@gradeui/ui 0.10.0 → 1.1.0

package/components/ui/dialog.md

@@ -5,25 +5,129 @@ subcomponents: [DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogD
 props:
   - Dialog: open?, onOpenChange? — Radix controlled/uncontrolled pattern
   - DialogTrigger: asChild? (wrap a Button)
+  - DialogContent: surface? (solid | translucent | glass | glass-strong) — what the modal panel is *made of*. Defaults to `solid` (opaque `bg-background`). `glass` lets the page show through softly — pairs with rich backdrops or AI-suggestion modals.
   - DialogContent: accepts native div HTML attrs
   - DialogFooter: used for action rows
-when_to_use: Modal interruptions — confirmations, focused forms, detail views. For non-blocking messaging use Alert or Sonner. Always include DialogTitle (a11y requirement).
-composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent]
-aliases: [modal, popup, overlay]
+when_to_use: Modal interruptions — confirmations, focused forms, detail views, AI suggestion sheets. Dialog is the right primitive for Apple HIG / React Native "Alert" (modal) semantics. For non-blocking inline messaging use Callout; for transient notifications use Toaster (Sonner). Always include DialogTitle (a11y requirement).
+composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent, Code (for changelog / diff modals), MediaSurface (for image / preview modals)]
+aliases: [modal, popup, overlay, alert, system alert, alert dialog, modal dialog, confirm dialog, react native modal, rn alert, glass modal, frosted modal, ai suggestion modal]
 ---
 
+DialogContent sits at elevation-5 (the dialog tier). The Presence axes still apply: `surface` picks the material, `gds-aura-*` adds radiating state, the overlay scrim handles dimming the page.
+
+---
+
+### Scenario 1 — Destructive confirmation (default opaque)
+
+You're confirming a destructive action: delete, discard, revoke. Keep the dialog opaque — the user should focus on the decision, not the page behind it. The raised Button + tonal `--btn-glow` keeps the destructive action visually heavy without going red-everywhere.
+
 ```jsx
 <Dialog>
-  <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>
+  <DialogTrigger asChild><Button variant="outline">Delete project</Button></DialogTrigger>
   <DialogContent>
     <DialogHeader>
       <DialogTitle>Delete project?</DialogTitle>
-      <DialogDescription>This cannot be undone.</DialogDescription>
+      <DialogDescription>
+        This will remove the project, its screens, and all comments. This cannot be undone.
+      </DialogDescription>
     </DialogHeader>
     <DialogFooter>
       <Button variant="outline">Cancel</Button>
-      <Button variant="destructive">Delete</Button>
+      <Button variant="raised" style={{ "--btn-glow": "var(--destructive)" }}>
+        Delete forever
+      </Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+No `surface` prop — `solid` is the right answer for high-stakes confirmations. The opacity reinforces "stop and decide".
+
+---
+
+### Scenario 2 — Glass modal over a rich canvas (creative-tool aesthetic)
+
+You're building a creative tool — Studio, a presentation builder, a photo editor. The canvas behind the dialog is visually rich (a layout in progress, an image, generative art). A solid dialog cuts a hole through the work. Glass keeps the work visible while focusing attention.
+
+```jsx
+<Dialog>
+  <DialogTrigger asChild><Button>Add a comment</Button></DialogTrigger>
+  <DialogContent surface="glass" className="shadow-elevation-5">
+    <DialogHeader>
+      <DialogTitle>Comment on Hero section</DialogTitle>
+      <DialogDescription>
+        Visible to your team and to Studio when it next regenerates this screen.
+      </DialogDescription>
+    </DialogHeader>
+    <Textarea placeholder="What should change about this section?" />
+    <DialogFooter>
+      <Button variant="ghost">Cancel</Button>
+      <Button>Post comment</Button>
     </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
+
+`surface="glass"` is the canvas-tool signature. The user keeps spatial awareness of what they were just looking at; the dialog feels like a layer above the work, not a separate page.
+
+---
+
+### Scenario 3 — AI suggestion sheet (translucent + aura)
+
+Studio is offering a suggestion. It shouldn't feel as heavy as a destructive confirmation — it's a recommendation, not a demand. Translucent (no blur) is lighter than glass; the aura ring announces "this is from an AI agent".
+
+```jsx
+<Dialog open={hasSuggestion}>
+  <DialogContent
+    surface="translucent"
+    className="shadow-elevation-5 gds-aura-ring"
+    style={{ "--aura-color": "var(--selected-glow)" }}
+  >
+    <DialogHeader>
+      <DialogTitle>Three buttons could align</DialogTitle>
+      <DialogDescription>
+        Toolbar buttons match TabsList height when size="sm". Apply across all three?
+      </DialogDescription>
+    </DialogHeader>
+
+    <Card surface="glass" className="shadow-elevation-2">
+      <CardContent>
+        <Code source={suggestedDiff} language="tsx" diff={{ added: [2, 3, 4] }} bare />
+      </CardContent>
+    </Card>
+
+    <DialogFooter>
+      <Button variant="ghost">Dismiss</Button>
+      <Button>Apply suggestion</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Three Presence axes layered: `surface="translucent"` (material), `shadow-elevation-5` (depth), `gds-aura-ring` (state signal). The inner Card uses `surface="glass"` for a different reason — to read as a nested floating preview rather than a flat content block.
+
+---
+
+### Anti-patterns
+
+**DO NOT use `surface="glass"` for destructive confirmations.** Glass implies "the page is still alive behind this" — users will be less decisive. Opaque is the right material for high-stakes choices.
+
+**DO NOT roll glass by hand on DialogContent.**
+
+```jsx
+{/* ❌ Misses edge highlight, no theme tuning, no inspector knob. */}
+<DialogContent className="bg-background/50 backdrop-blur-md">
+
+{/* ✅ */}
+<DialogContent surface="glass">
+```
+
+**DO NOT skip DialogTitle.** Screen readers announce the title on open — without it the dialog reads as "[unlabeled dialog]". If the design has no visible title, wrap a visually-hidden title:
+
+```jsx
+<DialogHeader>
+  <DialogTitle className="sr-only">Image preview</DialogTitle>
+</DialogHeader>
+```
+
+**DO NOT use Dialog for ambient messaging.** Toast for transient ("Saved"), Callout for inline ("3 unread comments"), Dialog only when the user MUST respond before continuing.

package/components/ui/dropdown-menu.md

@@ -6,17 +6,26 @@ props:
   - DropdownMenu: open?, defaultOpen?, onOpenChange?, modal? (default true)
   - 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.
+  - DropdownMenuSubContent: surface? (solid | translucent | glass | glass-strong) — same axis applied to nested submenu surfaces
   - 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
   - DropdownMenuShortcut: children — right-aligned kbd hint
 when_to_use: A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. For a full searchable list, use Command. For ONE primary action plus a secondary, use a Button next to a smaller ghost Button instead of a dropdown.
 composes_with: [Button (as trigger asChild), Avatar (user menu), Card (overflow on a tile), Tooltip (on the trigger)]
-aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu]
+aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu, menu, pull-down menu, pulldown menu, context menu, popup menu, actions menu, glass menu, frosted menu, ios menu, hig menu]
 ---
 
+DropdownMenuContent sits at elevation-4. Pick the material from the scenarios below — the `surface` prop is the discoverable lever.
+
+---
+
+### Scenario 1 — Overflow menu on a row/card (default opaque)
+
+The canonical "…" menu attached to a row or card. The content behind is a list — readability of the menu items matters more than seeing what's underneath.
+
 ```jsx
-// Overflow menu on a card/row — trigger an icon-only Button.
 <DropdownMenu>
   <DropdownMenuTrigger asChild>
     <Button variant="ghost" size="icon" aria-label="Open menu">
@@ -26,6 +35,7 @@ aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action
   <DropdownMenuContent align="end">
     <DropdownMenuItem onSelect={onDuplicate}>
       <Copy /> Duplicate
+      <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
     </DropdownMenuItem>
     <DropdownMenuItem onSelect={onShare}>
       <Share2 /> Share
@@ -37,3 +47,88 @@ aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action
   </DropdownMenuContent>
 </DropdownMenu>
 ```
+
+`solid` is the right default. Menu items are read-targets — give them a clean opaque background.
+
+---
+
+### Scenario 2 — Translucent menu (iOS / Apple HIG)
+
+You want the iOS-native menu feel: light translucency that picks up the colour of whatever's beneath without committing to a full blur. The Apple HIG canonical material for context menus.
+
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon"><MoreVertical /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent
+    surface="translucent"
+    className="shadow-elevation-4"
+    align="end"
+  >
+    <DropdownMenuLabel>Sort by</DropdownMenuLabel>
+    <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+      <DropdownMenuRadioItem value="recent">Most recent</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="alpha">A–Z</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="size">Size</DropdownMenuRadioItem>
+    </DropdownMenuRadioGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+82% opacity. The background tints the menu without demanding the user filter it out.
+
+---
+
+### Scenario 3 — Glass menu in a canvas tool
+
+Studio's layer-context menu, an image editor's right-click, a slide-tool insert menu. The canvas behind is the work. Glass lets the menu float without cutting a hole through the work.
+
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon"><Plus /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent
+    surface="glass"
+    className="shadow-elevation-4 w-56"
+    align="start"
+  >
+    <DropdownMenuLabel>Insert</DropdownMenuLabel>
+    <DropdownMenuItem><LayoutTemplate /> Layout</DropdownMenuItem>
+    <DropdownMenuItem><Image /> Media</DropdownMenuItem>
+    <DropdownMenuItem><Code2 /> Code block</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger><Sparkles /> AI suggestion</DropdownMenuSubTrigger>
+      <DropdownMenuSubContent surface="glass" className="shadow-elevation-4">
+        <DropdownMenuItem>Layout variant</DropdownMenuItem>
+        <DropdownMenuItem>Tone shift</DropdownMenuItem>
+        <DropdownMenuItem>Density pass</DropdownMenuItem>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Pass `surface="glass"` to BOTH the root content AND the sub-content — submenus default to `solid` so a glass parent with an opaque child looks broken. Match the surface consistently down the menu tree.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand on DropdownMenuContent.**
+
+```jsx
+{/* ❌ Misses the iOS-native edge highlight + theme blur tuning. */}
+<DropdownMenuContent className="bg-popover/55 backdrop-blur-md">
+
+{/* ✅ */}
+<DropdownMenuContent surface="glass">
+```
+
+**DO NOT mix surfaces between content and sub-content.** A glass root with a solid submenu (or vice-versa) reads as two materials competing for attention. Pick one for the whole tree.
+
+**DO NOT use DropdownMenu for searchable lists.** Past ~7 items the menu becomes a scrollable list and the right primitive is Command (a search-first list inside a Popover or Dialog).
+
+**DO NOT put long-form text in menu items.** Items are action labels — verbs. If you need help text, that's a Popover surface, not a menu.

package/components/ui/flex.md

@@ -13,7 +13,7 @@ props:
   - children: React.ReactNode
 when_to_use: The unopinionated flexbox primitive — reach for Flex when Stack, Row, or Grid don't quite fit. Specifically when you need reverse direction (`row-reverse` / `col-reverse`), CSS defaults instead of Row's baked-in `items-center gap-md`, or baseline alignment. Otherwise prefer Stack / Row / Grid — they're easier to read and tuned for the 95% case. Flex is the escape hatch, not the default.
 composes_with: [any content component]
-aliases: [flex, flexbox, flex container, hstack, vstack, horizontal, vertical]
+aliases: [flex, flexbox, flex container, hstack, vstack, horizontal, vertical, generic container, layout view]
 ---
 
 ```jsx

package/components/ui/grid.md

@@ -11,7 +11,7 @@ props:
   - children: React.ReactNode
 when_to_use: 2D layouts where Stack (vertical) and Row (horizontal) don't fit — stat-card grids, feature tiles, pricing columns, photo grids. Reach for Grid over hand-rolled `grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4` so the column count is a prop the settings panel can mutate and the responsive ladder stays consistent across designs.
 composes_with: [Card, Stack (inside each cell), Row, Button, any content component]
-aliases: [grid, tiles, cards grid, stat grid, columns, feature grid]
+aliases: [grid, tiles, cards grid, stat grid, columns, feature grid, grid view, lazy v grid, lazyvgrid, lazy h grid, lazyhgrid, tile grid, masonry]
 notes: |
   `cols` values and their responsive ladders:
     "1"  → grid-cols-1 (single column at all breakpoints)

package/components/ui/hover-card.md

@@ -6,13 +6,21 @@ props:
   - HoverCard: open?, defaultOpen?, onOpenChange?, openDelay? (default 700), closeDelay? (default 300)
   - HoverCardTrigger: asChild?: boolean — usually a Link or Button
   - HoverCardContent: side?, align?, sideOffset?, alignOffset?, className?
-when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
-composes_with: [Avatar (user preview), Card (richer content), Link (the trigger)]
-aliases: [hover card, hover preview, mention preview, profile peek, link preview]
+  - HoverCardContent: surface? (solid | translucent | glass | glass-strong) — what the preview surface is *made of*. `solid` (default) is `bg-popover`. `glass` for hover previews over rich content (a media feed, a layout canvas).
+when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups, layer-thumbnail peeks. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
+composes_with: [Avatar (user preview), Card (richer content), Link (the trigger), MediaSurface (link/layer previews), Code (snippet previews)]
+aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card, glass preview, frosted preview]
 ---
 
+HoverCardContent sits at elevation-4. The surface choice depends entirely on what's behind the trigger.
+
+---
+
+### Scenario 1 — User mention preview (default opaque)
+
+The trigger is inline text in a comment thread, document, or feed. The reader's eye is on the prose; the hover-card needs to feel like a small contained card popping up next to the link. Opaque is correct.
+
 ```jsx
-// User mention preview — pointer-only enrichment.
 <HoverCard>
   <HoverCardTrigger asChild>
     <a href="/u/elena" className="font-medium underline">@elena</a>
@@ -28,8 +36,94 @@ aliases: [hover card, hover preview, mention preview, profile peek, link preview
         <span className="text-sm text-muted-foreground">
           Design lead · Joined Mar 2025
         </span>
+        <span className="text-sm">Currently focused on the layout-quality skill suite.</span>
       </Stack>
     </Row>
   </HoverCardContent>
 </HoverCard>
 ```
+
+---
+
+### Scenario 2 — Glass layer preview in a canvas tool
+
+You're hovering a layer name in the Studio layer list. The canvas alongside shows the actual layer in context. A glass hover-card carrying a thumbnail of the layer keeps the canvas visible AND gives the preview presence.
+
+```jsx
+<HoverCard openDelay={300}>
+  <HoverCardTrigger asChild>
+    <button className="text-sm hover:underline">Hero card · v0</button>
+  </HoverCardTrigger>
+  <HoverCardContent
+    surface="glass"
+    className="w-80 shadow-elevation-4"
+    side="right"
+    align="start"
+  >
+    <Stack gap="sm">
+      <MediaSurface
+        aspect="video"
+        source={{ kind: "image", src: "/previews/hero-v0.png" }}
+        alt="Hero card v0 thumbnail"
+      />
+      <Stack gap="xs">
+        <span className="text-sm font-medium">Hero card · v0</span>
+        <span className="text-xs text-muted-foreground">Last edited 2m ago by Elena</span>
+      </Stack>
+    </Stack>
+  </HoverCardContent>
+</HoverCard>
+```
+
+Tighter `openDelay` (300ms vs the default 700) because the user is scanning a list — they want previews to come up faster.
+
+---
+
+### Scenario 3 — Code snippet preview (translucent)
+
+You're showing a hover preview of a code reference (a function name in docs, a symbol in a comment). Translucent lets the page peek through without committing to glass blur — feels lighter for a quick read.
+
+```jsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <code className="font-mono text-sm rounded bg-muted px-1.5 py-0.5">surfaceBg()</code>
+  </HoverCardTrigger>
+  <HoverCardContent
+    surface="translucent"
+    className="w-96 shadow-elevation-4 p-0"
+  >
+    <Stack gap="xs" className="p-4 pb-2">
+      <span className="text-sm font-medium">surfaceBg(surface, defaultBgClass)</span>
+      <span className="text-xs text-muted-foreground">@gradeui/ui · lib/surface</span>
+    </Stack>
+    <Code
+      source={`function surfaceBg(surface, defaultBgClass) {
+  return surface === "solid" ? defaultBgClass : "";
+}`}
+      language="ts"
+      bare
+      className="text-xs p-4"
+    />
+  </HoverCardContent>
+</HoverCard>
+```
+
+---
+
+### Anti-patterns
+
+**DO NOT use HoverCard on touch devices for critical info.** There's no hover on touch — the preview is unreachable. Either provide a click fallback or use Popover.
+
+**DO NOT roll glass by hand on HoverCardContent.**
+
+```jsx
+{/* ❌ */}
+<HoverCardContent className="bg-popover/60 backdrop-blur-md">
+
+{/* ✅ */}
+<HoverCardContent surface="glass">
+```
+
+**DO NOT use HoverCard for tooltips.** Tooltips are tiny, label-only, and dismiss instantly. HoverCard is for rich content with delay. If the content is a few words, reach for Tooltip.
+
+**DO NOT use HoverCard as a primary navigation surface.** It dismisses on pointer-out — if the user has to traverse a path to reach a button inside, the preview will close before they get there.

package/components/ui/input.md

@@ -6,7 +6,7 @@ props:
   - 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.
 composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
-aliases: [text field, textbox, textfield, form field, text input]
+aliases: [text field, textbox, textfield, form field, text input, secure field, search field, url field, number field, textinput, text input field, react native textinput]
 ---
 
 ```jsx

package/components/ui/label.md

@@ -6,6 +6,7 @@ props:
   - All native label HTML attrs
 when_to_use: Every Input / Textarea / Checkbox / Switch / RadioGroup. Always use htmlFor so clicking the label focuses the control.
 composes_with: [Input, Textarea, Checkbox, Switch, RadioGroup, Select]
+aliases: [label, form label, field label, caption]
 ---
 
 ```jsx

package/components/ui/map.md

@@ -2,7 +2,7 @@
 name: Map
 import: "@gradeui/ui"
 subcomponents: [MapMarker]
-aliases: [map, maps, mapbox, maplibre, google maps, geo, location, latlng, coordinates, marker, pin, airbnb, listings, fleet, real estate, logistics]
+aliases: [map, maps, mapbox, maplibre, google maps, geo, location, latlng, coordinates, marker, pin, airbnb, listings, fleet, real estate, logistics, map view, mapkit, mapview, react native maps, rn maps]
 props:
   - provider — "maplibre" (default, free, no key) | "mapbox" (needs accessToken) | "google" (needs apiKey). Switching is one prop change.
   - center — `[lng, lat]` tuple. ALWAYS lng first. Required.
@@ -77,4 +77,4 @@ ANTI-PATTERNS — don't do these:
 - DO NOT call `setStyle` or reach for `mapboxgl.Marker` directly — use `appearance` and `<MapMarker>`. The escape hatch (`mapRef.current.instance`) is for things the wrapper genuinely doesn't expose (3D extrusions, drawing tools, heatmaps).
 - DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
 
-Markers are DOM — children inherit `--rds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.
+Markers are DOM — children inherit `--gds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.

package/components/ui/media-surface.md

@@ -2,17 +2,60 @@
 name: MediaSurface
 import: "@gradeui/ui"
 props:
-  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
-  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--rds-media-radius` CSS var
+  - aspect?: "video" | "square" | "portrait" | "wide" | "auto" — when omitted, derived from `hint` (album/product/food → square, portrait/poster → portrait, landscape → wide, video/audio/embed/generic → video)
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--gds-media-radius` CSS var
+  - border?: boolean (default false)
+  - loading?: boolean — renders the muted skeleton overlay
+  - hint?: "album" | "portrait" | "landscape" | "poster" | "product" | "food" | "video" | "audio" | "embed" | "3d" | "generic" (default "generic") — picks the placeholder glyph + the default aspect + the future generation provider
+  - alt?: string — becomes the eventual `<img alt>`; also drives the placeholder caption and small-tier initials
+  - source?: { kind, …per-kind fields } — structured metadata for the generation pipeline. Shapes per kind — album: { artist, title, year? } · poster: { title, year? } · portrait: { name?, role? } · landscape: { location?, mood? } · product: { name?, brand? } · food: { dish?, cuisine? } · generic: { prompt } · video/audio/embed/3d: no fields
+  - src?: string — when set, renders an `<img>` filling the slot via object-cover; the wrapper keeps its chrome
+  - glyph?: ReactNode — per-instance override of the hint-derived placeholder glyph (escape hatch for unusual slots)
+  - overlay?: ReactNode — decorative layer rendered ABOVE the media/placeholder (play buttons, hover gradients, corner badges, progress bars). Does NOT suppress the placeholder — use this for decoration, use `children` for replacement
+  - emptyState?: "auto" | "icon" | "none" | ReactNode — "auto" (default) renders the size-tiered placeholder; "icon" is a legacy alias; "none" disables; a node fully overrides
   - className?: string
-  - children: React.ReactNode
-when_to_use: Low-level shell primitive that wraps a media canvas (video, Rive runtime, WebGL canvas) in an aspect-ratio surface with shared border-radius and pause-on-offscreen behaviour. Prefer VideoPlayer / RivePlayer / ThreeScene, which wrap this. Reach for MediaSurface directly only if you're building a bespoke media component and want consistent chrome.
-composes_with: [VideoPlayer, RivePlayer, ThreeScene — all use this internally]
-aliases: [media, canvas wrapper, media shell]
+  - children?: ReactNode — escape hatch for putting a custom `<video>`, `<canvas>`, Rive runtime, etc. inside. When supplied, the placeholder is suppressed
+when_to_use: The canonical media slot for ALL non-person imagery — album art, posters, hero images, landscape photos, video and 3D containers. Pass `hint` + `alt` + (optionally) `source` so the empty-state placeholder is meaningful and the generation pipeline can later fill the slot with a real image. Use directly for declarative slots; the higher-level VideoPlayer / RivePlayer / ThreeScene wrap this for runtime-heavy media.
+composes_with: [Card (as the image slot), CardBlock, MediaBlock, VideoPlayer, RivePlayer, ThreeScene]
+aliases: [media, image slot, media slot, image placeholder, cover, thumbnail, poster slot, image, image view, image well, imagebackground, asyncimage, react native image, fastimage]
+notes: |
+  Anti-patterns to avoid:
+
+  - DO NOT wrap <Avatar> inside <MediaSurface> to get a 2-letter initials
+    fallback. That conflates two primitives. Set `alt` + `hint` on
+    MediaSurface directly — the placeholder already renders initials at
+    small sizes derived from `alt`.
+  - DO NOT use <Avatar> for album art, posters, products, food, landscapes,
+    etc. Avatar is for PEOPLE only (circular, social context). Use
+    MediaSurface with the appropriate `hint`.
+  - DO NOT inline manual gradient backgrounds (`bg-gradient-to-br …`) on
+    MediaSurface as a "placeholder vibe" — the empty-state placeholder is
+    already styled via `--gds-media-placeholder-bg/-fg` and themes with
+    the rest of the design system.
+
+  When you have a real image URL, pass it as `src=`. The wrapper keeps its
+  aspect/radius/border chrome and fills with object-cover.
 ---
 
 ```jsx
+{/* Empty placeholder — model emits this before generation has filled the slot */}
+<MediaSurface
+  hint="album"
+  alt="Travelling Without Moving — Jamiroquai"
+  source={{ kind: "album", artist: "Jamiroquai", title: "Travelling Without Moving" }}
+  radius="md"
+/>
+
+{/* Filled — same component, now with a src */}
+<MediaSurface
+  hint="album"
+  alt="Travelling Without Moving — Jamiroquai"
+  src="https://coverartarchive.org/release/.../front-500.jpg"
+  radius="md"
+/>
+
+{/* Video container — children escape hatch */}
 <MediaSurface aspect="video" radius="lg">
-  <canvas ref={canvasRef} className="w-full h-full" />
+  <video src="/intro.mp4" controls className="absolute inset-0 h-full w-full" />
 </MediaSurface>
 ```

package/components/ui/multi-select.md

@@ -0,0 +1,114 @@
+---
+name: MultiSelect
+import: "@gradeui/ui"
+props:
+  - options: { value: string; label: string; icon?: ComponentType; disabled?: boolean }[]
+  - value?: string[] — controlled selection
+  - defaultValue?: string[] — uncontrolled initial selection
+  - onValueChange?: (next: string[]) => void
+  - placeholder?: string (default "Select…")
+  - searchPlaceholder?: string (default "Search…")
+  - emptyMessage?: string (default "Nothing matches.")
+  - maxCount?: number (default 3) — badges shown on the trigger before collapsing to "+N more"
+  - searchable?: boolean (default true) — hide for short option lists
+  - badgeDismissible?: boolean (default true) — show × on each selected badge
+  - disabled?: boolean
+  - modalPopover?: boolean (default false) — Popover modal mode
+  - className?: string
+when_to_use: |
+  Picking multiple items from a finite list — tag selectors, filter chips,
+  "share with N people", multi-region settings.
+
+  **This is the answer for ANY "removable-chips-inside-an-input" pattern.**
+  MultiSelect's trigger renders the current selection as Badges with X
+  icons (the "chip-in-trigger" / "chip-in-input" shape), opens a Popover
+  with a searchable Command list, and supports "+N more" collapse past
+  `maxCount`. Reach for it for:
+    - Linear-style filter bars (assignee, label, project chips inside one trigger)
+    - Slack channel pickers (selected channels as removable chips)
+    - Notion relation properties (related-page chips)
+    - GitHub label / assignee pickers
+    - tag / category / mention pickers anywhere
+  Don't invent a `<ChipInput>` or `<TagInput>` for these — MultiSelect
+  already covers the trigger-with-badges shape.
+
+  Use `<Select>` instead for SINGLE selection. Use `<Command>` directly
+  (no MultiSelect wrapper) when the option set is unbounded or async
+  (users to @-mention, email recipients, search-as-you-type API results).
+composes_with: [Popover, Command, Badge, Checkbox-style row indicator, Separator]
+aliases: [
+  multi select, multiselect, multi-select, tag picker, chips input,
+  chip input, chipinput, tag input, taginput, chip picker, badge picker,
+  multi picker, multi-pick combobox, multipicker, tag select,
+  react native multi select, multi-select combobox,
+  filter chips, filter bar chips, removable chips, removable pills,
+  channel picker, label picker, recipient picker, relation picker,
+  picker with chips, selected items as chips, badges in input,
+  badges in trigger, pills in input, multi-select with badges
+]
+---
+
+```jsx
+const frameworks = [
+  { value: "next", label: "Next.js" },
+  { value: "remix", label: "Remix" },
+  { value: "astro", label: "Astro" },
+  { value: "nuxt", label: "Nuxt" },
+];
+
+<MultiSelect
+  options={frameworks}
+  defaultValue={["next", "remix"]}
+  onValueChange={setSelected}
+  placeholder="Pick frameworks"
+  maxCount={2}
+/>
+```
+
+```jsx
+// With per-option icons — the icon renders both in the dropdown row
+// and on the selected badge.
+import { Code2, Server, Cloud } from "lucide-react";
+const services = [
+  { value: "edge", label: "Edge runtime", icon: Cloud },
+  { value: "node", label: "Node runtime", icon: Server },
+  { value: "browser", label: "Browser only", icon: Code2 },
+];
+
+<MultiSelect options={services} placeholder="Select runtimes" />
+```
+
+```jsx
+// Filter-bar chip picker (Linear / Jira style). Selected status chips
+// render INSIDE the trigger with X icons; click the trigger to open the
+// Popover and toggle more. Pair with a search Input to the left for the
+// "search + scoped filters" composition (e.g. Reddit / Linear / GitHub
+// header search). Don't reach for a custom ChipInput — this IS it.
+const statuses = [
+  { value: "todo", label: "Todo" },
+  { value: "doing", label: "In Progress" },
+  { value: "done", label: "Done" },
+];
+
+<Row gap="sm" align="center">
+  <Input placeholder="Search issues…" className="flex-1" />
+  <MultiSelect
+    options={statuses}
+    placeholder="Status"
+    maxCount={2}
+    badgeDismissible
+  />
+</Row>
+```
+
+### Anti-patterns
+
+DO NOT use MultiSelect for single-pick — that's `<Select>`. The visual semantics differ (badges vs single value) and screen-reader announcements differ ("combobox, 2 selected" vs "combobox, Apple").
+
+DO NOT pass `value` without `onValueChange` — the component becomes a read-only display of the controlled state and selections inside the popover silently no-op. Either go fully uncontrolled (`defaultValue`) or wire both.
+
+DO NOT inline `options` as `[{value, label}, ...]` from scratch on every render — memoise it. The component memoises its internal lookup, but a fresh array reference on every parent render still forces React to reconcile every row.
+
+DO NOT reach for MultiSelect when the list is unbounded or async (users to mention, email recipients, search-as-you-type API results). Use `<Command>` directly with custom rendering — MultiSelect's `options` model expects the full set up front.
+
+DO NOT hand-roll a "chip input" / "tag input" / "search with removable filter chips" composition with raw Badge + Input + state. MultiSelect already covers the trigger-with-removable-Badges pattern (the chip-in-trigger shape). If your screenshot has selected items rendered as removable pills, MultiSelect is the answer — even if the source visual integrates the chips with a search field. (Genuine gap: the *typed-text-immediately-next-to-chips* search composition where the input is freeform and the chips are scopes — that's a Row of `<Input>` + `<MultiSelect>`, not a new primitive.)