@gradeui/ui 0.10.0 → 1.1.0

package/components/ui/sidebar.md

@@ -0,0 +1,121 @@
+---
+name: Sidebar
+import: "@gradeui/ui"
+subcomponents: [SidebarHeader, SidebarContent, SidebarFooter, SidebarSection, SidebarItem]
+props:
+  - Sidebar: collapsed?: boolean — controlled collapsed state (wire onCollapsedChange when set)
+  - Sidebar: defaultCollapsed?: boolean — uncontrolled initial value (default false)
+  - Sidebar: onCollapsedChange?: (next: boolean) => void
+  - Sidebar: collapsible?: boolean — show the affordance for the user to collapse (default true)
+  - Sidebar: variant?: 'rail' | 'panel' — outer chrome treatment. `rail` (default) is the classic nav rail with a single right-border + tracked width via `--gds-sidebar-width`; drops cleanly into `<AppShellNav placement="side">`. `panel` is a card-style floating sidebar with full border + rounded corners + parent-controlled width; use when the sidebar is one of several adjacent panes in a body row (e.g. Projects | Canvas | Settings). The compound children (Header/Content/Footer/Section/Item) are identical in both treatments.
+  - SidebarHeader: any children — brand / logo / org switcher; hides nothing when collapsed (centred)
+  - SidebarContent: any children — scrollable body
+  - SidebarFooter: any children — user block, settings link, pinned chrome
+  - SidebarSection: title?: ReactNode — group label; **uppercase tracking-wide muted** styling auto-applied (Notion / Linear / Slack-style "GAMES", "FAVORITES", "WORKSPACE" headers); hidden when sidebar is collapsed
+  - SidebarSection: icon?: ReactNode — optional icon beside the title
+  - SidebarSection: trailing?: ReactNode — **action(s) on the right edge of the header** — the canonical "+" / "..." slot (Notion's "+ Add page" next to Pages, Linear's "+" next to Favorites, Slack's "+" next to Channels). Pointer events isolated so a Button here doesn't toggle collapse.
+  - SidebarSection: collapsible?: boolean — title acts as expand/collapse trigger with a **chevron indicator** (default true). Set `false` for a static, non-clickable header.
+  - SidebarSection: defaultExpanded?: boolean — initial open state (default true)
+  - SidebarItem: icon?: ReactNode — leading icon
+  - SidebarItem: badge?: ReactNode — trailing count / label (hidden when collapsed)
+  - SidebarItem: active?: boolean — current route; adds aria-current="page"
+  - SidebarItem: href?: string — renders as <a>; for routing use `asChild` with your link component
+  - SidebarItem: asChild?: boolean — wrap a custom link (<Link href> from Next.js etc.) via Radix Slot
+  - SidebarItem: asButton?: boolean — render as <button> for action rows (open dialog, log out)
+  - SidebarItem: disabled?: boolean
+  - SidebarItem: collapsedLabel?: ReactNode — tooltip override when sidebar is collapsed (defaults to children text)
+  - SidebarItem: size?: 'sm' | 'md' — row size. `md` (default) is the standard `text-sm font-medium` nav row; `sm` is `text-xs` + lighter weight + tighter padding for visually subordinate rows (nested screens under a project, sub-pages under a section). Active state still wins on color + weight so the current row pops at either size.
+  - SidebarItem: description?: ReactNode — secondary line beneath the label (metadata like 'Edited 2m ago', '12 items', a brief description). Row layout adapts: label + description stacked vertically; icon vertically-centered against the stack; badge stays on trailing edge. Hidden when sidebar collapsed.
+  - SidebarTreeItem: description?: ReactNode — secondary line beneath the label, same shape as SidebarItem.description. Useful when a branch needs more than just a name (last-edited timestamp, item count, owner).
+  - SidebarTreeItem: trailing?: ReactNode — right-edge action slot (settings cog, more-actions overflow, "+ add child"). Rendered as a SIBLING of the branch button (not nested inside it, so `<button>` children in `trailing` stay valid HTML). Vertically centered against the row; click events are stopPropagation'd so a tap on a trailing button doesn't toggle expand/collapse. The branch row wrapper carries a `group/row` named-group, so consumer-provided trailing can opt into hover-only visibility via `hidden group-hover/row:flex` — the hover state is scoped to the branch row alone, not the nested children.
+when_to_use: Vertical app navigation. Drop inside `<AppShellNav placement="side">` for full-page layouts. Compound API — `<SidebarHeader>` for brand, `<SidebarContent>` for the scrollable body of `<SidebarSection>` + `<SidebarItem>` rows, `<SidebarFooter>` for user / settings chrome. For top nav reach for TopMenu; for command-palette style search reach for Command.
+composes_with: [AppShell (inside AppShellNav), Avatar (in Footer), Tooltip (auto-wrapped on collapsed items), Button (asChild for custom routing)]
+aliases: [sidebar, side menu, sidemenu, navigation sidebar, app sidebar, side nav, side nav rail, master pane, sidebarmenu, navigation rail, react native drawer]
+---
+
+```jsx
+<Sidebar defaultCollapsed={false}>
+  <SidebarHeader>
+    <div className="flex items-center gap-2 font-semibold">
+      <Logo className="h-5 w-5" />
+      <span>Acme</span>
+    </div>
+  </SidebarHeader>
+
+  <SidebarContent>
+    <SidebarSection title="Workspace">
+      <SidebarItem href="/" icon={<Home />} active>Dashboard</SidebarItem>
+      <SidebarItem href="/inbox" icon={<Inbox />} badge={3}>Inbox</SidebarItem>
+      <SidebarItem href="/team" icon={<Users />}>Team</SidebarItem>
+    </SidebarSection>
+    <SidebarSection title="Personal">
+      <SidebarItem href="/settings" icon={<Settings />}>Settings</SidebarItem>
+    </SidebarSection>
+  </SidebarContent>
+
+  <SidebarFooter>
+    <Row gap="sm" align="center">
+      <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+      <Stack gap="none" className="text-xs">
+        <span className="font-medium">Ali</span>
+        <span className="text-muted-foreground">Pro plan</span>
+      </Stack>
+    </Row>
+  </SidebarFooter>
+</Sidebar>
+```
+
+```jsx
+// With Next.js routing — wrap any link component via `asChild`.
+import Link from "next/link";
+
+<SidebarItem asChild icon={<Home />} active={pathname === "/"}>
+  <Link href="/">Dashboard</Link>
+</SidebarItem>
+```
+
+```jsx
+// Action row — `asButton` renders a <button> instead of an <a>.
+<SidebarItem asButton icon={<LogOut />} onClick={signOut}>
+  Sign out
+</SidebarItem>
+```
+
+```jsx
+// Section header with a trailing action — the Notion / Linear / Slack
+// "+" next to a section name. The trailing slot isolates pointer events
+// from the collapse toggle, so the Button doesn't also flip expand.
+<SidebarSection
+  title="Pages"
+  trailing={
+    <Button variant="ghost" size="icon" className="h-5 w-5">
+      <Plus className="h-3 w-3" />
+    </Button>
+  }
+>
+  <SidebarItem>Notes</SidebarItem>
+  <SidebarItem>Drafts</SidebarItem>
+</SidebarSection>
+```
+
+```jsx
+// Non-collapsible static header — for sections the user shouldn't
+// be able to fold. `collapsible={false}` hides the chevron.
+<SidebarSection title="Workspace" collapsible={false}>
+  <SidebarItem>...</SidebarItem>
+</SidebarSection>
+```
+
+### Anti-patterns
+
+DO NOT pass a `sections={[...]}` data array — that was the old SideMenu shape (retired May 2026). Compose `<SidebarSection>` and `<SidebarItem>` directly so any non-list-shaped chrome (search input, drag handle, custom brand block) can sit alongside the nav.
+
+DO NOT set `href` AND `onClick` AND `asChild` at once — pick one mode per row. `href` = anchor, `asButton` = button, `asChild` = wrap your own link component. Mixing modes makes the DOM ambiguous.
+
+DO NOT use Sidebar for primary marketing-style top navigation — that's TopMenu. Sidebar is for app chrome (logged-in product surfaces), not landing pages.
+
+DO NOT rely on the collapsed-state tooltip to convey critical-only information. When the sidebar is collapsed, only the icon is visible by default; the label is in the tooltip on hover, but mobile users + screen readers won't reliably see it. Keep icons recognisable and ship the label as actual text on hover/focus, not just as a tooltip.
+
+DO NOT hand-roll an uppercase "SECTION NAME" header above your items. `<SidebarSection title="…">` already gives you the uppercase + tracking-wide + muted styling, plus the chevron + expand/collapse behaviour. If your design has a "+" or "..." next to the section name, use the `trailing` prop — don't render the action as a separate SidebarItem below the section.
+
+DO NOT bypass `<Sidebar>` and compose an icon rail or projects pane from raw `<Stack>` + buttons. You lose the collapsed-state handling, the per-item tooltip, the `data-gds-part` markers that Studio's selection layer reads, and the consistent padding/gap CSS vars (`--gds-sidebar-*`). If you find yourself writing `<button className="flex items-center gap-3 rounded-md px-3 py-2 hover:bg-muted">{icon}{label}</button>`, that's a SidebarItem.

package/components/ui/simple-tabs.md

@@ -1,27 +0,0 @@
----
-name: SimpleTabs
-import: "@gradeui/ui"
-subcomponents: [SimpleTabsList, SimpleTabsTrigger, SimpleTabsContent, SimpleTabsRoot, SimpleTabsPanel]
-props:
-  - SimpleTabs: tabs: { value: string; label: string; content: React.ReactNode }[] — fully-data-driven tab strip
-  - SimpleTabs: defaultValue?: string — initial selected tab value
-  - SimpleTabs: value?: string — controlled selected tab
-  - SimpleTabs: onValueChange?: (value: string) => void
-  - SimpleTabs: className?: string — wrapper class
-  - SimpleTabsPanel / SimpleTabsRoot / SimpleTabsList / SimpleTabsTrigger / SimpleTabsContent: composition primitives for when the data-driven prop isn't flexible enough
-when_to_use: A quick tab strip you can declare from data — config-driven settings tabs, model output where the LLM passes an array. For richer composition (icons, tooltips, per-trigger props) reach for the canonical Tabs component instead.
-composes_with: [Card, Dialog]
-aliases: [simple tabs, data tabs, config tabs]
----
-
-```jsx
-// Data-driven — pass an array of { value, label, content }.
-<SimpleTabs
-  defaultValue="profile"
-  tabs={[
-    { value: "profile", label: "Profile", content: <ProfilePanel /> },
-    { value: "team", label: "Team", content: <TeamPanel /> },
-    { value: "billing", label: "Billing", content: <BillingPanel /> },
-  ]}
-/>
-```

package/components/ui/skeleton.md

@@ -6,7 +6,7 @@ props:
   - All native div HTML attrs
 when_to_use: Loading placeholder for content whose shape you know. Set width/height via className to mimic the real content (e.g. "h-4 w-32"). Not a spinner — use it where the real thing will drop in.
 composes_with: [Card, Avatar (inside a Skeleton for avatar loading), any layout]
-aliases: [placeholder, shimmer, loader, loading state]
+aliases: [placeholder, shimmer, loader, loading state, redacted, redacted placeholder, shimmer placeholder, content placeholder, lottie placeholder]
 ---
 
 ```jsx

package/components/ui/slider.md

@@ -15,7 +15,7 @@ props:
   - name?: string — form name when posting natively
 when_to_use: A continuous-ish numeric pick — volume, opacity, font size, price-range filters. Use a single-thumb slider for one value, two-thumb for a range. For a small set of discrete options (1-5 stars, sm/md/lg) prefer ToggleGroup. For free-text numeric entry use an Input type="number".
 composes_with: [Label (mandatory above), Row (label + current value display), Card (settings rows)]
-aliases: [slider, range slider, range input, volume, opacity slider, scrub, drag value]
+aliases: [slider, range slider, range input, volume, opacity slider, scrub, drag value, slider control, value slider, react native slider]
 ---
 
 ```jsx

package/components/ui/sortable.md

@@ -0,0 +1,101 @@
+---
+name: Sortable
+import: "@gradeui/ui"
+subcomponents: [Sortable.Item, Sortable.Handle]
+props:
+  - Sortable: values: (string | number)[] — ordered list of unique ids; the source of truth for the order
+  - Sortable: onReorder?: (next: (string | number)[]) => void — fires with the new order after a drag that changed it
+  - Sortable: strategy?: "vertical" | "horizontal" | "grid" (default "vertical") — match the layout your items render in
+  - Sortable: disabled?: boolean — disable drag on every item
+  - Sortable.Item: value: string | number — must match one entry in the parent `values` array (identity, not React key)
+  - Sortable.Item: asChild?: boolean — render as the child element via Radix Slot
+  - Sortable.Item: disabled?: boolean — disable drag for this item only
+  - Sortable.Handle: asChild?: boolean — wrap a Button / icon as the drag grip
+when_to_use: Drag-to-reorder lists, kanban-column reordering, sortable shelves, tab strips the user can rearrange. Pairs with any layout primitive — Stack for vertical lists, Row for horizontal strips, Grid for 2D card walls. For cross-container drag (drag a card from one column to another) hand-roll DndContext at the page level — Sortable v1 covers single-list reorder; Sortable.Group for cross-container is a planned follow-up. Reach for raw `@dnd-kit/core` if you need custom collision detection, drag overlays with arbitrary chrome, or non-list use cases (kanban swimlanes, draggable canvas nodes).
+composes_with: [Stack (vertical lists), Row (horizontal strips), Grid (2D card walls), Card (typical item content), Button (as Sortable.Handle asChild)]
+aliases: [sortable, reorder, drag and drop, dnd, draggable list, sortable list, kanban, drag to reorder, drag-drop, dragdroplist, drag handle, react native draggable flatlist]
+---
+
+```jsx
+const [items, setItems] = React.useState([
+  { id: "a", title: "First" },
+  { id: "b", title: "Second" },
+  { id: "c", title: "Third" },
+]);
+
+<Sortable values={items.map(i => i.id)} onReorder={(ids) => {
+  setItems(ids.map(id => items.find(i => i.id === id)!));
+}}>
+  <Stack gap="sm">
+    {items.map((item) => (
+      <Sortable.Item key={item.id} value={item.id}>
+        <Card>
+          <CardContent className="p-3">{item.title}</CardContent>
+        </Card>
+      </Sortable.Item>
+    ))}
+  </Stack>
+</Sortable>
+```
+
+```jsx
+// With a drag handle — only the grip activates drag; the rest of the
+// row stays clickable for child Buttons / links.
+<Sortable values={ids} onReorder={setIds} strategy="vertical">
+  <Stack gap="sm">
+    {items.map((item) => (
+      <Sortable.Item key={item.id} value={item.id}>
+        <Card>
+          <Row gap="sm" align="center" className="p-3">
+            <Sortable.Handle asChild>
+              <Button variant="ghost" size="icon">
+                <GripVertical className="h-4 w-4" />
+              </Button>
+            </Sortable.Handle>
+            <span className="flex-1">{item.title}</span>
+            <Button size="sm">Edit</Button>
+          </Row>
+        </Card>
+      </Sortable.Item>
+    ))}
+  </Stack>
+</Sortable>
+```
+
+```jsx
+// Horizontal tab strip — strategy="horizontal" + Row instead of Stack.
+<Sortable values={tabIds} onReorder={setTabIds} strategy="horizontal">
+  <Row gap="xs">
+    {tabs.map((tab) => (
+      <Sortable.Item key={tab.id} value={tab.id}>
+        <Badge>{tab.label}</Badge>
+      </Sortable.Item>
+    ))}
+  </Row>
+</Sortable>
+```
+
+```jsx
+// 2D card grid — strategy="grid".
+<Sortable values={photoIds} onReorder={setPhotoIds} strategy="grid">
+  <Grid cols="3" gap="md">
+    {photos.map((p) => (
+      <Sortable.Item key={p.id} value={p.id}>
+        <MediaSurface aspect="square" alt={p.alt} />
+      </Sortable.Item>
+    ))}
+  </Grid>
+</Sortable>
+```
+
+### Anti-patterns
+
+DO NOT add a `sortable` prop to Stack / Row / Grid — those primitives stay pure. Wrap them in `<Sortable>` to mark a collection sortable. Mixing layout and reorder concerns into one component balloons each primitive's contract for a feature 95% of stacks don't use, and loses you cross-layout consistency (one Sortable wrapping a Grid works exactly like one wrapping a Stack).
+
+DO NOT use `key` as the sortable identity. `<Sortable.Item value={item.id}>` is the source of truth — `key={item.id}` is also fine for React's reconciler but `value` is what dnd-kit reads. They usually match; if they don't, drag-end will operate on the wrong row.
+
+DO NOT try to mutate children directly to reorder. Sortable's data model is `state → children`. Reorder fires `onReorder(newValues)`; you update state; React re-renders children in the new order. Trying to read children's keys + reorder them imperatively fights React.
+
+DO NOT wrap clickable items (Card with onClick, Button-bearing rows) without thinking about drag-vs-click conflict. The PointerSensor has a 4px activation distance so single clicks pass through, but if the row's primary affordance is "click to open detail," consider a `<Sortable.Handle>` so the user clicks the body for detail and drags only the grip.
+
+DO NOT use Sortable for cross-container drag in v1. A single `<Sortable>` is one DndContext; the kanban "drag from To Do to Done" case needs one DndContext above multiple SortableContexts. Until `<Sortable.Group>` lands, that pattern needs hand-rolled `@dnd-kit/core` at the page level. Single-list, single-grid, single-strip reorder all work.

package/components/ui/stack.md

@@ -5,12 +5,13 @@ role: layout
 props:
   - gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" (default "md") — vertical gap between children
   - align?: "start" | "center" | "end" | "stretch" (default "stretch") — cross-axis (horizontal) alignment of children
+  - justify?: "start" | "center" | "end" | "between" | "around" | "evenly" (default "start") — main-axis (vertical) distribution. Reach for this on absolute-positioned overlays (`justify="end"` pins children to the bottom) and split footers (`justify="between"`).
   - asChild?: boolean (default false) — render as the child element via Slot, so `<Stack asChild><section>…</section></Stack>` stamps Stack's classes onto the `<section>` rather than nesting a wrapper div
   - className?: string
   - children: React.ReactNode
 when_to_use: Default top-level layout inside the main slot when composing two or more stacked regions (hero + content + footer, auth card + subtext, etc.). Prefer Stack over hand-rolled `flex flex-col gap-*` so the vertical rhythm is editable through the settings panel.
 composes_with: [Section, Row, Split, Hero, any content component]
-aliases: [stack, vstack, vertical, column, vertical layout]
+aliases: [stack, vstack, vertical, column, vertical layout, v-stack, vertical stack, lazyvstack]
 ---
 
 ```jsx
@@ -30,3 +31,20 @@ aliases: [stack, vstack, vertical, column, vertical layout]
   <Button className="w-full">Continue</Button>
 </Stack>
 ```
+
+```jsx
+// Hero overlay pinned to the bottom — use `justify="end"`, NOT
+// `className="flex flex-col justify-end"`. Stack is already a flex
+// column, so `flex flex-col` in className is dead weight.
+<Stack justify="end" gap="md" className="absolute inset-0 p-10 max-w-2xl">
+  <Badge>Featured</Badge>
+  <h1 className="text-5xl font-semibold">Severance</h1>
+  <Button>Play</Button>
+</Stack>
+```
+
+### Anti-patterns
+
+DO NOT add `flex flex-col` to Stack's className — Stack already applies `flex flex-col` as its base. Same for Row + `flex flex-row`. These are the literal definitions of the primitives.
+
+DO NOT reach for `className="justify-end"` (or `justify-between`, etc.) when the new `justify` prop covers it. Inline-Tailwind layout escapes are how scaffolds slowly drift away from the design system — keep them in props so the settings panel can mutate them.

package/components/ui/switch.md

@@ -9,7 +9,7 @@ props:
   - 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)]
-aliases: [toggle]
+aliases: [toggle, switch, on/off switch, ios toggle, toggle switch, switch control, react native switch]
 ---
 
 ```jsx

package/components/ui/table.md

@@ -7,6 +7,7 @@ props:
   - No variants — styling follows the active theme tokens
 when_to_use: Structured tabular data — rows × columns with alignment requirements. NOT a layout grid — for that use div+Tailwind grid utilities. Keep to <100 rows; larger datasets need virtualisation (not in DS).
 composes_with: [Card (wrap the table), Badge (inside TableCell for status), Checkbox (row selection), Button (row actions)]
+aliases: [table, table view, data table, datatable, grid view, data grid, rows and columns]
 ---
 
 ```jsx

package/components/ui/tabs.md

@@ -3,14 +3,16 @@ name: Tabs
 import: "@gradeui/ui"
 subcomponents: [TabsList, TabsTrigger, TabsContent]
 sizes: [sm, md, lg]
+variants: [pill, underlined]
 props:
   - Tabs: defaultValue?, value?, onValueChange?, orientation?
   - TabsList: size? (sm | md | lg, default md) — t-shirt scale aligned with Button/ToggleGroup heights; cascades to every TabsTrigger via context so set it once on the list
+  - TabsList: variant? (pill | underlined, default pill) — `pill` is the shadcn chip-on-muted look; `underlined` is the minimal text + bottom-border treatment (formerly the separate SimpleTabs component, collapsed into Tabs in May 2026). Cascades to triggers.
   - TabsTrigger: value: string — matches a TabsContent value; tooltip?: string — when set, wraps the trigger in the design-system Tooltip and auto-applies aria-label (useful for icon-only triggers); requires a TooltipProvider somewhere above the tabs
   - TabsContent: value: string — matches a TabsTrigger value
-when_to_use: A small set of peer views within one surface (2–5 tabs). For primary nav use Side Menu/routing. For filters use a filter control, not tabs.
+when_to_use: A small set of peer views within one surface (2–5 tabs). For primary nav use Side Menu/routing. For filters use a filter control, not tabs. Pick `variant="pill"` for app chrome (settings panels, in-card tab strips). Pick `variant="underlined"` for marketing/docs pages and browser-tab-style treatments.
 composes_with: [Card (tabs inside a card body), Dialog, TooltipProvider (required for tooltip prop)]
-aliases: [tabs, tab strip, tab bar]
+aliases: [tabs, tab strip, tab bar, tab view, tabbed interface, pageviewcontroller, react native tab view, underlined tabs, page tabs, segment switcher, simple tabs]
 ---
 
 ```jsx
@@ -37,3 +39,18 @@ aliases: [tabs, tab strip, tab bar]
   </Tabs>
 </TooltipProvider>
 ```
+
+```jsx
+// Underlined variant — replaces the old SimpleTabs component. Use
+// `variant="underlined"` on the TabsList and it cascades to triggers.
+<Tabs defaultValue="profile">
+  <TabsList variant="underlined">
+    <TabsTrigger value="profile">Profile</TabsTrigger>
+    <TabsTrigger value="team">Team</TabsTrigger>
+    <TabsTrigger value="billing">Billing</TabsTrigger>
+  </TabsList>
+  <TabsContent value="profile">…</TabsContent>
+  <TabsContent value="team">…</TabsContent>
+  <TabsContent value="billing">…</TabsContent>
+</Tabs>
+```

package/components/ui/textarea.md

@@ -5,7 +5,7 @@ props:
   - 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.
 composes_with: [Label, Form, Card (in CardContent)]
-aliases: [text area, multiline, comment box, message field]
+aliases: [text area, multiline, comment box, message field, text editor, multi-line text, multiline input, multiline text field, comments box, multiline textinput]
 ---
 
 ```jsx

package/components/ui/toast.md

@@ -1,7 +1,7 @@
 ---
 name: Toaster
 import: "@gradeui/ui"
-aliases: [toast, toaster, sonner, notification, snackbar, alert toast, transient alert]
+aliases: [toast, toaster, sonner, notification, snackbar, alert toast, transient alert, transient banner, banner notification, toastandroid]
 props:
   - Toaster: position? "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right" (default "bottom-right")
   - Toaster: theme? "light" | "dark" | "system"
@@ -9,7 +9,7 @@ props:
   - Toaster: expand?: boolean — keep multiple toasts visually separated rather than stacked
   - Toaster: visibleToasts?: number — max concurrent toasts on screen (default 3)
   - Toaster: duration?: number — default ms before auto-dismiss
-when_to_use: Transient, non-blocking feedback that confirms or warns about an action — "Saved", "Failed to upload", "Copied to clipboard", "Invitation sent". For permanent inline messages keep using Alert. For confirmations that block until acknowledged use Dialog. Mount <Toaster /> ONCE at the root of the app; everywhere else, call the `toast` helper.
+when_to_use: Transient, non-blocking feedback that confirms or warns about an action — "Saved", "Failed to upload", "Copied to clipboard", "Invitation sent". For permanent inline messages reach for Callout. For confirmations that block until acknowledged use Dialog. Mount <Toaster /> ONCE at the root of the app; everywhere else, call the `toast` helper.
 composes_with: [App root layout (single <Toaster /> mount), Form submit handlers (success/error toasts), Async actions]
 notes: Backed by Sonner under the hood — `import { toast } from "sonner"` to fire toasts from anywhere.
 ---

package/components/ui/toggle-group.md

@@ -12,17 +12,24 @@ props:
   - ToggleGroup: size? (sm | md | lg, default md) — cascades to every ToggleGroupItem via context, matches Tabs/Button heights
   - ToggleGroup: variant? (default | outline)
   - ToggleGroupItem: value: string — what the group reports when this item is pressed
+  - ToggleGroupItem: tooltip?: ReactNode — when set, wraps the item in a Tooltip; required for icon-only items where the visible chrome doesn't carry a label
+  - ToggleGroupItem: tooltipSide? ("top" | "right" | "bottom" | "left", default "top") — side the tooltip renders on
+  - ToggleGroupItem: tooltipDelay?: number — per-item delay override; falls back to the upstream TooltipProvider's delayDuration
 when_to_use: A small set of mutually-exclusive (`type="single"`) or independent (`type="multiple"`) binary options that live side-by-side as a segmented control — viewport size picker (Mobile/Tablet/Desktop), text alignment, view density. Reads identically to a TabsList of the same size; reach for ToggleGroup when each option emits a value (like a form input) rather than swapping panels. Use Tabs for panel switching, Toggle for a single on/off.
 composes_with: [Card (header controls), Row, AppShellHeader chrome, settings panels]
-aliases: [toggle group, segmented control, segmented buttons, button group, pill group, view selector]
+aliases: [toggle group, segmented control, segmented buttons, button group, pill group, view selector, segmented picker, segmentedcontrolios, segmented buttons group, rn segmented control]
 ---
 
 ```jsx
-// Single-select segmented control — viewport size picker.
+// Single-select segmented control — viewport size picker with
+// icon-only items + tooltips. The `tooltip` prop also fills in
+// `aria-label` for screen readers, so consumers don't have to
+// duplicate the label.
 <ToggleGroup type="single" defaultValue="desktop" size="sm">
-  <ToggleGroupItem value="mobile" aria-label="Mobile"><Smartphone /></ToggleGroupItem>
-  <ToggleGroupItem value="tablet" aria-label="Tablet"><Tablet /></ToggleGroupItem>
-  <ToggleGroupItem value="desktop" aria-label="Desktop"><Monitor /></ToggleGroupItem>
+  <ToggleGroupItem value="mobile" tooltip="Mobile — 390px"><Smartphone /></ToggleGroupItem>
+  <ToggleGroupItem value="tablet" tooltip="Tablet — 768px"><Tablet /></ToggleGroupItem>
+  <ToggleGroupItem value="desktop" tooltip="Desktop — 1024px"><Monitor /></ToggleGroupItem>
+  <ToggleGroupItem value="responsive" tooltip="Responsive — fills the column"><MoveHorizontal /></ToggleGroupItem>
 </ToggleGroup>
 ```
 

package/components/ui/toolbar.md

@@ -0,0 +1,167 @@
+---
+name: Toolbar
+import: "@gradeui/ui"
+role: layout
+subcomponents: [ToolbarSlot]
+props:
+  - leading?: React.ReactNode — left-aligned region (logo + primary nav)
+  - center?: React.ReactNode — center region (search, page title, segmented control)
+  - trailing?: React.ReactNode — right-aligned region (action icons, avatar, primary CTA)
+  - children?: React.ReactNode — escape hatch; bypasses slot layout
+  - position?: "top" | "bottom" | "inline" (default "top") — border placement
+  - variant?: "default" | "subtle" | "transparent" (default "default")
+  - size?: "sm" | "md" | "lg" (default "md") — height + padding
+  - sticky?: boolean (default false) — pin to top/bottom of scroll container
+  - aria-label?: string (default "Toolbar") — required by WAI-ARIA toolbar pattern
+  - className?: string
+when_to_use: |
+  ANY three-region chrome bar — the leading/center/trailing pattern Apple HIG
+  describes as a "Toolbar." App window chrome (Reddit, Twitter, GitHub, Linear,
+  most desktop apps), section toolbars inside Cards or panels, bottom action
+  bars on mobile layouts, persistent footer toolbars.
+
+  Don't hand-roll `<Row justify="between">` with a flex-1 on a middle child and
+  manual min-width juggling — Toolbar gives you the canonical `auto 1fr auto`
+  grid for free, with `role="toolbar"`, `data-gds-part` markers, position
+  variants for top/bottom borders, and sticky sizing.
+
+  Slot semantics:
+    leading   — Logo + nav rail (e.g. a `<Row>` of Buttons or Link components)
+    center    — Search input, page title chip, segmented Tab strip
+    trailing  — Icon buttons, notification bell, avatar, primary CTA
+
+  When a slot is omitted, its column collapses cleanly. Center stays visually
+  centered in the bar regardless of leading/trailing widths because the grid
+  template is `auto 1fr auto` (the center column absorbs available width).
+
+  Use as the top child of `<AppShellHeader>` for window-level chrome:
+    <AppShellHeader>
+      <Toolbar leading={<Logo/>} center={<Search/>} trailing={<Avatar/>} />
+    </AppShellHeader>
+
+  Use directly inside a Card or page section for section-scoped toolbars:
+    <Card>
+      <Toolbar size="sm" variant="subtle" leading={...} trailing={...} />
+      {content}
+    </Card>
+composes_with: [Button, Avatar, Input, Logo, Badge, AppShellHeader, Card, Row, Stack]
+aliases: [
+  toolbar, tool bar, top bar, topbar, app bar, appbar, header bar, header,
+  navigation bar, nav bar, navbar, window chrome, window toolbar, title bar,
+  titlebar, action bar, actionbar, command bar, ribbon,
+  three-region nav, leading center trailing, leading-center-trailing,
+  apple hig toolbar, hig toolbar, native toolbar, segmented toolbar,
+  bottom toolbar, footer toolbar, fixed toolbar, sticky header
+]
+notes: |
+  Apple HIG reference: https://developer.apple.com/design/human-interface-guidelines/toolbars
+  WAI-ARIA toolbar pattern: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+
+  Roving tabindex for arrow-key navigation between toolbar items is NOT
+  implemented in v1. For a tight cluster of related controls (an editor
+  toolbar — B / I / S / link), compose with @radix-ui/react-toolbar inside
+  the slots if you need arrow-key navigation. For an app chrome bar (logo
+  + nav + actions), standard tab order is the expected pattern and a
+  single aria-label is sufficient.
+
+  Center vs. leading for the page title:
+    - Use `center` for a CENTERED page title (Apple-style window chrome).
+    - Use `leading` after the logo for a LEFT-ALIGNED page title (web-app
+      style — GitHub, Linear). Mixing is fine.
+---
+
+```jsx
+// App window chrome — Reddit / Twitter / GitHub shape.
+<Toolbar
+  leading={
+    <Row gap="sm" align="center">
+      <Logo />
+      <Button variant="ghost" size="sm">Home</Button>
+      <Button variant="ghost" size="sm">Explore</Button>
+    </Row>
+  }
+  center={
+    <Input placeholder="Search" className="max-w-md" />
+  }
+  trailing={
+    <Row gap="xs" align="center">
+      <Button variant="ghost" size="icon"><Bell /></Button>
+      <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+    </Row>
+  }
+/>
+```
+
+```jsx
+// Section toolbar inside a Card — small, subtle, no border.
+<Card>
+  <Toolbar
+    size="sm"
+    variant="subtle"
+    position="inline"
+    leading={<span className="text-sm font-medium">Recent activity</span>}
+    trailing={
+      <Button variant="ghost" size="sm">View all</Button>
+    }
+  />
+  <CardContent>…</CardContent>
+</Card>
+```
+
+```jsx
+// Bottom action toolbar — common on mobile-style detail pages.
+<Toolbar
+  position="bottom"
+  sticky
+  leading={<Button variant="outline" size="sm">Cancel</Button>}
+  trailing={<Button size="sm">Save changes</Button>}
+/>
+```
+
+```jsx
+// Inside AppShellHeader — the canonical "app chrome" composition.
+<AppShell nav="side">
+  <AppShellHeader>
+    <Toolbar
+      leading={<Logo />}
+      trailing={
+        <Row gap="xs">
+          <Button variant="ghost" size="icon"><Bell /></Button>
+          <Avatar><AvatarFallback>AL</AvatarFallback></Avatar>
+        </Row>
+      }
+    />
+  </AppShellHeader>
+  <AppShellNav placement="side">{/* sidebar */}</AppShellNav>
+  <AppShellMain>{/* content */}</AppShellMain>
+</AppShell>
+```
+
+## Anti-patterns
+
+```jsx
+// ❌ Hand-rolling the three-region grid every time.
+<Row justify="between" align="center" className="px-4 py-3 border-b border-border">
+  <Row gap="sm" align="center"><Logo /></Row>
+  <div className="flex-1 flex justify-center"><Input className="max-w-md" /></div>
+  <Row gap="xs" align="center"><Bell /><Avatar /></Row>
+</Row>
+
+// ✅ Toolbar collapses this to slot props + the right ARIA role.
+<Toolbar
+  leading={<Logo />}
+  center={<Input className="max-w-md" />}
+  trailing={<Row gap="xs"><Bell /><Avatar /></Row>}
+/>
+```
+
+```jsx
+// ❌ Cramming an editor-style toolbar (B / I / S / link) into the leading
+//    slot. Toolbar's slot layout is for chrome bars; for a tight cluster
+//    of related controls with arrow-key navigation, compose with Radix
+//    Toolbar primitives inside the leading slot OR use a plain <Row>.
+
+// ✅ Editor toolbar lives inside the section it's editing, not in the
+//    window chrome. Use a Row of Buttons or @radix-ui/react-toolbar
+//    inside the section.
+```

package/components/ui/tooltip.md

@@ -10,7 +10,7 @@ props:
   - TooltipContent: side? "top" | "right" | "bottom" | "left" (default "top"); align? "start" | "center" | "end"; sideOffset?: number
 when_to_use: A short, non-essential label that explains a control on hover/focus — icon-only buttons in toolbars, abbreviated column headers, status dots. NEVER hide critical info inside a tooltip — they're invisible on touch and can be skipped by screen readers if implemented carelessly. For richer hover content use HoverCard. For inline help text that's always visible, use a description paragraph.
 composes_with: [Button (icon-only), Toggle, TabsTrigger (the canonical tabs already have a `tooltip` prop that wraps this), Avatar (status badge meaning)]
-aliases: [tooltip, tip, hover tip, hint, label on hover]
+aliases: [tooltip, tip, hover tip, hint, label on hover, help tag, hint, helper text bubble, info tip]
 ---
 
 ```jsx

package/components/ui/video-player.md

@@ -9,13 +9,13 @@ props:
   - muted?: boolean (default = autoPlay)
   - pauseOffscreen?: boolean (default true) — pause when scrolled out of viewport
   - aspect?: "video" | "square" | "portrait" | "wide" | "auto" (default "video")
-  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--rds-media-radius`
+  - radius?: "none" | "sm" | "md" | "lg" | "xl" (default "lg") — driven by `--gds-media-radius`
   - objectFit?: "cover" | "contain" | "fill" (default "cover")
   - poster?: string — image shown before playback. Always rendered as a `loading="lazy"` `<img>` overlay (not the native `poster` attribute, which fetches eagerly).
   - playbackRate?: number (default 1)
 when_to_use: HTML5 video wrapped in the shared media surface. Controls-on for a standard player, controls-off (+ autoplay/muted/loop) for hero / background video. Prefer Rive for anything interactive, Three Scene for shader backgrounds.
 composes_with: [MediaSurface (internal), Card (wrap for thumbnail grids)]
-aliases: [video, mp4, movie, webm, clip]
+aliases: [video, mp4, movie, webm, clip, video view, av player, react native video, video element]
 notes: Poster images are always lazy-loaded. We don't use the native `<video poster>` attribute because browsers fetch it eagerly even when the surface is off-screen, which wastes the offscreen-pause savings. Instead we render `<img loading="lazy" decoding="async">` layered over the video, then fade it out on `onPlaying`. When no `src` is given nothing renders — always pass a URL.
 ---
 

package/dist/contracts.d.mts

@@ -0,0 +1,14 @@
+import { ComponentContract } from '@gradeui/contracts';
+
+/**
+ * Component contract registry — auto-managed by
+ * scripts/generate-contracts.mjs. Hand-authored contracts (MediaSurface,
+ * etc.) are also wired in here; the generator preserves them on each
+ * run.
+ */
+
+declare const COMPONENT_CONTRACTS: Readonly<Record<string, ComponentContract>>;
+declare function getComponentContract(componentName: string | null | undefined): ComponentContract | null;
+declare function listContractedComponents(): string[];
+
+export { COMPONENT_CONTRACTS, getComponentContract, listContractedComponents };