@gradeui/ui 0.10.0 → 1.1.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/banner.md

@@ -0,0 +1,146 @@
+---
+name: Banner
+import: "@gradeui/ui"
+variants: [default, info, success, warning, destructive, announcement]
+props:
+  - variant? (default | info | success | warning | destructive | announcement) — intent + tonal direction. `default` is a calm muted strip; `announcement` is a low-alpha brand tint for "new feature" messaging; status variants pick up the soft+deep token pairs.
+  - surface? (solid | translucent | glass | glass-strong) — material applied over the variant tint. `glass` for banners that sit over imagery / generative backdrops.
+  - align? (start | center | between) — justify behaviour of the inner flex row. Defaults to `between` so the action / dismiss button right-align.
+  - sticky?: boolean — stick to the top of the scroll container.
+  - dismissible?: boolean — render the trailing X close button. Pair with `onDismiss` to react.
+  - onDismiss?: () => void
+  - icon?: ReactNode — leading icon slot. NOT inferred from variant; pass what fits the message.
+  - action?: ReactNode — trailing slot before dismiss. Usually a `<Button size="sm">` or `<a>`.
+  - role?: string — overrides the automatic role mapping (warning/destructive → alert, others → status).
+when_to_use: A full-width horizontal strip surfacing system-level state, announcements, or first-run guidance — "you're previewing a draft", "investigating incident", "new feature available", "send your design to Figma". Distinct from Callout (inline boxed message in the layout flow), Toast (transient floating notification), Dialog (modal interrupt). Banner is what lives at the TOP of an AppShellHeader, page, or panel.
+composes_with: [AppShellHeader (most common host — banner sits ABOVE the header content), Button (in the action slot), Link (inside the content), Lucide icons (in the icon slot)]
+aliases: [banner, notification banner, system banner, header banner, announcement bar, top bar, status bar, promo banner, incident banner, draft banner, first run banner, glass banner, sticky banner]
+---
+
+Banner is the "horizontal strip across the top of something" primitive. The shape difference from Callout matters: Callout is an inline boxed message inside layout flow; Banner is full-bleed and meant to anchor at the top of a page, panel, or AppShellHeader.
+
+---
+
+### Scenario 1 — First-run guidance (default)
+
+A one-line hint surfaced the first time a user lands on a tab or screen. Calm muted tint, dismissible, lives above the main content.
+
+```jsx
+<Banner
+  variant="default"
+  dismissible
+  onDismiss={dismiss}
+  action={
+    <a href={pluginUrl} target="_blank" rel="noreferrer" className="text-sm font-medium underline underline-offset-4">
+      Get the Grade plugin →
+    </a>
+  }
+>
+  Send your design to Figma as live components.
+</Banner>
+```
+
+This is the canonical replacement for the inline-style `FigmaIntroBanner` that motivated this primitive — same content, but the tint inherits properly from the active theme and the dismiss button gets the same focus-ring treatment as every other interactive element.
+
+---
+
+### Scenario 2 — Incident / warning banner at AppShellHeader top
+
+You need to tell users something is going wrong without interrupting them. Banner with `variant="warning"` (or `destructive` if it's worse) sits at the very top of the AppShell.
+
+```jsx
+<AppShell>
+  <Banner
+    variant="warning"
+    sticky
+    icon={<AlertTriangle className="h-4 w-4" />}
+    action={
+      <Button asChild variant="outline" size="sm">
+        <a href="/status">Status page</a>
+      </Button>
+    }
+  >
+    We're investigating an incident affecting search results. Comments and edits are unaffected.
+  </Banner>
+  <AppShellHeader>...</AppShellHeader>
+  <AppShellMain>...</AppShellMain>
+</AppShell>
+```
+
+`sticky` so it doesn't scroll away (incidents stay visible). `variant="warning"` gets `role="alert"` automatically — screen readers interrupt to announce it.
+
+---
+
+### Scenario 3 — Announcement banner (brand tint, low-key)
+
+New feature announcement. You want to be noticed but not alarming. The `announcement` variant uses a low-alpha brand tint so the banner reads as "we have news" without competing with the page.
+
+```jsx
+<Banner
+  variant="announcement"
+  dismissible
+  onDismiss={dismissAnnouncement}
+  icon={<Sparkles className="h-4 w-4" />}
+  action={
+    <Button asChild size="sm">
+      <a href="/components/code">See how →</a>
+    </Button>
+  }
+>
+  <strong className="font-medium">New —</strong> Code component lands with diff hero and scroll-triggered reveals.
+</Banner>
+```
+
+---
+
+### Scenario 4 — Glass banner over a hero image
+
+The marketing site has a hero image and a top banner promoting an event. A solid banner would punch a stripe through the imagery. Glass keeps the image visible.
+
+```jsx
+<div className="relative h-screen" style={{ backgroundImage: "url(/hero/teams-shipping.jpg)", backgroundSize: "cover" }}>
+  <Banner
+    surface="glass"
+    sticky
+    align="center"
+    action={
+      <Button size="sm" variant="outline" asChild>
+        <a href="/launchweek">Watch the launch →</a>
+      </Button>
+    }
+  >
+    GradeUI launch week kicks off 14 June.
+  </Banner>
+  ...
+</div>
+```
+
+`surface="glass"` + the default `variant="default"` gives a frosted strip with `--surface-blur-glass` worth of blur. Pair with `align="center"` when the banner has no leading icon — keeps the message visually centered.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll a banner with inline styles or Tailwind soup.**
+
+```jsx
+{/* ❌ Wrong token names, no dismiss focus ring, no role mapping, no theme inheritance. */}
+<div style={{ background: "oklch(var(--gds-primary) / 0.06)", color: "var(--gds-foreground)" }}>
+  Send your design to Figma. <a>Get the Grade plugin →</a>
+</div>
+
+{/* ✅ */}
+<Banner variant="announcement" dismissible onDismiss={dismiss} action={...}>
+  Send your design to Figma.
+</Banner>
+```
+
+The inline-style original this primitive replaced was effectively invisible because it reached for `--gds-primary` / `--gds-foreground` tokens that don't exist. The fallback values kicked in and the banner washed out completely. Banner exists so this category of mistake is impossible.
+
+**DO NOT use Banner for inline form-level validation.** That's Callout's job — it's a boxed message inside the layout flow. Banner is full-bleed chrome.
+
+**DO NOT use Banner for transient confirmation ("Saved").** That's Toast (Sonner). Banner is persistent until dismissed.
+
+**DO NOT stack multiple Banners.** Two banners reading at the same time fight for attention. If you genuinely need two messages, surface the highest-priority one and queue the second for after the first is dismissed.
+
+**DO NOT pass `role="alert"` on a calm `variant="info"` Banner.** The variant→role mapping is intentional. Info/success/announcement are polite; warning/destructive interrupt. Overriding makes assistive tech behaviour inconsistent with the visual signal.

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>