@gradeui/ui 4.0.1 → 4.1.0

package/AGENTS.md

@@ -0,0 +1,25 @@
+# Using @gradeui/ui (for AI agents)
+
+You are generating UI with the Grade Design System. This package is **self-describing** —
+everything you need ships in the installed package. Read the comprehensive spec first:
+
+- **`@gradeui/ui/DESIGN.md`** — the whole design system in one file: foundations
+  (themes, colour scopes, expressive accents, typography, spacing) + every component
+  sidecar (when_to_use, props, examples). **Read this before generating markup.**
+- **`@gradeui/ui/contracts`** — programmatic prop schemas: `import { COMPONENT_CONTRACTS } from "@gradeui/ui/contracts"`.
+- **`@gradeui/ui/styles.css`** — precompiled styles (or wire `@gradeui/ui/styles/globals.css` into Tailwind v4).
+
+## The one rule you must not break
+
+A page is an ordered stack of `Section` bands, and **every `Section` wraps a `Container`**:
+
+```jsx
+<Section scope="inverse" pad="xl">
+  <Container maxW="lg">{/* content */}</Container>
+</Section>
+```
+
+Full-bleed = `<Container maxW="full">`, never omitting the Container. This holds for
+app content regions too, not just marketing. **Never** hand-roll
+`<section className="py-20">` or `<div className="max-w-7xl mx-auto px-6">` — that
+div-soup is exactly what `Section` + `Container` replace.

package/DESIGN.index.md

@@ -0,0 +1,88 @@
+<!-- GENERATED — pnpm -F @gradeui/ui generate:design -->
+# Grade component index
+
+A cheap scan of all 79 components. Read the foundations + this
+index first; then pull only the sidecars you need from `components/ui/<name>.md`
+(or the full `@gradeui/ui/DESIGN.md`). Foundations: themes, color-scopes, expressive, typography, spacing-layout.
+
+| component | when to use |
+| --- | --- |
+| `Accordion` | Long-form content that would overwhelm if shown all at once — FAQs, settings groups, "what's included" sections, nested help. |
+| `AIChatComposer` | The reusable "input card" for any chat surface — auto-growing textarea, image attachments via paperclip and clipboard paste, attachment chips with previews, Sen |
+| `AIChat` | A flexible chat block — header + scrollable message list + composer. |
+| `AppShell` | | |
+| `Avatar` | User/entity identity for PEOPLE — profile pictures, author rows, member lists, account headers. |
+| `BackgroundFill` | The background *paint* of a frame — a generative shader, image, video, gradient, repeating texture, or solid token rendered as a layer BEHIND the frame's conten |
+| `Badge` | Compact status chips, counts, tags, pills. |
+| `Banner` | A full-width horizontal strip surfacing system-level state, announcements, or first-run guidance — "you're previewing a draft", "investigating incident", "new f |
+| `Breadcrumb` | Reach for Breadcrumb whenever a screen sits inside a hierarchy and you want the path back to the top to be visible. |
+| `Button` | Any clickable action. |
+| `Calendar` | An inline date grid — date-of-birth pickers in profile forms, scheduling screens with a month view, range selection in reporting filters. |
+| `Callout` | Inline, ambient, non-blocking status/feedback that sits inside the layout flow. |
+| `Card` | Grouped content with a distinct surface — settings panels, dashboard tiles, list-of-cards layouts, marketing hero containers, AI suggestion overlays. |
+| `Carousel` | Anywhere a horizontal stack of slides cycles automatically or on user input — marketing hero rotations, featured rails on a TV / streaming app, onboarding tours |
+| `ChartContainer` | Reporting dashboards, single-purpose analytics cards (revenue, conversions, active users), or anywhere you'd otherwise hand-roll a Recharts setup. |
+| `CheckboxCard` | Multi-select where each option is a whole selectable card (add-ons, feature toggles, opt-ins). |
+| `Checkbox` | Binary on/off tied to a list (select multiple, agree to terms). |
+| `Code` | Read-only code surface for marketing heroes, docs, changelog entries, AI-output displays. |
+| `Collapsible` | A single show/hide reveal — "Show advanced settings" rows, expandable inline help, "More details" sections inside cards. |
+| `ColorPicker` | The token-led single-select colour picker — the focused "pick one colour token" sibling of FillPicker's solid tab. |
+| `Combobox` | Single-pick searchable picker — the single-select sibling of MultiSelect and the Linear "selectable badge" pattern (status / priority / assignee). |
+| `Command` | A searchable list of actions or destinations — global ⌘K palettes, "jump to" inputs, account switchers with filter. |
+| `Composer` | | |
+| `DataView` | One dataset, drawn as a table, a list of cards, or a grid — without re-typing the TanStack boilerplate (sortable headers, flexRender, selection, view switch) on |
+| `DatePicker` | Any date or date-range entry. |
+| `Dialog` | Modal interruptions — confirmations, focused forms, detail views, AI suggestion sheets. |
+| `DropdownMenu` | A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. |
+| `Field` | Pair a bare control with a label and optional description in a row, with id + aria-describedby wired automatically. |
+| `FillPicker` | Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. |
+| `Flex` | The unopinionated flexbox primitive — reach for Flex when Stack, Row, or Grid don't quite fit. |
+| `grade-loader` |  |
+| `GradientEditor` | Edit a multi-stop CSS gradient with token-led stops. |
+| `Grid` | 2D layouts where Stack (vertical) and Row (horizontal) don't fit — stat-card grids, feature tiles, pricing columns, photo grids. |
+| `HoverCard` | Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups, layer-thumbnail peeks. |
+| `Input` | Any single-line text entry. |
+| `Label` | Every Input / Textarea / Checkbox / Switch / RadioGroup. |
+| `Logo` | ALWAYS use <Logo> wherever a screen carries a brand mark — |
+| `Map` | Any layout that needs a real map — listings (real estate, Airbnb-style), fleet/logistics dashboards, store locators, anywhere a user picks a location from a vie |
+| `MediaSurface` | The canonical media slot for ALL non-person imagery — album art, posters, hero images, landscape photos, video and 3D containers. |
+| `Message` | | |
+| `Motion` | A directed sequence of scenes on one persistent stage — the |
+| `MultiSelect` | | |
+| `Popover` | A floating panel anchored to a trigger that contains interactive content — date pickers, color pickers, filter pickers, "more info" panels, inline forms. |
+| `Progress` | Determinate progress — file uploads, multi-step forms, quota meters. |
+| `PropertyList` | Read-only display of the properties of a SINGLE item — detail panels, inspectors, "about this" cards, order/record summaries. |
+| `RadioCard` | Single-select where each option is a whole selectable card (shipping options, plan picker, onboarding choices). |
+| `RadioGroup` | A small set of mutually-exclusive options where the user needs to SEE all of them at once — pricing tiers (3-4 options), shipping speed, payment method radio ca |
+| `Resizable` | A multi-pane layout where the user wants to drag the divider — Slack/Mail-style list+detail, IDE editor+terminal, side-by-side compare view. |
+| `RivePlayer` | Rive runtime wrapped in the shared media surface. |
+| `Row` | Horizontal composition — button groups, inline form rows, logo + nav rows, anything on one line. |
+| `ScreenAnimator` | Wrap ANY screen or section in a directed camera — a "live demo |
+| `ScrollArea` | Bounded content that needs custom scroll chrome — sidebars with long item lists, chat transcripts, table panels inside a dashboard, anywhere the OS scrollbar wo |
+| `SectionBlock` | The top-level container for a marketing page section — hero, feature row, pricing table, testimonial strip, FAQ section. |
+| `Section` | THE page scaffold. |
+| `Select` | Single-choice from 3+ known options. |
+| `SelectionCard` | A selectable option where the WHOLE card is the control — plan pickers, shipping/payment options, onboarding choices, settings toggles. |
+| `Separator` | Light divider between sibling blocks in a Card, list, or header. |
+| `ShaderControls` | Render a `ControlSpec[]` schema into a DS-native control panel — the single renderer behind shader params, the post-processing stack, and any effect layer (they |
+| `ShaderPresetPicker` | Runtime gallery of shader presets — click to select. |
+| `ShaderPresetPreview` | Thumbnail-sized preview card for a shader preset. |
+| `Sheet` | A panel that slides in from a screen edge — mobile nav drawers, side panels for editing a single record without leaving the list, filter trays on small viewport |
+| `Sidebar` | Vertical app navigation. |
+| `Skeleton` | Loading placeholder for content whose shape you know. |
+| `Slider` | A continuous-ish numeric pick — volume, opacity, font size, price-range filters. |
+| `Sortable` | Drag-to-reorder lists, kanban-column reordering, sortable shelves, tab strips the user can rearrange. |
+| `Stack` | Default top-level layout inside the main slot when composing two or more stacked regions (hero + content + footer, auth card + subtext, etc.). |
+| `Swatch` | Showing a colour as a small chip — brand-pop strips, palette / accent pickers, theme previews, token galleries, "pick a colour" rows. |
+| `SwitchCard` | A prominent on/off setting presented as a whole selectable card. |
+| `Switch` | Instant on/off setting ("Enable notifications", "Dark mode"). |
+| `Table` | Structured tabular data — rows × columns with alignment requirements. |
+| `Tabs` | A small set of peer views within one surface (2–5 tabs). |
+| `Textarea` | Multi-line text entry (descriptions, messages, comments). |
+| `ThreeScene` | WebGL primitive for shader backgrounds, generative visuals, and bespoke three.js scenes. |
+| `Toaster` | Transient, non-blocking feedback that confirms or warns about an action — "Saved", "Failed to upload", "Copied to clipboard", "Invitation sent". |
+| `ToggleGroup` | A small set of mutually-exclusive (`type="single"`) or independent (`type="multiple"`) binary options that live side-by-side as a segmented control — viewport s |
+| `Toggle` | A standalone on/off button — Bold/Italic in a toolbar, "Show grid" in a header, single binary toggle that doesn't belong inside a Switch row. |
+| `Toolbar` | | |
+| `Tooltip` | A short, non-essential label that explains a control on hover/focus — icon-only buttons in toolbars, abbreviated column headers, status dots. |
+| `VideoPlayer` | HTML5 video wrapped in the shared media surface. |