@gradeui/ui 0.9.0 → 1.0.0

package/components/ui/accordion.md

@@ -0,0 +1,30 @@
+---
+name: Accordion
+import: "@gradeui/ui"
+subcomponents: [AccordionItem, AccordionTrigger, AccordionContent]
+props:
+  - Accordion: type: "single" | "multiple" — single keeps one open at a time, multiple lets several be open at once
+  - Accordion: collapsible?: boolean — only valid with type="single"; allows the open item to be toggled shut
+  - Accordion: defaultValue?: string | string[] — initial open item(s)
+  - Accordion: value?: string | string[] — controlled
+  - Accordion: onValueChange?: (value: string | string[]) => void
+  - AccordionItem: value: string — id used by the open-state machinery
+  - AccordionTrigger: children: React.ReactNode — the row label users click to expand
+  - 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, disclosure group, outline group, expandable list, sectionlist]
+---
+
+```jsx
+<Accordion type="single" collapsible defaultValue="one">
+  <AccordionItem value="one">
+    <AccordionTrigger>What's included?</AccordionTrigger>
+    <AccordionContent>Everything in the design system, plus Studio.</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="two">
+    <AccordionTrigger>Can I bring my own theme?</AccordionTrigger>
+    <AccordionContent>Yes — three hues in, full theme out.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

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

@@ -0,0 +1,81 @@
+---
+name: AIChat
+import: "@gradeui/ui"
+props:
+  - 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 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
+// Canned use — no slots, no metadata. Matches the original API.
+<AIChat
+  messages={messages}
+  isLoading={loading}
+  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/app-shell.md

@@ -0,0 +1,178 @@
+---
+name: AppShell
+import: "@gradeui/ui"
+role: layout
+subcomponents: [AppShellHeader, AppShellNav, AppShellAside, AppShellMain, AppShellFooter]
+props:
+  - 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 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: |
+  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 (default) the nav gets h-screen + self-scroll,
+  so long nav lists don't push main down.
+---
+
+```jsx
+// nav="side" — classic dashboard: left nav + main.
+<AppShell nav="side">
+  <AppShellNav placement="side">
+    <Sidebar>{/* sidebar items */}</Sidebar>
+  </AppShellNav>
+  <AppShellMain>
+    <Stack gap="lg" className="p-6">
+      {/* page content */}
+    </Stack>
+  </AppShellMain>
+</AppShell>
+```
+
+```jsx
+// 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">
+    <Toolbar leading={<Logo/>} trailing={<Avatar/>} />
+  </AppShellNav>
+  <AppShellMain maxWidth="container">
+    <Stack gap="lg" className="py-8">
+      {/* page content */}
+    </Stack>
+  </AppShellMain>
+</AppShell>
+```
+
+```jsx
+// 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

@@ -0,0 +1,29 @@
+---
+name: Avatar
+import: "@gradeui/ui"
+subcomponents: [AvatarImage, AvatarFallback]
+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 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
+<Avatar>
+  <AvatarImage src="/ada.jpg" alt="Ada Lovelace" />
+  <AvatarFallback>AL</AvatarFallback>
+</Avatar>
+```

package/components/ui/badge.md

@@ -0,0 +1,18 @@
+---
+name: Badge
+import: "@gradeui/ui"
+variants: [default, secondary, destructive, outline, highlight, success, warning, info, success-soft, warning-soft, destructive-soft, info-soft, highlight-soft, success-outline, warning-outline, destructive-outline, info-outline]
+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 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, badge, tag view, status pill, token, count badge]
+---
+
+```jsx
+<Badge>New</Badge>
+<Badge variant="success-soft" rounded="full">Active</Badge>
+<Badge variant="destructive-outline">Blocked</Badge>
+```

package/components/ui/breadcrumb.md

@@ -0,0 +1,101 @@
+---
+name: Breadcrumb
+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? — 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, path bar, navigation trail, finder path]
+---
+
+```jsx
+// Two-level path — Dashboard → current page.
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Dashboard</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Settings</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</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>
+  <BreadcrumbList>
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/">Home</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbEllipsis />
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbLink href="/projects/acme">Acme</BreadcrumbLink>
+    </BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem>
+      <BreadcrumbPage>Billing</BreadcrumbPage>
+    </BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```

package/components/ui/button.md

@@ -0,0 +1,63 @@
+---
+name: Button
+import: "@gradeui/ui"
+variants: [default, destructive, outline, secondary, ghost, link, raised]
+sizes: [sm, md, lg, icon]
+props:
+  - 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, 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
+<Button>Save</Button>
+<Button variant="outline" size="sm">Cancel</Button>
+<Button size="icon" variant="ghost"><Mail /></Button>
+```
+
+```jsx
+// Lined up next to a TabsList — same size = same height.
+<Row gap="sm" align="center">
+  <TabsList size="sm">
+    <TabsTrigger value="all">All</TabsTrigger>
+    <TabsTrigger value="open">Open</TabsTrigger>
+  </TabsList>
+  <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

@@ -0,0 +1,39 @@
+---
+name: Calendar
+import: "@gradeui/ui"
+subcomponents: [CalendarDayButton]
+props:
+  - mode?: "single" | "multiple" | "range" — picks one date, several dates, or a [from, to] range
+  - selected?: Date | Date[] | { from: Date; to?: Date } — controlled selection; shape matches `mode`
+  - onSelect?: (value) => void — fires with the new selection
+  - month?: Date — controlled displayed month
+  - defaultMonth?: Date — uncontrolled initial month
+  - onMonthChange?: (date: Date) => void
+  - numberOfMonths?: number (default 1) — render multiple months side by side, useful for range pickers
+  - disabled?: Date | Date[] | { before?: Date; after?: Date } | (date: Date) => boolean
+  - captionLayout?: "label" | "dropdown" | "dropdown-months" | "dropdown-years"
+  - 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, calendar view, multidate picker, react native calendars]
+---
+
+```jsx
+// Single-date inline calendar.
+<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  captionLayout="dropdown"
+/>
+```
+
+```jsx
+// Two-month range picker — typical reporting filter shape.
+<Calendar
+  mode="range"
+  numberOfMonths={2}
+  selected={range}
+  onSelect={setRange}
+/>
+```

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.