@gradeui/ui 0.10.0 → 1.0.0

package/components/ui/accordion.md

@@ -13,7 +13,7 @@ props:
   - AccordionContent: children: React.ReactNode — the body that animates in
 when_to_use: Long-form content that would overwhelm if shown all at once — FAQs, settings groups, "what's included" sections, nested help. For tab-style peer views with one always visible, reach for Tabs. For a single show/hide reveal use Collapsible.
 composes_with: [Card (as a faq inside a card body), Section primitives]
-aliases: [accordion, faq, expand, collapse list, disclosure list]
+aliases: [accordion, faq, expand, collapse list, disclosure list, disclosure group, outline group, expandable list, sectionlist]
 ---
 
 ```jsx

package/components/ui/ai-chat-composer.md

@@ -0,0 +1,37 @@
+---
+name: AIChatComposer
+import: "@gradeui/ui"
+props:
+  - value: string — controlled textarea value
+  - onChange: (next: string) => void — fires for every textarea change
+  - onSend: (text: string, attachments?: ChatAttachment[]) => void — fires when the user submits (Enter or click Send); composer validates that text or attachments exist before firing
+  - isLoading?: boolean — disables the textarea + paperclip and swaps Send for Stop
+  - onStop?: () => void — fires when the user clicks Stop; without this, Stop renders disabled
+  - placeholder?: string
+  - maxLength?: number — hard cap passed to the underlying `<textarea>`
+  - showHint?: boolean — show the "Press Enter… · Paste images" hint below the card; default true, set false when the host renders its own footer
+  - className?: string
+when_to_use: The reusable "input card" for any chat surface — auto-growing textarea, image attachments via paperclip and clipboard paste, attachment chips with previews, Send/Stop toggle, controlled value. Drop in below any messages list. Use this when you want the input affordances of `<AIChat>` but you're rendering your own messages list / scrollarea / header (e.g. Studio's left-column chat, where SelectionChip and SettingsPanel sit between messages and composer). For the full canned chat block, use `<AIChat>` instead.
+composes_with: [AIChat (uses this internally), Card (host above), ScrollArea (place messages above)]
+aliases: [chat composer, chat input, prompt composer, message input]
+---
+
+```jsx
+const [value, setValue] = useState("");
+
+<AIChatComposer
+  value={value}
+  onChange={setValue}
+  onSend={(text, attachments) => {
+    // text is already trimmed; attachments is undefined when none.
+    // The composer owns each attachment's previewUrl — don't revoke
+    // it yourself, just hand the File objects off (e.g. upload, or
+    // build multimodal message parts).
+    sendToAssistant(text, attachments?.map((a) => a.file));
+    setValue("");
+  }}
+  isLoading={isStreaming}
+  onStop={() => stop()}
+  placeholder="Describe a UI…"
+/>
+```

package/components/ui/ai-chat.md

@@ -2,34 +2,80 @@
 name: AIChat
 import: "@gradeui/ui"
 props:
-  - messages?: ChatMessage[] — `{ id, role: "user" | "assistant", content, timestamp }`; defaults to empty
-  - onSendMessage?: (message: string) => void — fires when the user submits a query
-  - isLoading?: boolean — shows a typing indicator on the last assistant turn
-  - placeholder?: string — input placeholder text
-  - suggestedPrompts?: { icon?: React.ReactNode; text: string }[] — empty-state quick prompts
+  - messages?: ChatMessage[] — `{ id, role: "user" | "assistant", content, timestamp, thinking?, steps?, usage?, refs?, actions?, duration? }`; defaults to empty
+  - onSendMessage?: (message: string, attachments?: ChatAttachment[]) => void — fires when the user submits via the default composer; ignored if `composerSlot` is set
+  - isLoading?: boolean — shows a typing indicator at the bottom of the message list
+  - placeholder?: string — composer placeholder text (ignored if `composerSlot` is set)
+  - title?: string — header title; defaults to "AI Assistant"
+  - titleIcon?: React.ReactNode — optional icon rendered before the title (e.g. `<Sparkles />`)
+  - headerTokens?: number — optional session-level token total shown on the right of the header; rendered as "N tokens" with a small gauge icon when set
+  - headerEnd?: React.ReactNode — optional arbitrary content appended after `headerTokens` on the right of the header
+  - showUsage?: boolean — show the per-turn `usage` strip below the assistant bubble; default false
+  - showRefs?: boolean — show the per-turn `refs` strip below the assistant bubble; default false
+  - showActions?: boolean — render per-turn `actions` chips when a message has them; default true
+  - showDuration?: boolean — render the per-turn wall-clock duration ("2.3s") below the assistant bubble when a message carries `duration`; default false
+  - showThinking?: boolean — render the per-turn reasoning ("Thoughts") disclosure above the assistant prose when a message carries `thinking`; collapsed by default, click to expand; default false
+  - showSteps?: boolean — render the per-turn step timeline above the assistant prose when a message carries `steps`; collapsed view shows the current running step (or "N steps completed"), click to expand the vertical timeline with status glyphs; default false
+  - thinkingPhrase?: string — override the "Thinking" label in the loading indicator
+  - suggestedPrompts?: { icon?: React.ReactNode; text: string }[] — empty-state quick prompts (ignored if `emptyStateSlot` is set)
+  - emptyStateSlot?: React.ReactNode — replaces the default empty state entirely
+  - errorSlot?: React.ReactNode — rendered after the messages list (typically an error banner)
+  - composerAboveSlot?: React.ReactNode — rendered between the messages and the composer (selection chip, settings panel)
+  - composerBelowSlot?: React.ReactNode — rendered below the composer (disclaimer, char counter)
+  - composerSlot?: React.ReactNode — full override of the composer; when provided, `onSendMessage` + `placeholder` are unused
+  - bare?: boolean — strip the outer card chrome (background, border, rounded corners) so the chat takes the surface of its container; default false (keeps the canned card look)
+  - assistantBubble?: boolean — whether assistant messages render with a bubble (background + border + padding + rounded corners); default true. Set false for a Claude.ai-style chromeless transcript where assistant text sits on the surface and only user turns wear a bubble.
   - className?: string
-when_to_use: A pre-built chat block — paste it in to get a working LLM chat surface without composing the message list, autoscroll, suggested prompts, and submit input yourself. Reach for it as the "AI panel" in an admin/support tool, or to demo an LLM-driven feature inside a marketing page. For Studio-grade chat with file refs and streaming structured output, you'll outgrow this and want a custom composition built on Textarea + Card + ScrollArea.
-composes_with: [Card (host in a sidebar panel), Sheet (mobile drawer), Stack (place above other content)]
-aliases: [ai chat, chat panel, chat block, llm chat, assistant panel, copilot chat]
+when_to_use: A flexible chat block — header + scrollable message list + composer. Out of the box it looks like a polished "AI panel"; under it, every region is a slot so hosts can compose richer chat surfaces (e.g. Studio's left column with selection chip + settings panel above the composer, an error banner inline, per-message usage / refs / actions). Per-turn token usage, refs, and actions are optional and gated by `showUsage` / `showRefs` / `showActions` — leave them off for product-facing chats, turn them on for developer-facing ones where transparency matters. Composes with [[AIChatComposer]] (rendered internally; can be slotted in with custom props via `composerSlot`).
+composes_with: [Card (host in a sidebar panel), Sheet (mobile drawer), Stack (place above other content), AIChatComposer (internal composer; slot to override)]
+aliases: [ai chat, chat panel, chat block, llm chat, assistant panel, copilot chat, ai assistant]
 ---
 
 ```jsx
-const [messages, setMessages] = useState([]);
-const [loading, setLoading] = useState(false);
-
+// Canned use — no slots, no metadata. Matches the original API.
 <AIChat
   messages={messages}
   isLoading={loading}
-  onSendMessage={async (text) => {
-    setMessages((m) => [...m, { id: uid(), role: "user", content: text, timestamp: new Date() }]);
-    setLoading(true);
-    const reply = await fetchAssistant(text);
-    setMessages((m) => [...m, { id: uid(), role: "assistant", content: reply, timestamp: new Date() }]);
-    setLoading(false);
-  }}
-  suggestedPrompts={[
-    { icon: <Sparkles />, text: "Summarise this page" },
-    { icon: <Lightbulb />, text: "Suggest next steps" },
-  ]}
+  onSendMessage={(text, attachments) => send(text, attachments)}
+/>
+```
+
+```jsx
+// Developer-facing chat with per-turn usage + refs + a "Rendered in
+// preview →" action on assistant turns. `headerTokens` shows a session
+// running total. All optional — flip them via your own settings UI.
+<AIChat
+  title="Ask Grade AI"
+  titleIcon={<Sparkles className="h-3 w-3" />}
+  headerTokens={sessionTokenTotal}
+  showUsage
+  showRefs
+  messages={messages.map((m) => ({
+    id: m.id,
+    role: m.role,
+    content: textFromParts(m.parts),
+    timestamp: new Date(),
+    usage: usageFromMetadata(m.metadata),
+    refs: refsFromMetadata(m.metadata),
+    actions: hasJsxBlock(m)
+      ? [{ id: "preview", label: "Rendered in preview →", icon: <Code2 className="h-3 w-3" />, onClick: () => focusPreview() }]
+      : undefined,
+  }))}
+  isLoading={isStreaming}
+  thinkingPhrase={rotatingPhrase}
+  composerAboveSlot={<><SelectionChip /><SettingsPanel /></>}
+  composerBelowSlot={<InputFooter charCount={input.length} limit={1000} />}
+  composerSlot={
+    <AIChatComposer
+      value={input}
+      onChange={setInput}
+      onSend={handleSend}
+      isLoading={isStreaming}
+      onStop={stop}
+      maxLength={1000}
+      showHint={false}
+    />
+  }
+  errorSlot={error && <ErrorBanner error={error} />}
 />
 ```

package/components/ui/alert.md

@@ -1,21 +0,0 @@
----
-name: Alert
-import: "@gradeui/ui"
-subcomponents: [AlertTitle, AlertDescription]
-variants: [default, destructive, success, warning, info, highlight]
-props:
-  - variant? (default | destructive | success | warning | info | highlight)
-  - All native div HTML attrs
-when_to_use: Inline status/feedback that sits inside the layout flow. NOT a toast (use Sonner for transient). NOT a modal (use Dialog). Put an icon as first child — it will be auto-positioned; AlertTitle + AlertDescription follow.
-composes_with: [lucide-react icons as first child, Button (inside AlertDescription), Card (as a section callout)]
----
-
-Variant tokens come from theme (`--destructive-soft`, `--success-deep`, etc.) so they restyle with the active Grade theme.
-
-```jsx
-<Alert variant="warning">
-  <AlertTriangle />
-  <AlertTitle>Low disk space</AlertTitle>
-  <AlertDescription>2GB remaining on /dev/sda1.</AlertDescription>
-</Alert>
-```

package/components/ui/app-shell.md

@@ -2,30 +2,67 @@
 name: AppShell
 import: "@gradeui/ui"
 role: layout
-subcomponents: [AppShellNav, AppShellMain]
+subcomponents: [AppShellHeader, AppShellNav, AppShellAside, AppShellMain, AppShellFooter]
 props:
-  - nav?: "none" | "top" | "side" (default "none") — layout structure. "top" puts the nav above main, "side" to the left, "none" hides it
+  - nav?: "none" | "top" | "side" | "three-pane" (default "none") — layout structure
   - asChild?: boolean (default false) — render as the child element via Slot
   - className?: string
   - children: React.ReactNode
-when_to_use: The top-level page scaffold for app-like layouts — any screen that needs a nav region plus a content region. Reach for AppShell instead of hand-rolled `grid grid-cols-[auto_1fr]` so the layout shape (top vs side nav, constrained vs full-width main) is a prop the settings panel can mutate. Drop a Stack of nav items into AppShellNav for the nav region; drop a Stack into AppShellMain for the page's vertical rhythm.
-composes_with: [Stack, Row, Card, Button, Separator, any page content]
-aliases: [app shell, page shell, layout, app layout, dashboard shell, scaffold]
+when_to_use: |
+  The top-level page scaffold for any app-like or marketing layout. Reach for AppShell
+  instead of hand-rolling `grid grid-cols-[auto_1fr]` so the layout shape (top nav,
+  side nav, three-pane Slack/Mail/Notion shape, constrained vs full-width main) is a
+  prop the settings panel can mutate. Don't compose top-level layouts from raw grid
+  templates — the four variants below cover most app shapes.
+
+  Pick the `nav` variant from the source:
+    nav="none"        — Single column. Marketing landing, login, splash.
+    nav="top"         — Top bar + content. Reddit, Twitter chrome.
+    nav="side"        — Left nav + content. Linear, Notion sidebar shape.
+    nav="three-pane"  — **Narrow icon rail + Aside + Main.** The Slack /
+                        WhatsApp / Mail / Plane / Discord / Notion-with-pages
+                        shape. ANY time you see a vertical icon rail next to
+                        a separate list/sidebar, this is the answer — don't
+                        reach for raw `<div className="grid">` with three
+                        column tracks.
+composes_with: [Stack, Row, Card, Button, Separator, Sidebar, Toolbar, any page content]
+aliases: [
+  app shell, page shell, layout, app layout, dashboard shell, scaffold,
+  navigation split view, navigationsplitview, split view layout,
+  safe area view, safeareaview,
+  three pane, three-pane, three column, three-column, master-detail-detail,
+  rail and sidebar, icon rail, sidebar layout, mail shape, slack shape,
+  notion shape, discord shape, whatsapp shape, plane shape
+]
 notes: |
-  Three parts:
-    AppShell        — <div> by default; sets the grid (nav=none|top|side)
-    AppShellNav     — <nav> by default; props: placement ("top"|"side"|"none", match AppShell.nav), sticky (boolean, default true)
-    AppShellMain    — <main> by default; props: maxWidth ("full"|"container", default "full")
-  All three support asChild and emit data-gds-part ("app-shell", "app-shell-nav", "app-shell-main").
+  Five slots, all CSS-grid placed by `grid-area` so child order doesn't matter:
+
+    AppShellHeader  — <header>; full-bleed across the top
+    AppShellNav     — <nav>;    placement="top"|"side"|"none"
+    AppShellAside   — <aside>;  middle column in three-pane
+    AppShellMain    — <main>;   props: maxWidth ("full"|"container", default "full")
+    AppShellFooter  — <footer>; full-bleed across the bottom
+
+  Three-pane sizing: the Aside column reads `--gds-app-shell-aside` (default 320px).
+  Override on the AppShell root to tighten or widen:
+    style={{ "--gds-app-shell-aside": "245px" }}    // Plane-style
+    style={{ "--gds-app-shell-aside": "380px" }}    // WhatsApp-style
+
+  Nav rail in three-pane sizes to its content's intrinsic width (column track is
+  `auto`). Add `w-[60px]` etc. to the AppShellNav child so the rail has a stable width.
+
+  All slots support asChild and emit data-gds-part ("app-shell", "app-shell-nav",
+  "app-shell-aside", "app-shell-main", "app-shell-header", "app-shell-footer").
   Pure structure — no collapse state, no context. Server-renders cleanly.
-  For nav placement="side" + sticky=true the nav gets h-screen + self-scroll, so long nav lists don't push main down.
+  For nav placement="side" + sticky=true (default) the nav gets h-screen + self-scroll,
+  so long nav lists don't push main down.
 ---
 
 ```jsx
-// Side nav + full-width main — the classic dashboard shape.
+// nav="side" — classic dashboard: left nav + main.
 <AppShell nav="side">
   <AppShellNav placement="side">
-    {/* nav items — Stack of Buttons, a SideMenu, etc. */}
+    <Sidebar>{/* sidebar items */}</Sidebar>
   </AppShellNav>
   <AppShellMain>
     <Stack gap="lg" className="p-6">
@@ -36,12 +73,36 @@ notes: |
 ```
 
 ```jsx
-// Top nav + constrained content — marketing / docs / settings pages.
+// nav="three-pane" — Slack / WhatsApp / Mail / Plane shape.
+// Narrow icon rail + middle Aside + main content area. Override
+// the Aside width via the CSS var on the root.
+<AppShell nav="three-pane" style={{ "--gds-app-shell-aside": "260px" }}>
+  <AppShellNav placement="side">
+    {/* icon rail — stack of icon buttons, ~60px wide */}
+    <Stack gap="sm" align="center" className="w-[60px] py-3">
+      <RailButton icon={<Home/>} />
+      <RailButton icon={<Inbox/>} />
+      <RailButton icon={<Settings/>} />
+    </Stack>
+  </AppShellNav>
+  <AppShellAside>
+    {/* middle column — chat list, project list, mailbox list */}
+    <Sidebar collapsible={false}>
+      <SidebarHeader>…</SidebarHeader>
+      <SidebarContent>…</SidebarContent>
+    </Sidebar>
+  </AppShellAside>
+  <AppShellMain>
+    {/* main content — active chat, active project page, etc. */}
+  </AppShellMain>
+</AppShell>
+```
+
+```jsx
+// nav="top" — marketing / docs / settings layout.
 <AppShell nav="top">
   <AppShellNav placement="top">
-    <Row justify="between" align="center" className="px-6 py-3">
-      {/* logo + nav buttons */}
-    </Row>
+    <Toolbar leading={<Logo/>} trailing={<Avatar/>} />
   </AppShellNav>
   <AppShellMain maxWidth="container">
     <Stack gap="lg" className="py-8">
@@ -52,10 +113,66 @@ notes: |
 ```
 
 ```jsx
-// No nav — just a shell for a single-screen prototype.
+// nav="none" — single screen prototype, login, splash.
 <AppShell nav="none">
   <AppShellMain maxWidth="container">
     {/* page content */}
   </AppShellMain>
 </AppShell>
 ```
+
+```jsx
+// Full chrome — header + three-pane body + footer.
+<AppShell nav="three-pane">
+  <AppShellHeader>
+    <Toolbar leading={<Logo/>} center={<Search/>} trailing={<Avatar/>} />
+  </AppShellHeader>
+  <AppShellNav placement="side">{/* icon rail */}</AppShellNav>
+  <AppShellAside>{/* list pane */}</AppShellAside>
+  <AppShellMain>{/* content */}</AppShellMain>
+  <AppShellFooter>
+    <Row justify="between" className="px-4 py-2 text-xs">© Brand · v1.0</Row>
+  </AppShellFooter>
+</AppShell>
+```
+
+## Anti-patterns
+
+```jsx
+// ❌ Hand-rolling a three-pane grid when AppShell nav="three-pane" exists.
+//    You lose: the CSS-var Aside sizing knob, the rail's auto-width
+//    column track, the grid-area routing that lets you add a Header
+//    later without re-doing the grid.
+<div className="grid h-screen" style={{ gridTemplateColumns: "60px 280px 1fr" }}>
+  <Rail />
+  <Sidebar />
+  <Main />
+</div>
+
+// ✅ The Grade way.
+<AppShell nav="three-pane" style={{ "--gds-app-shell-aside": "280px" }}>
+  <AppShellNav placement="side"><Rail /></AppShellNav>
+  <AppShellAside><Sidebar /></AppShellAside>
+  <AppShellMain><Main /></AppShellMain>
+</AppShell>
+```
+
+```jsx
+// ❌ Stacking nav at the top + another nav on the side via raw grid.
+//    Use AppShellHeader + nav="side" instead.
+<div className="min-h-screen grid" style={{ gridTemplateRows: "auto 1fr" }}>
+  <TopBar />
+  <div className="grid" style={{ gridTemplateColumns: "260px 1fr" }}>
+    <Sidebar />
+    <Main />
+  </div>
+</div>
+
+// ✅ Use AppShellHeader for the full-bleed top bar; pick nav based on
+//    what's below it.
+<AppShell nav="side">
+  <AppShellHeader><Toolbar leading={<Logo/>} trailing={<Avatar/>} /></AppShellHeader>
+  <AppShellNav placement="side"><Sidebar /></AppShellNav>
+  <AppShellMain><Main /></AppShellMain>
+</AppShell>
+```

package/components/ui/avatar.md

@@ -6,8 +6,19 @@ props:
   - Avatar: className? — set size via utilities (default h-10 w-10)
   - AvatarImage: src, alt
   - AvatarFallback: initials/icon rendered when image fails or loads
-when_to_use: User/entity identity in lists, cards, headers. Always include AvatarFallback so load failure doesn't leave a gap.
+when_to_use: User/entity identity for PEOPLE — profile pictures, author rows, member lists, account headers. Circular by default; the AvatarFallback initials read as a person's name. Always include AvatarFallback so load failure doesn't leave a gap.
 composes_with: [Card (in CardHeader), Table cells, Badge (placed next to for status), Skeleton (loading state)]
+aliases: [profile picture, user image, account image, avatar, person glyph, user avatar, profile image, react native avatar]
+notes: |
+  Anti-patterns to avoid:
+
+  - DO NOT use Avatar for album art, posters, product photos, landscape
+    images, or anything that isn't a person. Use <MediaSurface> with the
+    appropriate `hint` ("album", "poster", "product", "landscape", etc.) —
+    MediaSurface also renders initials-style fallbacks at small sizes
+    derived from `alt`, so you don't lose the affordance.
+  - DO NOT wrap Avatar inside MediaSurface to get an initials fallback.
+    MediaSurface has that built in via `alt` + the size-tiered placeholder.
 ---
 
 ```jsx

package/components/ui/badge.md

@@ -6,9 +6,9 @@ props:
   - variant? (see list above)
   - rounded? (default | full) — "full" gives a pill shape
   - All native div HTML attrs
-when_to_use: Compact status chips, counts, tags, pills. For higher-signal inline status → use Alert. For solid CTAs → Button. Soft/outline variants are quieter; solid variants are loud.
+when_to_use: Compact status chips, counts, tags, pills. For higher-signal inline status → use Callout. For solid CTAs → Button. Soft/outline variants are quieter; solid variants are loud.
 composes_with: [Card, Table (inside a cell), Avatar (next to it), anywhere inline]
-aliases: [chip, tag, pill, label chip]
+aliases: [chip, tag, pill, label chip, badge, tag view, status pill, token, count badge]
 ---
 
 ```jsx

package/components/ui/breadcrumb.md

@@ -4,15 +4,16 @@ import: "@gradeui/ui"
 subcomponents: [BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis]
 props:
   - Breadcrumb: aria-label? (defaults to "breadcrumb") — passed to the underlying <nav>
+  - Breadcrumb: separator? — **tree-wide default** for every <BreadcrumbSeparator/> inside. Pass a string ("/", "›", "•"), a lucide icon (`<Slash/>`, `<ChevronRight/>`), or any ReactNode. Default: `<ChevronRight/>`. Set once on the root; every separator below picks it up via context.
   - BreadcrumbList: className? — the <ol> wrapper; usually no overrides needed
   - BreadcrumbItem: className? — wraps a single crumb (link or page)
   - BreadcrumbLink: href? — renders as <a> when set, <button> when not; asChild? wraps a custom element
   - BreadcrumbPage: className? — the current page; rendered as a non-interactive <span> with aria-current="page"
-  - BreadcrumbSeparator: children? (defaults to a chevron) — the visual separator between crumbs
+  - BreadcrumbSeparator: children? — per-instance override of the separator glyph. When set, beats the root's `separator` prop for this one slot. When not set, falls back to the root's `separator`, then to `<ChevronRight/>`.
   - BreadcrumbEllipsis: className? — collapsed middle crumbs marker, use between BreadcrumbItems
 when_to_use: Reach for Breadcrumb whenever a screen sits inside a hierarchy and you want the path back to the top to be visible. Common spots: above page titles in admin/CMS screens, top of Settings detail pages, after a router redirect when the URL implies depth. Use the current page as a <BreadcrumbPage> (non-clickable) and prior levels as <BreadcrumbLink>. For a horizontal "top nav" of peer destinations use Side Menu or Tabs instead — Breadcrumb is strictly for hierarchical path.
 composes_with: [AppShellMain, Card (in CardHeader), Dialog]
-aliases: [breadcrumb, breadcrumbs, crumbs, path, page hierarchy]
+aliases: [breadcrumb, breadcrumbs, crumbs, path, page hierarchy, path bar, navigation trail, finder path]
 ---
 
 ```jsx
@@ -30,6 +31,52 @@ aliases: [breadcrumb, breadcrumbs, crumbs, path, page hierarchy]
 </Breadcrumb>
 ```
 
+```jsx
+// Slash-separated, finder / URL-style. Set once on the root and every
+// <BreadcrumbSeparator/> below picks it up via context.
+import { Slash } from "lucide-react";
+
+<Breadcrumb separator={<Slash />}>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/blog">Blog</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Article</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
+```jsx
+// Plain glyph — string children also work.
+<Breadcrumb separator="›">…</Breadcrumb>
+<Breadcrumb separator="/">…</Breadcrumb>
+<Breadcrumb separator="•">…</Breadcrumb>
+```
+
+```jsx
+// Per-instance override beats the root default. Useful for "different
+// separator just before the current page" designs (e.g. an arrow that
+// points at the leaf).
+import { ArrowRight, ChevronRight } from "lucide-react";
+
+<Breadcrumb separator={<ChevronRight />}>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbLink href="/team">Team</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator><ArrowRight /></BreadcrumbSeparator>
+    <BreadcrumbItem><BreadcrumbPage>Settings</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```
+
 ```jsx
 // Deep path with collapsed middle — useful when the path is long.
 <Breadcrumb>

package/components/ui/button.md

@@ -1,16 +1,17 @@
 ---
 name: Button
 import: "@gradeui/ui"
-variants: [default, destructive, outline, secondary, ghost, link]
+variants: [default, destructive, outline, secondary, ghost, link, raised]
 sizes: [sm, md, lg, icon]
 props:
-  - variant? (default | destructive | outline | secondary | ghost | link)
+  - variant? (default | destructive | outline | secondary | ghost | link | raised)
   - size? (sm | md | lg | icon) — t-shirt scale aligned with Tabs/ToggleGroup heights (sm=h-7, md=h-8, lg=h-10). `default` still works as an alias for `md`.
   - asChild?: boolean — renders as the child element (use to wrap <a>/<Link>)
   - disabled?: boolean
   - All native button HTML attrs (onClick, type, etc.)
-when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
+when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, variant="raised" for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
 composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form controls]
+aliases: [button, push button, plain button, bordered button, destructive button, capsule button, link button, action button, cta, raised button, pill button, key button]
 ---
 
 ```jsx
@@ -29,3 +30,34 @@ composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form c
   <Button size="sm">New issue</Button>
 </Row>
 ```
+
+```jsx
+// Raised variant — tactile bevel + drop shadow + ambient hover glow.
+// Composed from the Presence elevation tokens (--elevation-3 rest,
+// --elevation-hot hover, --elevation-pressed active). Tone is driven
+// by --btn-glow, which defaults to --selected-glow (blue). Override
+// per-button for "traffic light" semantics:
+<Row gap="sm">
+  <Button variant="raised" style={{ "--btn-glow": "var(--warning)" }}>
+    Iterate
+  </Button>
+  <Button variant="raised" style={{ "--btn-glow": "var(--success)" }}>
+    Ship it
+  </Button>
+</Row>
+```
+
+```jsx
+// data-state="on" / aria-pressed="true" gives the held-down "key
+// pressed" look — picks up the --selected blue stroke + heat-inner
+// glow. Works as a Toggle/ToggleGroupItem child via asChild.
+<Button variant="raised" data-state="on">Locked</Button>
+```
+
+```jsx
+// Combine with Aura for AI-attention states. The three Aura styles
+// (ring/gradient/shimmer) stack independently of the variant.
+<Button variant="raised" className="gds-aura-ring">
+  Studio is reviewing this
+</Button>
+```

package/components/ui/calendar.md

@@ -15,7 +15,7 @@ props:
   - className?: string
 when_to_use: An inline date grid — date-of-birth pickers in profile forms, scheduling screens with a month view, range selection in reporting filters. For a compact trigger-and-popover input, use DatePicker / DateRangePicker (which wrap Calendar internally). For one-off relative dates ("yesterday", "last week") use a Select instead.
 composes_with: [Popover (DatePicker composes them), Card (inline scheduling card), Dialog (full-screen mobile date pick)]
-aliases: [calendar, date grid, month view, scheduler grid]
+aliases: [calendar, date grid, month view, scheduler grid, calendar view, multidate picker, react native calendars]
 ---
 
 ```jsx

package/components/ui/callout.md

@@ -0,0 +1,45 @@
+---
+name: Callout
+import: "@gradeui/ui"
+subcomponents: [CalloutTitle, CalloutDescription]
+variants: [default, destructive, success, warning, info]
+props:
+  - variant? (default | destructive | success | warning | info) — semantic colouring; `default` is neutral
+  - All native div HTML attrs
+when_to_use: Inline, ambient, non-blocking status/feedback that sits inside the layout flow. Form-level validation summaries, settings-page notices, page-level banners. NOT a toast (use Sonner for transient). NOT a modal (use Dialog when the user must respond). Put an icon as first child — it's auto-positioned; CalloutTitle + CalloutDescription follow.
+composes_with: [lucide-react icons as first child, Button (inside CalloutDescription), Card (as a section callout)]
+aliases: [callout, banner, notice, inline alert, in-app notification, status banner, info banner, info callout, warning callout, success callout]
+---
+
+Renamed from `Alert` (May 2026). The old name implied modal/interruptive behaviour the component doesn't have — Apple HIG `Alert` is a modal, and `role="alert"` is assertive ARIA. Callout is honest about what it is: ambient, inline, non-blocking. For genuinely interruptive needs, reach for `<Dialog>`.
+
+Variant tokens come from theme (`--destructive-soft`, `--success-deep`, etc.) so they restyle with the active Grade theme.
+
+```jsx
+<Callout variant="warning">
+  <AlertTriangle />
+  <CalloutTitle>Low disk space</CalloutTitle>
+  <CalloutDescription>2GB remaining on /dev/sda1.</CalloutDescription>
+</Callout>
+```
+
+```jsx
+// Ambient success notice — uses role="status" (polite) so screen
+// readers don't interrupt the user. Warning/destructive get
+// role="alert" (assertive) instead.
+<Callout variant="success">
+  <CheckCircle2 />
+  <CalloutTitle>Profile updated</CalloutTitle>
+  <CalloutDescription>Your changes are live.</CalloutDescription>
+</Callout>
+```
+
+### Anti-patterns
+
+DO NOT use `<Callout>` for interruptive or blocking messages. If the user must respond before continuing, use `<Dialog>` — the modal primitive that Apple HIG calls "Alert" and React Native exposes as `Alert.alert()`. Callout is ambient by design.
+
+DO NOT pass `role="alert"` when the variant is `info` / `success` / `default` — the component already routes those to `role="status"` (polite), and overriding makes screen readers interrupt for non-urgent content.
+
+DO NOT reach for `variant="warning"` to convey "this is just notable / FYI" — that's what `variant="info"` is for. Warning is for things that could go wrong if ignored; info is for ambient context.
+
+The previous `variant="highlight"` (yellow) was dropped in the Alert → Callout rename — it overlapped `warning` semantically without offering a distinct intent. Use `warning` for amber attention and `info` for neutral attention.

package/components/ui/card.md

@@ -4,9 +4,10 @@ import: "@gradeui/ui"
 subcomponents: [CardHeader, CardTitle, CardDescription, CardContent, CardFooter]
 props:
   - Each subcomponent accepts native div HTML attrs (className, etc.)
-  - No variants — Card is a flexible container surface
+  - No variants — Card is a flexible container surface; shape via data-card-style and depth via shadow-elevation-* utilities
 when_to_use: Grouped content with a distinct surface — settings panels, dashboard tiles, list-of-cards layouts. Pair CardHeader (title + description) with CardContent and optional CardFooter (actions).
 composes_with: [Button (in CardFooter), Badge, Separator, Avatar, any form controls]
+aliases: [card, group box, groupbox, panel, tile, surface]
 ---
 
 Canonical structure — do NOT skip CardHeader if the card has a title:
@@ -23,3 +24,17 @@ Canonical structure — do NOT skip CardHeader if the card has a title:
   </CardFooter>
 </Card>
 ```
+
+Card is the most common host for Presence affordances. Three independent axes:
+
+```jsx
+// Elevation — pick a depth level (1=minimal, 3=raised, 4=popover, 5=dialog).
+<Card className="shadow-elevation-4">…</Card>
+
+// Surface — opt into glass / translucent backgrounds.
+<Card className="gds-surface-glass shadow-elevation-4">…</Card>
+
+// Aura — radiate AI-attention state. Combinable.
+<Card className="gds-aura-ring">Studio is reviewing this</Card>
+<Card className="gds-aura-ring gds-aura-shimmer">Generating…</Card>
+```