@gradeui/ui 0.10.0 → 1.0.0

package/components/ui/carousel.md

@@ -0,0 +1,56 @@
+---
+name: Carousel
+import: "@gradeui/ui"
+subcomponents: [Carousel.Slide, Carousel.VideoSlide, Carousel.Dots, Carousel.Arrows]
+props:
+  - Carousel: loop?: boolean — wrap last → first (default true)
+  - Carousel: align?: "start" | "center" | "end" — slide alignment (default start)
+  - Carousel: slidesPerView?: number — how many slides visible at once (default 1)
+  - Carousel: autoplay?: boolean | { delay?: number; pauseOnHover?: boolean; pauseWhenOffscreen?: boolean } — true for defaults (5s, hover/offscreen aware)
+  - Carousel: draggable?: boolean — drag-to-swipe (default true)
+  - Carousel: onSlideChange?: (index: number) => void
+  - Carousel.Slide: duration?: number — per-slide autoplay duration in ms; overrides the carousel default for this slide only
+  - Carousel.VideoSlide: src: string — video URL
+  - Carousel.VideoSlide: poster?: string — image shown until the slide is active
+  - Carousel.VideoSlide: alt?: string — accessible label for the video
+  - Carousel.VideoSlide: loop?: boolean — default true (the chosen video-default behaviour)
+  - Carousel.VideoSlide: controls?: boolean — default false (chosen default = no controls)
+  - Carousel.VideoSlide: fit?: "cover" | "contain" — object-fit (default cover)
+  - Carousel.VideoSlide: duration?: number — same as Carousel.Slide; overrides autoplay timing for THIS slide
+  - Carousel.Dots: position?: "below" | "overlay"
+  - Carousel.Arrows: position?: "overlay" | "outside"
+when_to_use: Anywhere a horizontal stack of slides cycles automatically or on user input — marketing hero rotations, featured rails on a TV / streaming app, onboarding tours, image galleries, product carousels, testimonial cycles. Mixed video + still slides are a first-class case; the VideoSlide handles muted-autoplay + poster swap on activation.
+composes_with: [MediaSurface, Card, Stack, Row]
+aliases: [carousel, slideshow, slider, hero rotation, image gallery, featured row, swipe deck, paged view, page tabview, page view, swiper, react native swiper, page control]
+---
+
+```jsx
+<Carousel autoplay={{ delay: 6000 }} loop>
+  <Carousel.Slide duration={15000}>
+    <MediaSurface aspect="wide" hint="poster" alt="Featured: Severance S2" />
+  </Carousel.Slide>
+
+  <Carousel.VideoSlide
+    src="/trailers/the-studio.mp4"
+    poster="/posters/the-studio.jpg"
+    alt="The Studio — official trailer"
+  />
+
+  <Carousel.Slide>
+    <MediaSurface aspect="wide" hint="poster" alt="Coming soon: Foundation S3" />
+  </Carousel.Slide>
+
+  <Carousel.Arrows />
+  <Carousel.Dots position="overlay" />
+</Carousel>
+```
+
+### Anti-patterns
+
+DO NOT confuse `<Carousel>` with `<Slider>`. `Slider` is the range input (a draggable thumb on a track) — the colloquial "slider" you'd put on a marketing page is a `Carousel`. When the user says "add a slider", check whether they want a range control or a slideshow before reaching for either.
+
+DO NOT pass real `<img>` or `<video>` tags directly as `Carousel.Slide` children when the slide is meant to be a hero media tile. Use `<MediaSurface>` (still slots) or `<Carousel.VideoSlide>` (video slots) so themes, aspect ratios, and the future image-generation pipeline stay consistent. Raw `<img>` inside a slide is fine for fully-authored content (logo strips, certificates), but for "media that might get regenerated" the surface primitive is mandatory.
+
+DO NOT set very short `duration` values (sub-2000ms) on still slides — the autoplay timer ignores the request implicitly when the carousel is paused (hover, offscreen) but very fast cycles read as broken to users. 5-15 seconds per slide is the natural range.
+
+DO NOT mount the autoplay timer inside individual slides via `setInterval` and forget to clean up — use `<Carousel.Slide duration>` instead. The carousel root owns the single timer; per-slide overrides feed into it through a context-shared ref.

package/components/ui/chart.md

@@ -12,7 +12,7 @@ props:
   - ChartLegend / ChartLegendContent: pair the same way for the legend
 when_to_use: Reporting dashboards, single-purpose analytics cards (revenue, conversions, active users), or anywhere you'd otherwise hand-roll a Recharts setup. Bring the actual chart type from `recharts` — ChartContainer doesn't pick the chart shape for you, it themes whatever you nest. For sparkline-style decorative trends consider just rendering a small SVG line directly; ChartContainer is overkill for non-interactive ornament.
 composes_with: [Card (chart-in-a-card pattern), Tabs (multi-metric switcher), Recharts components (Bar, Line, Area, Pie, Radar from "recharts")]
-aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart]
+aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart, swift chart, swiftui chart, victory chart, victory native]
 ---
 
 ```jsx

package/components/ui/checkbox.md

@@ -9,6 +9,7 @@ props:
   - 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)]
+aliases: [checkbox, tickbox, tick box, check, multi-select item]
 ---
 
 ```jsx

package/components/ui/collapsible.md

@@ -10,7 +10,7 @@ props:
   - CollapsibleContent: children: React.ReactNode — the content that animates in/out
 when_to_use: A single show/hide reveal — "Show advanced settings" rows, expandable inline help, "More details" sections inside cards. For multiple rows of expandable content where one-at-a-time matters, reach for Accordion. For a separate panel that floats above content, use Popover.
 composes_with: [Button (as the trigger, asChild), Card (expandable settings group), Row (header + chevron)]
-aliases: [collapsible, expand, show more, disclosure, advanced settings]
+aliases: [collapsible, expand, show more, disclosure, advanced settings, disclosure group, expandable section, expandable view, show hide]
 ---
 
 ```jsx

package/components/ui/command.md

@@ -16,7 +16,7 @@ props:
   - CommandDialog: open, onOpenChange — when you want the command palette mounted in a modal (cmd+k pattern)
 when_to_use: A searchable list of actions or destinations — global ⌘K palettes, "jump to" inputs, account switchers with filter. Wrap in CommandDialog when it should pop over the entire app on a hotkey. For straight forms with filter, prefer a Select with a search input. For free-text autocomplete tied to a single value, prefer Combobox built on Popover + Command.
 composes_with: [Dialog (CommandDialog wraps it), Popover (inline combobox), Tooltip]
-aliases: [command palette, command menu, cmd k, quick switcher, action menu]
+aliases: [command palette, command menu, cmd k, quick switcher, action menu, spotlight, spotlight search, quick open, fuzzy finder]
 ---
 
 ```jsx

package/components/ui/date-picker.md

@@ -17,7 +17,7 @@ props:
 when_to_use: Any date or date-range entry. Use DatePicker for a single date (DOB, due date, booking). Use DateRangePicker for a span (report period, stay dates, filter window). Prefer these over <Input type="date"> — consistent theming, keyboard nav, a11y, and no browser-native UI drift.
 composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
 subcomponents: [DateRangePicker]
-aliases: [datepicker, calendar input, date field, date range]
+aliases: [datepicker, calendar input, date field, date range, datepickerios, react native date picker, calendar input field, date field control]
 ---
 
 ```jsx

package/components/ui/dialog.md

@@ -7,9 +7,9 @@ props:
   - DialogTrigger: asChild? (wrap a Button)
   - 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).
+when_to_use: Modal interruptions — confirmations, focused forms, detail views. 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]
-aliases: [modal, popup, overlay]
+aliases: [modal, popup, overlay, alert, system alert, alert dialog, modal dialog, confirm dialog, react native modal, rn alert]
 ---
 
 ```jsx
@@ -27,3 +27,14 @@ aliases: [modal, popup, overlay]
   </DialogContent>
 </Dialog>
 ```
+
+DialogContent ships at elevation-5. Reach for the raised Button variant inside DialogFooter when the action carries weight ("Delete", "Publish", "Ship"):
+
+```jsx
+<DialogFooter>
+  <Button variant="outline">Cancel</Button>
+  <Button variant="raised" style={{ "--btn-glow": "var(--destructive)" }}>
+    Delete forever
+  </Button>
+</DialogFooter>
+```

package/components/ui/dropdown-menu.md

@@ -12,7 +12,7 @@ props:
   - 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]
 ---
 
 ```jsx
@@ -37,3 +37,9 @@ aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action
   </DropdownMenuContent>
 </DropdownMenu>
 ```
+
+DropdownMenuContent ships at elevation-4. For frosted overlays on rich canvases, opt into glass:
+
+```jsx
+<DropdownMenuContent className="gds-surface-glass">…</DropdownMenuContent>
+```

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

@@ -8,7 +8,7 @@ props:
   - 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]
+aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card]
 ---
 
 ```jsx

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.)

package/components/ui/popover.md

@@ -9,7 +9,7 @@ props:
   - PopoverAnchor: asChild?: boolean — pin the popover to a different element than the trigger
 when_to_use: A floating panel anchored to a trigger that contains interactive content — date pickers, color pickers, filter pickers, "more info" panels, inline forms. Differs from Tooltip (hover-only, no focusable content) and Dialog (modal, blocks the page). DatePicker, DateRangePicker, and the Combobox pattern all compose Popover internally.
 composes_with: [Button (as trigger), Calendar (date picker), Command (combobox), Form controls (inline edit popover)]
-aliases: [popover, dropdown panel, floating panel, inline editor, attached panel, filter pop]
+aliases: [popover, dropdown panel, floating panel, inline editor, attached panel, filter pop, popover view, popoverpresentation, attached popover]
 ---
 
 ```jsx
@@ -34,3 +34,10 @@ aliases: [popover, dropdown panel, floating panel, inline editor, attached panel
   </PopoverContent>
 </Popover>
 ```
+
+PopoverContent ships at elevation-4. Opt into glass for a frosted look, or layer in aura when the popover is AI-driven:
+
+```jsx
+<PopoverContent className="gds-surface-glass">…</PopoverContent>
+<PopoverContent className="gds-aura-ring">Studio suggestion</PopoverContent>
+```

package/components/ui/progress.md

@@ -7,6 +7,7 @@ props:
   - className?: string
 when_to_use: Determinate progress — file uploads, multi-step forms, quota meters. Indeterminate state → use Skeleton or animated Loader icon.
 composes_with: [Card (as a section), Badge (showing % next to it), Label (describing what's loading)]
+aliases: [progress, progress view, progress indicator, progress bar, determinate progress, loading bar, completion bar]
 ---
 
 ```jsx

package/components/ui/radio-group.md

@@ -14,7 +14,7 @@ props:
   - 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)]
-aliases: [radio group, radio buttons, single-choice, pricing options, payment method]
+aliases: [radio group, radio buttons, single-choice, pricing options, payment method, radio buttons, radio control, single-select]
 ---
 
 ```jsx

package/components/ui/resizable.md

@@ -13,7 +13,7 @@ props:
   - ResizableHandle: withHandle?: boolean — show a visible drag affordance (default just a hit-zone)
 when_to_use: 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. Static layouts shouldn't use this — reach for AppShell with nav="three-pane" (fixed widths) or Grid (responsive ladder). Built on react-resizable-panels under the hood.
 composes_with: [AppShellMain (host the splitter inside main), ScrollArea (each panel's content), Card]
-aliases: [resizable, splitter, split pane, drag divider, adjustable panels, resizer]
+aliases: [resizable, splitter, split pane, drag divider, adjustable panels, resizer, split view, draggable divider, split pane resizer, ns split view]
 ---
 
 ```jsx

package/components/ui/row.md

@@ -12,7 +12,7 @@ props:
   - children: React.ReactNode
 when_to_use: Horizontal composition — button groups, inline form rows, logo + nav rows, anything on one line. Reach for Row instead of `flex items-center gap-*` so the alignment and spacing are editable through the settings panel. For two-pane layouts with an explicit ratio (sidebar + content, 1/3 + 2/3) use Split instead — Row evenly flows whatever children it holds.
 composes_with: [Button, Input, NavItem, Stack (can wrap a Row), any content component]
-aliases: [row, hstack, horizontal, inline, horizontal layout]
+aliases: [row, hstack, horizontal, inline, horizontal layout, hstack, h-stack, horizontal stack, lazyhstack]
 ---
 
 ```jsx

package/components/ui/scroll-area.md

@@ -10,7 +10,7 @@ props:
   - ScrollBar: orientation? "vertical" | "horizontal" (default vertical)
 when_to_use: Bounded content that needs custom scroll chrome — sidebars with long item lists, chat transcripts, table panels inside a dashboard, anywhere the OS scrollbar would feel out of place against the design tokens. The wrapping element has to have a height constraint (`h-`, `max-h-`, or grid row sizing) or nothing scrolls — scroll-area can't infer a bound on its own. For body-level scrolling, leave the document to the browser.
 composes_with: [Card (long card body), AppShellNav (long sidebar), Sheet (long modal body), Table (sticky-header scrolling list)]
-aliases: [scroll area, scroll container, custom scrollbar, sidebar scroll, panel scroll]
+aliases: [scroll area, scroll container, custom scrollbar, sidebar scroll, panel scroll, scroll view, scrollview, react native scrollview]
 ---
 
 ```jsx

package/components/ui/select.md

@@ -10,7 +10,7 @@ props:
   - 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.
 composes_with: [Label (above SelectTrigger), Form, Card]
-aliases: [dropdown, combobox, picker]
+aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup picker, picker view, rnpickerselect, react native picker, native picker]
 ---
 
 ```jsx

package/components/ui/separator.md

@@ -7,7 +7,7 @@ props:
   - className?: string
 when_to_use: Light divider between sibling blocks in a Card, list, or header. For section-level partition use extra spacing instead.
 composes_with: [Card (between CardHeader/Content/Footer), navigation menus, any vertical stacks]
-aliases: [divider, rule, hr]
+aliases: [divider, rule, hr, line, horizontal rule]
 ---
 
 ```jsx

package/components/ui/sheet.md

@@ -11,7 +11,7 @@ props:
   - SheetClose: asChild? — usually wraps a Button labelled Cancel or Done
 when_to_use: 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 viewports. For a centered focus modal use Dialog. For a transient announcement use Toast (Sonner). For inline reveals use Collapsible.
 composes_with: [Form controls (an inline edit sheet), Button (trigger + close), AppShellNav (mobile-only swap)]
-aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over]
+aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over, action sheet, modal sheet, bottom sheet, side sheet, react native modal sheet, bottom-sheet, ios action sheet]
 ---
 
 ```jsx
@@ -44,3 +44,9 @@ aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-
   </SheetContent>
 </Sheet>
 ```
+
+SheetContent ships at elevation-5. Opt into a frosted glass sheet when the canvas behind it should remain visible:
+
+```jsx
+<SheetContent className="gds-surface-glass">…</SheetContent>
+```

package/components/ui/side-menu.md

@@ -1,40 +0,0 @@
----
-name: SideMenu
-import: "@gradeui/ui"
-props:
-  - sections: SideMenuSection[] — top-level groups; each section has `{ title?, items }`
-  - sections[].title?: string — optional group heading
-  - sections[].items: SideMenuItem[] — `{ label, href?, icon?, active?, badge?, onClick? }`
-  - activeHref?: string — auto-derives `active` on matching items; falls back to per-item `active`
-  - onItemClick?: (item) => void — fires for client-side routing; complements per-item onClick
-  - className?: string
-when_to_use: The primary navigation rail inside an AppShell — Admin/Settings/Billing, Inbox/Sent/Archive, file-tree-ish sidebars. Always sits inside <AppShellNav placement="side">. For top horizontal nav, compose Row + Button/Link directly — Side Menu is vertical-stack-of-items by design. For palette-style jump-to, use Command.
-composes_with: [AppShellNav, AppShell, Avatar (header above the menu), Badge (item counts)]
-aliases: [side menu, sidebar nav, side nav, vertical nav, sidebar items, rail, side bar]
----
-
-```jsx
-// Inbox/Sent/Archive rail inside AppShellNav.
-<AppShellNav placement="side">
-  <SideMenu
-    activeHref="/inbox"
-    sections={[
-      {
-        title: "Mail",
-        items: [
-          { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: "12" },
-          { label: "Sent", href: "/sent", icon: <Send /> },
-          { label: "Archive", href: "/archive", icon: <Archive /> },
-        ],
-      },
-      {
-        title: "Labels",
-        items: [
-          { label: "Work", href: "/label/work", icon: <Tag /> },
-          { label: "Personal", href: "/label/personal", icon: <Tag /> },
-        ],
-      },
-    ]}
-  />
-</AppShellNav>
-```