@gradeui/ui 1.2.0 → 2.0.0

package/components/ui/background-fill.md

@@ -0,0 +1,135 @@
+---
+name: BackgroundFill
+import: "@gradeui/ui"
+props:
+  - type: "none" | "solid" | "gradient" | "image" | "video" | "shader" — which paint to render (required)
+  - color?: string — solid fill; a token name (`primary`, `card`, `muted`, `accent`, `secondary`, `destructive`, `background`, `transparent`) or any CSS colour
+  - gradient?: { from?; via?; to?; angle?; shape?; at?; size? } — stops are token names or CSS colours. shape: "linear" (default, uses `angle`, default 135°) | "radial" (uses `at` — CSS position like "top" / "30% 20%", default "center" — and optional `size` like "45rem 50rem", default farthest-corner)
+  - src?: string — image or video URL
+  - fit?: "cover" | "contain" | "fill" | "none" — object-fit for image/video (default "cover")
+  - position?: string — CSS object/background position (default "center")
+  - repeat?: boolean — tile the image (background-repeat) instead of a single <img>
+  - tileSize?: string — CSS background-size when repeating (e.g. "120px")
+  - preset?: string — shader preset id (see ThreeScene)
+  - fragmentShader?: string — custom GLSL (takes precedence over preset)
+  - palette?: Partial<{ primary; secondary; accent; background }> — shader palette overrides; wrap tokens as `oklch(var(--token))`
+  - postPreset?: string | PostPreset — shader post-FX
+  - opacity?: number — layer opacity 0–1
+  - blendMode?: CSS mix-blend-mode — blend against the frame behind it
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" — match the frame's radius so the paint clips cleanly
+when_to_use: 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 content. Use it as the first child of a `relative` frame; it paints an `absolute inset-0`, `z-0`, `pointer-events-none` layer, so content carrying `relative z-10` sits on top. This is the canonical way to give any container a rich background — never drop a full-bleed `<ThreeScene>` or `<img>` as a free-standing sibling. For a sized, in-flow media element (a hero card, a thumbnail), use ThreeScene / MediaSurface / VideoPlayer directly instead.
+composes_with: [AppShell, Card, Stack, Row, Grid (any relative container), ThreeScene (shader fill), MediaSurface]
+aliases: [background, fill, frame fill, backdrop, surface fill, background image, background video, background gradient, background shader, texture, paint]
+notes: |
+  ## The fill model
+
+  A background is a PROPERTY of a frame, not a node you select — exactly
+  like a fill in Figma / Paper. Select the frame; its Fill controls drive
+  this layer. BackgroundFill is the render boundary that makes that true.
+
+  ### Required frame setup
+
+  The parent frame must be `relative` (so the `absolute inset-0` layer
+  anchors to it) and ideally `overflow-hidden` (so the paint clips to the
+  frame's corners). Content that should sit ABOVE the fill needs its own
+  stacking context — wrap it `relative z-10`:
+
+    ```jsx
+    <Card className="relative overflow-hidden">
+      <BackgroundFill type="shader" preset="mesh" opacity={0.3} />
+      <div className="relative z-10">…content…</div>
+    </Card>
+    ```
+
+  ### Why a layer (and why pointer-events-none)
+
+  A solid colour does not strictly need a layer — it could be the frame's
+  own `background`. Every other paint (image, video, gradient, shader,
+  tiled texture) needs real pixels, so it renders as an absolutely-
+  positioned layer. The layer is `z-0` + `pointer-events-none` so it sits
+  behind content and never intercepts clicks. It carries
+  `data-gds-part="frame-fill"` + `aria-hidden` so Studio treats it as
+  chrome (the frame is the selectable unit) and assistive tech skips it.
+
+  ### Type cheat-sheet
+
+    - solid    — `color` (token or CSS colour). Cheapest.
+    - gradient — `gradient={{ from, via?, to, angle }}` for linear;
+                 `gradient={{ shape: "radial", at: "top", from, to }}` for a radial
+                 glow/wash. Tokens get wrapped in oklch() automatically.
+    - image    — `src` + `fit` / `position`; set `repeat` (+ `tileSize`) for a tiled texture.
+    - video    — `src` (autoplays muted + looped + inline).
+    - shader   — `preset` OR `fragmentShader`, + `palette` / `postPreset`. Delegates to ThreeScene.
+
+  Anti-patterns to avoid:
+
+  - DO NOT build gradients with arbitrary-value Tailwind classes —
+    `bg-[radial-gradient(45rem_50rem_at_top,theme(colors.indigo.50),white)]`
+    renders NOTHING in the Studio preview (no runtime Tailwind compiler) and
+    `theme(colors.*)` colours ignore the active Grade theme. Use
+    `type="gradient"` with token stops instead — themeable, and it always renders.
+  - DO NOT hand-roll `style={{ backgroundImage: "linear-gradient(…)" }}` on the
+    frame itself when a BackgroundFill child does the same job — the fill layer
+    keeps the paint selectable/editable as a Fill in Studio's inspector.
+
+  `opacity` + `blendMode` apply to every type — the same two controls as
+  the inspector's Blending section, so a loud shader/image can be dialled
+  back to a subtle wash behind text.
+---
+
+```jsx
+// Shader background behind a hero, dialled back so text stays readable.
+<section className="relative overflow-hidden rounded-xl">
+  <BackgroundFill
+    type="shader"
+    preset="mesh"
+    palette={{
+      primary: "oklch(var(--primary))",
+      secondary: "oklch(var(--accent))",
+      accent: "oklch(var(--primary))",
+      background: "oklch(var(--foreground))",
+    }}
+    opacity={0.35}
+  />
+  <div className="relative z-10 p-12">
+    <h1 className="text-4xl font-bold">Build at the speed of thought</h1>
+  </div>
+</section>
+```
+
+```jsx
+// Gradient wash on a card.
+<Card className="relative overflow-hidden">
+  <BackgroundFill type="gradient" gradient={{ from: "primary", to: "accent", angle: 120 }} opacity={0.18} />
+  <CardContent className="relative z-10">…</CardContent>
+</Card>
+```
+
+```jsx
+// Radial glow from the top of a hero — the token-true version of the
+// classic `radial-gradient(45rem 50rem at top, indigo-50, white)` wash.
+<section className="relative overflow-hidden">
+  <BackgroundFill
+    type="gradient"
+    gradient={{ shape: "radial", at: "top", size: "45rem 50rem", from: "primary", to: "background" }}
+    opacity={0.2}
+  />
+  <div className="relative z-10 py-24 text-center">…hero content…</div>
+</section>
+```
+
+```jsx
+// Image background, cover-fit, with a blend mode.
+<div className="relative h-64 overflow-hidden rounded-lg">
+  <BackgroundFill type="image" src="/hero.jpg" fit="cover" blendMode="multiply" />
+  <div className="relative z-10 p-6 text-white">Featured</div>
+</div>
+```
+
+```jsx
+// Tiled texture.
+<div className="relative overflow-hidden">
+  <BackgroundFill type="image" src="/noise.png" repeat tileSize="160px" opacity={0.08} />
+  <div className="relative z-10">…</div>
+</div>
+```

package/components/ui/checkbox-card.md

@@ -0,0 +1,43 @@
+---
+name: CheckboxCard
+import: "@gradeui/ui"
+props:
+  - checked? / defaultChecked? / onCheckedChange? — standard checkbox state
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the check; selection shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content instead of label/description
+when_to_use: Multi-select where each option is a whole selectable card (add-ons, feature toggles, opt-ins). The whole card is the control, so focus and the checked state live on the card surface. Standalone (not in a group). Static content only — never nest an interactive control inside. For a plain checkbox + label row use Field instead.
+composes_with: [Badge (in aside), MediaSurface (custom children), Stack / Grid (laying out several)]
+aliases: [checkbox card, selectable card, multi-select card, add-on card, feature card, opt-in card]
+---
+
+```jsx
+<div className="grid gap-3">
+  <CheckboxCard label="Priority support" description="24/7 response within an hour" defaultChecked />
+  <CheckboxCard label="Extended warranty" description="3 years parts and labour" />
+</div>
+```
+
+Indicator on the leading edge, with a Badge in the `aside` slot:
+
+```jsx
+<CheckboxCard
+  indicatorPosition="leading"
+  label="Priority support"
+  description="24/7 response within an hour"
+  aside={<Badge variant="info-soft">Popular</Badge>}
+  defaultChecked
+/>
+```
+
+No visible tick (selection reads from the card border + background), in a two-up grid:
+
+```jsx
+<div className="grid grid-cols-2 gap-3">
+  <CheckboxCard hideIndicator label="Email" description="Weekly digest" defaultChecked />
+  <CheckboxCard hideIndicator label="SMS" description="Critical alerts only" />
+</div>
+```

package/components/ui/checkbox.md

@@ -7,8 +7,8 @@ props:
   - defaultChecked?: boolean
   - disabled?: boolean
   - id?: string — bind a Label's htmlFor to this
-when_to_use: Binary on/off tied to a list (select multiple, agree to terms). Single on/off that controls a setting is better with Switch.
-composes_with: [Label (via htmlFor), Card, Form rows, Table (for row selection)]
+when_to_use: Binary on/off tied to a list (select multiple, agree to terms). Single on/off that controls a setting is better with Switch. For a label + description row, wrap in Field. When each option should be a whole selectable card (label + description, selected state on the card surface), use CheckboxCard.
+composes_with: [Label (via htmlFor), Field (label + description row), CheckboxCard (whole-card selectable option), Card, Form rows, Table (for row selection)]
 aliases: [checkbox, tickbox, tick box, check, multi-select item]
 ---
 

package/components/ui/dropdown-menu.md

@@ -7,7 +7,9 @@ props:
   - DropdownMenuTrigger: asChild?: boolean — usually wraps a Button
   - DropdownMenuContent: align? "start" | "center" | "end"; side? "top" | "right" | "bottom" | "left"; sideOffset? number
   - DropdownMenuContent: surface? (solid | translucent | glass | glass-strong) — what the menu surface is *made of*. `solid` (default) is `bg-popover`. `translucent` matches Apple HIG / iOS menu sheets. `glass` for menus floating over rich canvases.
+  - DropdownMenuContent: size? "default" | "sm" | "xs" — menu density; cascades to every item (Item, Checkbox, Radio, SubTrigger, Label) via context so a compact trigger gets a compact menu. Use "xs" in dense tool panels.
   - DropdownMenuSubContent: surface? (solid | translucent | glass | glass-strong) — same axis applied to nested submenu surfaces
+  - DropdownMenuSubContent: size? "default" | "sm" | "xs" — match the parent content's size down the tree
   - DropdownMenuItem: onSelect?, disabled?, asChild?, inset?
   - DropdownMenuCheckboxItem / DropdownMenuRadioItem: checked? / value, onCheckedChange? / onValueChange? (radio is on the group)
   - DropdownMenuSub / DropdownMenuSubTrigger / DropdownMenuSubContent: nested menu — sub-trigger shows children, sub-content holds the deeper items

package/components/ui/field.md

@@ -0,0 +1,26 @@
+---
+name: Field
+import: "@gradeui/ui"
+props:
+  - layout?: "option" | "setting" — option (default): control leads, text beside it; setting: text leads, control pinned trailing
+  - children: one bare control (Checkbox / RadioGroupItem / Switch) + Field.Label + Field.Description? + Field.Trailing? — order does not matter
+when_to_use: Pair a bare control with a label and optional description in a row, with id + aria-describedby wired automatically. Use layout="setting" for the classic settings row (label on the left, Switch on the right). For a selectable CARD where the whole surface is the control, use RadioCard / CheckboxCard / SwitchCard instead.
+composes_with: [Checkbox, RadioGroup, RadioGroupItem, Switch, Badge (inside Field.Trailing)]
+aliases: [field, form field, control row, label and description, two line checkbox, option row, setting row, toggle row]
+---
+
+```jsx
+<Field>
+  <Checkbox value="terms" />
+  <Field.Label>Accept terms</Field.Label>
+  <Field.Description>You agree to the privacy policy.</Field.Description>
+</Field>
+```
+
+```jsx
+<Field layout="setting">
+  <Field.Label>Email notifications</Field.Label>
+  <Field.Description>Weekly digest of activity.</Field.Description>
+  <Switch defaultChecked />
+</Field>
+```

package/components/ui/fill-picker.md

@@ -0,0 +1,36 @@
+---
+name: FillPicker
+import: "@gradeui/ui"
+props:
+  - value: FillValue — current paint ({ type, color?, gradient?, src?, fit?, repeat?, tileSize?, preset?, palette?, postPreset?, opacity? }) (required)
+  - onChange: (value: FillValue) => void — called on any change (required)
+when_to_use: Grade's paint picker — the control for choosing a frame's background fill, modelled on Figma's fill popover. A fill-type icon row (solid · gradient · image · pattern · video · shader) switches the panel below; a global opacity sits at the foot. Emits a FillValue that maps 1:1 onto BackgroundFill props. This is a Studio/inspector chrome control — pair it with BackgroundFill, which renders the chosen paint. Not for app content.
+composes_with: [BackgroundFill (renders the FillValue), Popover (host it in a popover), ShaderPresetPicker (the shader tab), the inspector Fill section]
+aliases: [fill picker, paint picker, background picker, fill chooser, fill popover]
+notes: |
+  Grade is token-led, so the solid + gradient tabs lead with theme-token
+  swatches (`primary`, `accent`, `secondary`, `muted`, `card`,
+  `background`, `destructive`, `transparent`) rather than a freeform HSV
+  square. The "pattern" tab is sugar for an image fill with `repeat` on.
+
+  The `FillValue` is the shared data shape: store it on a frame and feed
+  it straight to `<BackgroundFill {...value} />`. Solid colour can be a
+  className (`bg-<token>`) instead of a layer; every other type renders
+  as a `<BackgroundFill>` child of the frame.
+---
+
+```jsx
+const [fill, setFill] = useState({ type: "shader", preset: "mesh", opacity: 0.35 });
+
+<Popover>
+  <PopoverTrigger asChild><button>Fill</button></PopoverTrigger>
+  <PopoverContent className="w-[320px] p-3">
+    <FillPicker value={fill} onChange={setFill} />
+  </PopoverContent>
+</Popover>
+
+<div className="relative overflow-hidden">
+  <BackgroundFill {...fill} />
+  <div className="relative z-10">…content…</div>
+</div>
+```

package/components/ui/input.md

@@ -3,10 +3,13 @@ name: Input
 import: "@gradeui/ui"
 props:
   - type?: string (text | email | password | number | search | url | tel | date)
+  - size?: "default" | "sm" | "xs" — control density. `default` (h-9) for forms; `sm` (h-8) and `xs` (h-7) for dense tool panels like the inspector.
+  - startSlot?: ReactNode — adornment rendered inside the leading edge (icon, prefix, currency symbol). Non-interactive by default so clicks focus the input.
+  - endSlot?: ReactNode — adornment rendered inside the trailing edge (unit like "px", a clear button, a stepper). Same pointer rules as startSlot.
   - All native input HTML attrs (value, onChange, placeholder, disabled, required)
-when_to_use: Any single-line text entry. Always pair with a Label for accessibility.
+when_to_use: Any single-line text entry. Always pair with a Label for accessibility. Use startSlot/endSlot for icons, prefixes and units instead of hand-positioning absolute children; use size="sm"/"xs" in dense tool panels.
 composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
-aliases: [text field, textbox, textfield, form field, text input, secure field, search field, url field, number field, textinput, text input field, react native textinput]
+aliases: [text field, textbox, textfield, form field, text input, secure field, search field, url field, number field, textinput, text input field, react native textinput, unit input, input with icon]
 ---
 
 ```jsx
@@ -15,3 +18,25 @@ aliases: [text field, textbox, textfield, form field, text input, secure field,
   <Input id="email" type="email" placeholder="you@example.com" />
 </div>
 ```
+
+Slots — a leading icon and a trailing unit, no manual positioning:
+
+```jsx
+<Input
+  size="sm"
+  type="number"
+  placeholder="0"
+  startSlot={<Ruler className="size-4" />}
+  endSlot={<span className="text-xs text-muted-foreground">px</span>}
+/>
+```
+
+Sizes — `default` for forms, `sm` / `xs` for dense panels:
+
+```jsx
+<div className="grid gap-2">
+  <Input size="default" placeholder="Default (h-9)" />
+  <Input size="sm" placeholder="Small (h-8)" />
+  <Input size="xs" placeholder="Extra small (h-7)" />
+</div>
+```

package/components/ui/label.md

@@ -3,8 +3,9 @@ name: Label
 import: "@gradeui/ui"
 props:
   - htmlFor?: string — binds to the input's id
+  - size?: "default" | "sm" | "xs" — text size, mirrors Input/Select/Textarea so a field and its label scale together. default = text-sm; xs = 11px for dense tool panels.
   - All native label HTML attrs
-when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control.
+when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control. Match `size` to the field it labels (size="xs" label over a size="xs" input).
 composes_with: [Input, Textarea, Checkbox, Switch, RadioGroup, Select]
 aliases: [label, form label, field label, caption]
 ---

package/components/ui/logo.md

@@ -0,0 +1,59 @@
+---
+name: Logo
+import: "@gradeui/ui"
+subcomponents: []
+props:
+  - sources?: LogoSources — artwork keyed by lockup then appearance:
+      { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
+      Each slot is any node (inline <svg>, <img>, component). Omit entirely
+      and a neutral "Logo" placeholder renders (use this in prototypes
+      before real artwork exists).
+  - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
+  - mode?: "light" | "dark" (default "light") — the background the logo sits on
+  - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)
+  - size?: "sm" | "md" | "lg" | "xl" | number (default "md") — height; width is intrinsic
+  - label?: string — accessible name (brand name); becomes aria-label + role="img"
+  - decorative?: boolean — aria-hidden when the name is already nearby
+  - href?: string — renders the logo as a link (logo-links-home)
+  - className?: string
+when_to_use: A brand mark with built-in variations — a square mark for tight
+  spaces, a horizontal lockup for headers, monochrome for busy/inverted
+  surfaces. Reach for Logo in toolbars, sidenav headers, and footers instead
+  of dropping a bare <img>, so the lockup and on-dark/on-light treatment are
+  switchable by prop. The artwork is supplied by the consumer; Logo just picks
+  the right slot for the context.
+composes_with: [AppShell, AppShellHeader, Sidebar, SidebarHeader, Row, Stack]
+aliases: [logo, brand, brandmark, wordmark, lockup, brand logo, app logo, logotype]
+---
+
+```jsx
+// Sidenav header: square mark when collapsed, horizontal when expanded.
+// Supply your own artwork per slot; here inline SVGs stand in.
+<Logo
+  lockup="horizontal"
+  mode="dark"
+  size="md"
+  label="Acme"
+  sources={{
+    square: { light: <AcmeSquare />, dark: <AcmeSquareWhite /> },
+    horizontal: { light: <AcmeWide />, dark: <AcmeWideWhite /> },
+    icon: { mono: <AcmeGlyph /> },
+  }}
+/>
+```
+
+### Anti-patterns
+
+DO NOT drop a bare `<img src="logo.png">` in a toolbar/sidenav/footer when you
+want light/dark or square/horizontal switching — use `<Logo>` so the variant
+is a prop.
+
+DO NOT invert a colour logo with a CSS filter to fake a dark version — supply
+the brand's real `dark` artwork in the `sources` slot.
+
+DO NOT set both `label` and `decorative` — `decorative` hides the logo from
+assistive tech; `label` names it. Pick one (name it unless the brand name is
+already in the DOM right beside it).
+
+DO NOT hardcode a width — `size` sets the height and the artwork keeps its own
+aspect ratio (square/icon are 1:1, horizontal stays wide).

package/components/ui/message.md

@@ -13,6 +13,7 @@ props:
   - threadCount?: number — renders a "N replies" link affordance below the body
   - onThreadClick?: () => void — handler for the threadCount affordance
   - align?: "start" | "end" — `start` (default) puts the avatar on the left; `end` mirrors for "your messages" in DM threads
+  - density?: "default" | "compact" — `default` is the canonical chat / channel-feed rhythm; `compact` tightens text sizes + gaps for dense side panels (Studio comments, activity feeds). Pair with `Avatar size="xs"` for the tightest stack.
   - children: ReactNode — body content (plain text or rich nodes)
   - className?: string
 when_to_use: |
@@ -156,6 +157,39 @@ aliases: [
 </Stack>
 ```
 
+```jsx
+// Compact density — for narrow side panels (Studio Comments tab,
+// activity feeds, notification rows). Notice the smaller Avatar size
+// pairs naturally with density="compact".
+<Stack gap="sm">
+  <Message
+    density="compact"
+    author="alice"
+    timestamp="2m ago"
+    edited="· edited 1m ago"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Splitting this into two PRs makes the review tractable.
+  </Message>
+  <Message
+    density="compact"
+    author="ben"
+    timestamp="1m ago"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="amber">B</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Agreed. I'll take the schema PR.
+  </Message>
+</Stack>
+```
+
 ## Anti-patterns
 
 ```jsx

package/components/ui/radio-card.md

@@ -0,0 +1,41 @@
+---
+name: RadioCard
+import: "@gradeui/ui"
+props:
+  - value: string (required) — the radio value
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the dot; selection shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content (image, custom layout) instead of label/description
+when_to_use: Single-select where each option is a whole selectable card (shipping options, plan picker, onboarding choices). The whole card is the control, so focus and the checked state live on the card surface and the entire card is clickable. MUST sit inside a RadioGroup (keeps roving focus + single-select). Static content only — never nest an interactive control (Slider/Input/Button/link) inside. For a plain radio + label row use Field instead.
+composes_with: [RadioGroup (required parent), Badge (in aside), MediaSurface (custom children)]
+aliases: [radio card, selectable card, option card, plan picker, choice card, pricing tier, segmented choice card]
+---
+
+```jsx
+<RadioGroup defaultValue="standard" className="grid gap-3">
+  <RadioCard value="standard" label="Standard" description="4–10 business days" />
+  <RadioCard value="fast" label="Fast" description="2–5 business days" />
+  <RadioCard value="next-day" label="Next day" description="1 business day" />
+</RadioGroup>
+```
+
+Indicator on the leading edge instead of trailing:
+
+```jsx
+<RadioGroup defaultValue="standard" className="grid gap-3">
+  <RadioCard value="standard" indicatorPosition="leading" label="Standard" description="4–10 business days" />
+  <RadioCard value="fast" indicatorPosition="leading" label="Fast" description="2–5 business days" />
+</RadioGroup>
+```
+
+No visible dot (selection reads from the card border + background), laid out in a grid via className on the group:
+
+```jsx
+<RadioGroup defaultValue="m" className="grid grid-cols-2 gap-3">
+  <RadioCard value="s" hideIndicator label="Small" description="Up to 10 seats" />
+  <RadioCard value="m" hideIndicator label="Medium" description="Up to 50 seats" />
+</RadioGroup>
+```

package/components/ui/radio-group.md

@@ -12,8 +12,8 @@ props:
   - RadioGroupItem: value: string — what the group emits when this item is picked
   - RadioGroupItem: id?: string — pair with a <Label htmlFor> for click-on-label
   - RadioGroupItem: disabled?: boolean
-when_to_use: 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 cards. For 5+ options use Select. For a segmented control as part of a toolbar use ToggleGroup. For yes/no use Switch.
-composes_with: [Label (paired with each item via htmlFor), Stack (vertical list), Card (radio card pattern)]
+when_to_use: 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 cards. When each option should be a whole clickable card (label + description, selected state on the card), use RadioCard inside the RadioGroup instead of a Card with a radio in the corner. For a plain label + description row, wrap RadioGroupItem in Field. For 5+ options use Select. For a segmented control as part of a toolbar use ToggleGroup. For yes/no use Switch.
+composes_with: [Label (paired with each item via htmlFor), Field (label + description row), RadioCard (whole-card selectable option), Stack (vertical list)]
 aliases: [radio group, radio buttons, single-choice, pricing options, payment method, radio buttons, radio control, single-select]
 ---
 

package/components/ui/screen-animator.md

@@ -0,0 +1,54 @@
+---
+name: ScreenAnimator
+import: "@gradeui/ui"
+subcomponents: []
+props:
+  - shots?: Array<{ zoom?, cx?, cy?, hold?, trans?, label? }> — the tour. Each
+      shot is a zoom (1 = fit, >1 push in), focal point cx/cy (0..1 fractions of
+      the content), hold (ms dwell), trans (ms glide-in), and a caption label.
+      Omit for a static framed view.
+  - autoplay?: boolean (default true)
+  - loop?: boolean (default true) — fly in → shots → back to start → exit → repeat
+  - controls?: boolean (default true) — play / pause / restart transport
+  - spotlight?: boolean (default false) — opt in to dim the edges (vignette) when pushed in
+  - cursor?: boolean (default true) — synthetic cursor pulse on detail shots
+  - enter?: boolean (default true) — fly in from offscreen on start
+  - stage?: string — CSS background of the stage behind the screen (default dark)
+  - backdrop?: React.ReactNode — a live layer behind the content (image, gradient, or a <ThreeScene> shader)
+  - className?: string
+  - children: React.ReactNode (the screen to animate)
+when_to_use: Wrap ANY screen or section in a directed camera — a "live demo
+  director". Give it a list of shots and it tours them (zoom + pan) over the
+  live, still-interactive content, with a focus spotlight, captions, a synthetic
+  cursor, and play/pause. Use it to turn a built screen into an auto-playing
+  product demo (embed it, or drop it on a marketing page). It's the live,
+  editable, re-renderable answer to a screen-recording video.
+composes_with: [AppShell, ThreeScene, Card, Grid, the whole component set (it wraps a screen)]
+aliases: [screen animator, camera, camera tour, director, demo, product demo, zoom pan, spotlight, ken burns, presenter]
+---
+
+```jsx
+// Wrap a live screen; the camera tours the shots and loops.
+<ScreenAnimator
+  shots={[
+    { zoom: 1, cx: 0.5, cy: 0.5, hold: 2400, label: "Overview" },
+    { zoom: 2.4, cx: 0.2, cy: 0.34, hold: 2600, label: "Revenue up 24%" },
+    { zoom: 1.8, cx: 0.5, cy: 0.6, hold: 2800, label: "Pipeline" },
+  ]}
+  backdrop={<ThreeScene preset="aurora" />}
+>
+  <Dashboard />
+</ScreenAnimator>
+```
+
+### Anti-patterns
+
+DO NOT use it as a layout wrapper — it positions `absolute inset-0` and takes
+over the frame. It's for a whole screen/section you want to direct, not a div.
+
+DO NOT hand-tune `trans`/`hold` per shot unless you need to — the defaults
+(soft settle on overview, snappier push on detail) read well. `cx`/`cy` are the
+knobs that matter; they're fractions of the screen (0 = left/top, 0.5 = centre).
+
+DO NOT worry about reduced motion — it settles on the starter frame and stops
+moving automatically under `prefers-reduced-motion`.

package/components/ui/select.md

@@ -4,11 +4,11 @@ import: "@gradeui/ui"
 subcomponents: [SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator]
 props:
   - Select: value?, onValueChange?, defaultValue?, disabled? — Radix root
-  - SelectTrigger: wraps the clickable control; nest SelectValue inside
+  - SelectTrigger: size?: "default" | "sm" | "xs" — control density; wraps the clickable control, nest SelectValue inside
   - SelectValue: placeholder?: string — text when nothing is selected
-  - SelectContent: accepts items via children
-  - SelectItem: value: string — required; content is the label
-when_to_use: Single-choice from 3+ known options. Fewer than 3 → RadioGroup. Huge list with search → use a Combobox (not in DS yet). Multi-select → not supported by this primitive.
+  - SelectContent: size?: "default" | "sm" | "xs" — menu density; cascades to every SelectItem inside via context so a compact trigger gets a compact menu. Accepts items via children.
+  - SelectItem: value: string — required; content is the label. Inherits density from SelectContent.
+when_to_use: Single-choice from 3+ known options. Fewer than 3 → RadioGroup. Huge list with search → use a Combobox (not in DS yet). Multi-select → not supported by this primitive. In dense tool panels, set size="xs" on BOTH the trigger and the content so the closed control and open menu match.
 composes_with: [Label (above SelectTrigger), Form, Card]
 aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup picker, picker view, rnpickerselect, react native picker, native picker]
 ---
@@ -22,3 +22,15 @@ aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup
   </SelectContent>
 </Select>
 ```
+
+Compact, for dense panels — match the trigger and menu density:
+
+```jsx
+<Select defaultValue="md">
+  <SelectTrigger size="xs"><SelectValue /></SelectTrigger>
+  <SelectContent size="xs">
+    <SelectItem value="sm">Small</SelectItem>
+    <SelectItem value="md">Medium</SelectItem>
+  </SelectContent>
+</Select>
+```

package/components/ui/switch-card.md

@@ -0,0 +1,30 @@
+---
+name: SwitchCard
+import: "@gradeui/ui"
+props:
+  - checked? / defaultChecked? / onCheckedChange? — standard switch state
+  - label?: ReactNode — title line
+  - description?: ReactNode — secondary line
+  - aside?: ReactNode — slot before the indicator (a Badge, price, hint)
+  - hideIndicator?: boolean — hide the switch glyph; state shown by the card border + background
+  - indicatorPosition?: "leading" | "trailing" — default trailing
+  - children?: ReactNode — arbitrary static content instead of label/description
+when_to_use: A prominent on/off setting presented as a whole selectable card. The whole card is the switch, so the toggled state lives on the card surface. Standalone. For a row of compact settings (label left, small Switch right) use Field layout="setting" instead — SwitchCard is for the heavier, card-sized toggle.
+composes_with: [Badge (in aside), Stack (stacking several)]
+aliases: [switch card, toggle card, setting card, feature toggle card]
+---
+
+```jsx
+<SwitchCard label="Auto-renew" description="Renew this plan automatically each month" defaultChecked />
+```
+
+Indicator on the leading edge:
+
+```jsx
+<SwitchCard
+  indicatorPosition="leading"
+  label="Auto-renew"
+  description="Renew this plan automatically each month"
+  defaultChecked
+/>
+```

package/components/ui/switch.md

@@ -7,8 +7,8 @@ props:
   - defaultChecked?: boolean
   - disabled?: boolean
   - id?: string
-when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox.
-composes_with: [Label (via htmlFor), Card (settings rows)]
+when_to_use: Instant on/off setting ("Enable notifications", "Dark mode"). Commits on toggle — no submit button needed. For selecting-from-a-list use Checkbox. For a settings row (label + description on the left, Switch on the right) use Field layout="setting". For a prominent on/off presented as a whole selectable card, use SwitchCard.
+composes_with: [Label (via htmlFor), Field (layout="setting" settings row), SwitchCard (whole-card toggle), Card (settings rows)]
 aliases: [toggle, switch, on/off switch, ios toggle, toggle switch, switch control, react native switch]
 ---
 

package/components/ui/textarea.md

@@ -2,8 +2,9 @@
 name: Textarea
 import: "@gradeui/ui"
 props:
+  - size?: "default" | "sm" | "xs" — control density, mirrors Input. default = min-h-80 / text-sm; sm and xs shrink the min-height + padding for dense panels.
   - All native textarea HTML attrs (rows, value, onChange, placeholder, disabled)
-when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead.
+when_to_use: Multi-line text entry (descriptions, messages, comments). Pair with a Label. Single-line input → use Input instead. Use size="sm"/"xs" in dense tool panels.
 composes_with: [Label, Form, Card (in CardContent)]
 aliases: [text area, multiline, comment box, message field, text editor, multi-line text, multiline input, multiline text field, comments box, multiline textinput]
 ---