@gradeui/ui 1.0.0 → 1.1.0

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/card.md

@@ -3,14 +3,26 @@ name: Card
 import: "@gradeui/ui"
 subcomponents: [CardHeader, CardTitle, CardDescription, CardContent, CardFooter]
 props:
+  - surface? (solid | translucent | glass | glass-strong) — what the card surface is *made of*. `solid` is the default opaque `bg-card`. `translucent` is ~82% opacity for menu sheets. `glass` is ~58% opacity + 14px blur + edge highlight for floating panels. `glass-strong` is ~42% + 24px blur for full-page overlays. Composes with `shadow-elevation-*` (depth) and `gds-aura-*` (state signal).
   - Each subcomponent accepts native div HTML attrs (className, etc.)
-  - 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]
+when_to_use: Grouped content with a distinct surface — settings panels, dashboard tiles, list-of-cards layouts, marketing hero containers, AI suggestion overlays. Pair CardHeader (title + description) with CardContent and optional CardFooter (actions). Reach for `surface="glass"` whenever the card sits over a busy backdrop (gradient mesh, dot grid, generative art, image hero).
+composes_with: [Button (in CardFooter), Badge, Separator, Avatar, Code, MediaSurface, any form controls]
+aliases: [card, group box, groupbox, panel, tile, surface, glass card, frosted card, floating panel, hero card, ai suggestion card, dashboard tile, settings panel]
 ---
 
-Canonical structure — do NOT skip CardHeader if the card has a title:
+Card is the most common host for the **Presence** system (PRESENCE.md). Three independent axes layer on top of every card:
+
+- **Surface** — what it's made of (`surface` prop: solid / translucent / glass / glass-strong)
+- **Elevation** — how high it sits (`shadow-elevation-1..5` utility)
+- **Aura** — what it's radiating (`gds-aura-ring`, `gds-aura-gradient`, `gds-aura-shimmer`)
+
+The four scenarios below are the canonical recipes. Match the scenario to the screen you're building.
+
+---
+
+### Scenario 1 — Settings panel (default opaque)
+
+You want a grouped content surface on a normal page: a settings panel, a list-of-cards tile, a dashboard widget. The page background is calm; the card just needs to sit cleanly on it.
 
 ```jsx
 <Card>
@@ -18,23 +30,166 @@ Canonical structure — do NOT skip CardHeader if the card has a title:
     <CardTitle>Billing</CardTitle>
     <CardDescription>Manage your subscription.</CardDescription>
   </CardHeader>
-  <CardContent>…</CardContent>
+  <CardContent>
+    <Stack gap="md">
+      <Row justify="between">
+        <span className="text-sm">Plan</span>
+        <Badge>Pro</Badge>
+      </Row>
+      <Row justify="between">
+        <span className="text-sm">Renews</span>
+        <span className="text-sm text-muted-foreground">12 Jun 2026</span>
+      </Row>
+    </Stack>
+  </CardContent>
   <CardFooter>
-    <Button>Save</Button>
+    <Button variant="outline">Cancel plan</Button>
+    <Button>Update payment</Button>
   </CardFooter>
 </Card>
 ```
 
-Card is the most common host for Presence affordances. Three independent axes:
+No `surface` prop — the default `solid` is the right answer for almost every in-page card. Reach for glass only when there's something behind worth blurring.
+
+---
+
+### Scenario 2 — Glass card over a busy backdrop (marketing hero)
+
+You're building a marketing hero. There's a gradient mesh, a dot grid, generative art, or a hero image behind the card. The card should read as **floating chrome** — translucent enough to let the backdrop breathe through, but with a defined edge so the content stays legible.
 
 ```jsx
-// Elevation — pick a depth level (1=minimal, 3=raised, 4=popover, 5=dialog).
-<Card className="shadow-elevation-4">…</Card>
+<SectionBlock background="gradient" padding="xl">
+  <Grid cols="2" gap="md">
+    <Card surface="glass" className="shadow-elevation-4">
+      <CardHeader>
+        <CardTitle>v0 — sidebar component</CardTitle>
+        <CardDescription>~300 lines</CardDescription>
+      </CardHeader>
+      <CardContent className="p-0">
+        <Code source={v0Code} language="tsx" bare className="p-4 text-xs max-h-72" />
+      </CardContent>
+    </Card>
+
+    <Card surface="glass" className="shadow-elevation-4 gds-aura-ring">
+      <CardHeader>
+        <CardTitle>GradeUI — sidebar component</CardTitle>
+        <CardDescription>6 lines</CardDescription>
+      </CardHeader>
+      <CardContent className="p-0">
+        <Code source={gradeCode} language="tsx" bare className="p-4 text-xs max-h-72" />
+      </CardContent>
+    </Card>
+  </Grid>
+</SectionBlock>
+```
+
+`surface="glass"` does five things at once: 58% opacity `bg-card`, 14px backdrop blur, an inner edge highlight (the "wet" rim that gives glass its boundary), a faint border, and it drops the base `bg-card` so the alpha actually shows. Layering `shadow-elevation-4` adds the floating-popover drop shadow; `gds-aura-ring` makes the second card pulse with a blue halo to signal "this is the recommended path".
+
+---
+
+### Scenario 3 — Translucent menu sheet (floating chrome with structure)
 
-// Surface — opt into glass / translucent backgrounds.
-<Card className="gds-surface-glass shadow-elevation-4">…</Card>
+You want a floating panel — a command palette, a notification drawer, an AI suggestion overlay — that's visibly distinct from the canvas but doesn't need full glass blur. Translucent is for "I want presence without drama".
 
-// 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>
+```jsx
+<Card surface="translucent" className="shadow-elevation-5 w-80">
+  <CardHeader>
+    <CardTitle>Suggested action</CardTitle>
+    <CardDescription>Studio noticed a layout opportunity.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Three buttons in your toolbar would line up edge-to-edge with the
+      tabs below if their size matched. Apply <code>size="sm"</code>?
+    </p>
+  </CardContent>
+  <CardFooter>
+    <Button variant="ghost" size="sm">Dismiss</Button>
+    <Button size="sm">Apply</Button>
+  </CardFooter>
+</Card>
 ```
+
+82% opacity is enough to feel layered but not enough to need backdrop blur — works equally well over a busy or a calm background. `shadow-elevation-5` (dialog tier) plus `translucent` is the "floating but not glass" signature.
+
+---
+
+### Scenario 4 — AI is generating (aura + surface composition)
+
+You want to signal that Studio (or any AI agent) is actively working on this card. Aura is the right axis for state signals. It composes with any surface.
+
+```jsx
+<Card
+  surface="glass"
+  className="shadow-elevation-4 gds-aura-ring gds-aura-shimmer"
+  style={{ "--aura-color": "var(--selected-glow)" }}
+>
+  <CardHeader>
+    <CardTitle>Generating layout</CardTitle>
+    <CardDescription>About 4 seconds remaining.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Stack gap="xs">
+      <Skeleton className="h-4 w-3/4" />
+      <Skeleton className="h-4 w-1/2" />
+      <Skeleton className="h-4 w-2/3" />
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+Ring (pulsing halo) + shimmer (diagonal sweep) together = "actively generating". For "Studio is reviewing this", use ring alone. For "ready to ship", swap tone to `--success`. The skeletons inside are the content's own loading state — orthogonal to the card-level aura.
+
+---
+
+### Scenario 5 — Glass-strong for a full-page overlay backdrop
+
+`surface="glass-strong"` is tuned for a different job than the other three: it's the **backdrop** behind a modal sheet, not the modal itself. Heavy blur (24px), 42% opacity. Use it to de-emphasise the page underneath while keeping it readable.
+
+```jsx
+<Card surface="glass-strong" className="fixed inset-4 z-50">
+  <CardContent className="grid place-items-center h-full">
+    <Stack gap="md" align="center">
+      <Spinner />
+      <span className="text-lg">Saving your theme…</span>
+    </Stack>
+  </CardContent>
+</Card>
+```
+
+Almost always wrong for in-flow content — at 42% opacity the card reads as washed out. If you find yourself reaching for glass-strong for a regular card, you probably want `glass`.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand with Tailwind utilities.** The wrong path:
+
+```jsx
+{/* ❌ Tailwind soup — misses edge highlight, locks blur to a fixed step,
+    bypasses theme tuning, no Studio inspector knob. */}
+<Card className="overflow-hidden border-border bg-card/40 backdrop-blur-md">
+```
+
+The right path:
+
+```jsx
+{/* ✅ Theme-aware bg, tuned blur, edge highlight, knob-discoverable. */}
+<Card surface="glass">
+```
+
+This is the single most common mistake. The model reaches for `bg-card/40 backdrop-blur-md` because every other DS leaves glass at the utility layer. Ours doesn't.
+
+**DO NOT layer a solid `bg-card` className over `surface="glass"`.** The opaque fill defeats the blur. Card already drops `bg-card` when `surface` is set to anything other than `solid` — don't undo that by tacking `bg-card` back on via className. If you want a tinted glass, override `--card` on the element:
+
+```jsx
+<Card surface="glass" style={{ "--card": "0.99 0.04 250" }}>
+  ...
+</Card>
+```
+
+**DO NOT use `surface="glass"` over a solid background.** Glass needs something behind it to blur. Over plain `bg-background` it reads as a slightly washed-out card and you pay for backdrop-filter for no gain. If the page is calm, use `solid`.
+
+**DO NOT use `surface="glass-strong"` for in-flow content.** It's a full-page overlay material. At 42% opacity, regular cards read as washed out. Reach for `glass`.
+
+**DO NOT skip CardHeader if the card has a title.** The header is the semantic anchor for the title + description pair. Inline `<h3>` inside CardContent breaks the visual rhythm and harms screen-reader navigation.

package/components/ui/code.md

@@ -0,0 +1,132 @@
+---
+name: Code
+import: "@gradeui/ui"
+variants: []
+props:
+  - source: string — the code to render
+  - language? (tsx | jsx | ts | js | html | css | json | bash | md | py | go | rust) — Prism language id; defaults to `tsx`
+  - highlight? — 1-indexed line number, array of numbers, or array of `[start, end]` ranges to emphasise
+  - diff? — `{ added?: number[]; removed?: number[] }` — 1-indexed lines for diff hero / changelog mode
+  - reveal? (none | lines | typewriter | diff) — entrance animation; defaults to `none`
+  - trigger? (mount | inView | manual) — what kicks the reveal off; defaults to `mount`
+  - play?: boolean — for `trigger="manual"`, set true to play
+  - speed? (slow | normal | fast) — animation feel preset. `normal` (default) maps to the canonical 50ms/22ms staggers + 180ms pre-delay. Pick a feel; don't tune individual numbers unless you have to.
+  - delay?: number — explicit delay before reveal starts (ms) — overrides the `speed` preset
+  - stagger?: number — explicit per-line stagger for `lines`/`diff`, per-token for `typewriter` (ms) — overrides the `speed` preset
+  - prompt?: string — string prepended to each line. Use for terminal emulation: `prompt="$ "` for bash, `prompt="> "` for PowerShell, `prompt=">>> "` for Python REPL. Prompt characters render in muted token colour, don't pick up the typewriter stagger, and are hidden from screen readers.
+  - showLineNumbers?: boolean
+  - filename?: string — optional label rendered in the header chrome
+  - wrap?: boolean — wrap long lines instead of horizontal scroll
+  - bare?: boolean — drop chrome (border, header, padding) — for inline use
+  - height? (auto | number | string) — container sizing. `auto` (default) grows with content. Number = pixels (`300` → `300px`). String passes through as CSS (`"20rem"`, `"50vh"`).
+  - maxLines?: number — cap the visible line count at exactly N line-heights. Wins over `height`. Use for terminal windows, code-tour cards, and surfaces that need a stable vertical rhythm regardless of snippet length.
+when_to_use: Read-only code surface for marketing heroes, docs, changelog entries, AI-output displays. Use `diff` for the "diff hero" pattern (before/after side-by-side or stacked). Use `reveal="lines"` with `trigger="inView"` for scroll-driven marketing pages. Use `reveal="typewriter"` for AI-output / chat-style displays. Use `bare` for inline code inside prose. NOT a code editor — for editable code, reach for an external editor primitive (CodeMirror / Monaco).
+composes_with: [SectionBlock, Card, Tabs (for multi-file examples), Carousel (slide-to-slide code progression)]
+aliases: [code block, code, code snippet, code surface, syntax highlighted code, diff hero, diff view, diff block, changelog code, before after code, scroll-triggered code, typewriter code]
+---
+
+Token palette is driven by `--gds-code-*` CSS variables in `styles/globals.css`. The component itself is presentation-agnostic: prism renders tokens, the variables colour them, motion handles the reveal. Override per-instance via inline `style` to retune one block without touching the theme.
+
+The engine is `prism-react-renderer` (already used by Studio's CodeView). Sync, ~6kb, render-prop API — no async hydration flash, no bundle bloat from lang files.
+
+```jsx
+// Plain block.
+<Code language="tsx" source={`function greet(name) {
+  return \`Hello, \${name}\`;
+}`} />
+```
+
+```jsx
+// Line highlight — emphasis lines accept a number, an array, or
+// [start, end] ranges. Composes cleanly with diff (diff colours win).
+<Code
+  language="tsx"
+  highlight={[2, [4, 6]]}
+  source={`<Button>Save</Button>
+<Button variant="raised">Ship it</Button>
+<Button variant="raised" style={{ "--btn-glow": "var(--warning)" }}>
+  Iterate
+</Button>`}
+/>
+```
+
+```jsx
+// Diff hero — the marketing "before / after" pattern. Added lines get
+// the success-tinted bg + `+` gutter; removed lines get destructive-
+// tinted bg + `-` gutter. `showLineNumbers` is opt-in.
+<Code
+  language="tsx"
+  filename="button.tsx"
+  diff={{ removed: [1], added: [2, 3, 4] }}
+  source={`<button className="px-4 py-2 rounded-md bg-blue-600 text-white shadow-md">
+<Button variant="raised">
+  Ship it
+</Button>`}
+/>
+```
+
+```jsx
+// Scroll-triggered reveal — marketing hero. The block waits until the
+// reader scrolls it into view, then staggers each line in. `once: true`
+// is baked in: the reveal doesn't replay when the user scrolls away
+// and back.
+<Code
+  language="tsx"
+  reveal="lines"
+  trigger="inView"
+  stagger={50}
+  source={`<AppShell nav="three-pane">
+  <AppShellHeader>...</AppShellHeader>
+  <AppShellNav>...</AppShellNav>
+  <AppShellAside>...</AppShellAside>
+  <AppShellMain>...</AppShellMain>
+</AppShell>`}
+/>
+```
+
+```jsx
+// Typewriter — token-by-token reveal. Good for AI-output displays
+// and "watch it generate" demos. Whitespace tokens are free (no
+// delay) so leading indent doesn't feel like dead time. `speed`
+// keeps it ergonomic — pick "slow" / "normal" / "fast" instead of
+// tuning stagger by hand.
+<Code
+  language="tsx"
+  reveal="typewriter"
+  trigger="inView"
+  speed="normal"
+  source={`const theme = await ai.generate({
+  brand: "Acme",
+  mood: "calm",
+});`}
+/>
+```
+
+```jsx
+// Terminal emulation — `prompt` prepends a static prompt string to
+// each line. Combine with `reveal="typewriter"` for a scripted CLI
+// session feel. Prompt chars are chrome (muted, aria-hidden, no
+// animation), so the typewriter only stages the actual command.
+<Code
+  language="bash"
+  prompt="$ "
+  reveal="typewriter"
+  trigger="inView"
+  speed="slow"
+  source={`pnpm add @gradeui/ui
+pnpm gradeui init
+pnpm dev`}
+/>
+```
+
+### Anti-patterns
+
+DO NOT use `<Code>` as a code editor. It's read-only by design — the prism renderer doesn't take input. For editable code, compose your own surface around CodeMirror or Monaco.
+
+DO NOT reach for a separate library to render code elsewhere in the app — Studio's CodeView, docs blocks, and marketing heroes should all share this primitive so the token palette stays single-source.
+
+DO NOT pass `highlight` AND `diff` for the same line — diff wins, and the highlight emphasis is silently dropped. Use one signal per line.
+
+DO NOT use `reveal="typewriter"` for long blocks (50+ lines). It works but feels laboured; use `reveal="lines"` instead.
+
+DO NOT override the prism `theme` prop — the component intentionally hides it. Restyle via the `--gds-code-*` CSS variables so every Code block in the app shifts together with the active theme.

package/components/ui/dialog.md

@@ -5,36 +5,129 @@ subcomponents: [DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogD
 props:
   - Dialog: open?, onOpenChange? — Radix controlled/uncontrolled pattern
   - DialogTrigger: asChild? (wrap a Button)
+  - DialogContent: surface? (solid | translucent | glass | glass-strong) — what the modal panel is *made of*. Defaults to `solid` (opaque `bg-background`). `glass` lets the page show through softly — pairs with rich backdrops or AI-suggestion modals.
   - DialogContent: accepts native div HTML attrs
   - DialogFooter: used for action rows
-when_to_use: Modal interruptions — confirmations, focused forms, detail views. Dialog is the right primitive for Apple HIG / React Native "Alert" (modal) semantics. For non-blocking inline messaging use Callout; for transient notifications use Toaster (Sonner). Always include DialogTitle (a11y requirement).
-composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent]
-aliases: [modal, popup, overlay, alert, system alert, alert dialog, modal dialog, confirm dialog, react native modal, rn alert]
+when_to_use: Modal interruptions — confirmations, focused forms, detail views, AI suggestion sheets. Dialog is the right primitive for Apple HIG / React Native "Alert" (modal) semantics. For non-blocking inline messaging use Callout; for transient notifications use Toaster (Sonner). Always include DialogTitle (a11y requirement).
+composes_with: [Button (as DialogTrigger asChild, and inside DialogFooter), Input/Textarea/Select inside DialogContent, Code (for changelog / diff modals), MediaSurface (for image / preview modals)]
+aliases: [modal, popup, overlay, alert, system alert, alert dialog, modal dialog, confirm dialog, react native modal, rn alert, glass modal, frosted modal, ai suggestion modal]
 ---
 
+DialogContent sits at elevation-5 (the dialog tier). The Presence axes still apply: `surface` picks the material, `gds-aura-*` adds radiating state, the overlay scrim handles dimming the page.
+
+---
+
+### Scenario 1 — Destructive confirmation (default opaque)
+
+You're confirming a destructive action: delete, discard, revoke. Keep the dialog opaque — the user should focus on the decision, not the page behind it. The raised Button + tonal `--btn-glow` keeps the destructive action visually heavy without going red-everywhere.
+
 ```jsx
 <Dialog>
-  <DialogTrigger asChild><Button>Delete</Button></DialogTrigger>
+  <DialogTrigger asChild><Button variant="outline">Delete project</Button></DialogTrigger>
   <DialogContent>
     <DialogHeader>
       <DialogTitle>Delete project?</DialogTitle>
-      <DialogDescription>This cannot be undone.</DialogDescription>
+      <DialogDescription>
+        This will remove the project, its screens, and all comments. This cannot be undone.
+      </DialogDescription>
     </DialogHeader>
     <DialogFooter>
       <Button variant="outline">Cancel</Button>
-      <Button variant="destructive">Delete</Button>
+      <Button variant="raised" style={{ "--btn-glow": "var(--destructive)" }}>
+        Delete forever
+      </Button>
     </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
 
-DialogContent ships at elevation-5. Reach for the raised Button variant inside DialogFooter when the action carries weight ("Delete", "Publish", "Ship"):
+No `surface` prop — `solid` is the right answer for high-stakes confirmations. The opacity reinforces "stop and decide".
+
+---
+
+### Scenario 2 — Glass modal over a rich canvas (creative-tool aesthetic)
+
+You're building a creative tool — Studio, a presentation builder, a photo editor. The canvas behind the dialog is visually rich (a layout in progress, an image, generative art). A solid dialog cuts a hole through the work. Glass keeps the work visible while focusing attention.
 
 ```jsx
-<DialogFooter>
-  <Button variant="outline">Cancel</Button>
-  <Button variant="raised" style={{ "--btn-glow": "var(--destructive)" }}>
-    Delete forever
-  </Button>
-</DialogFooter>
+<Dialog>
+  <DialogTrigger asChild><Button>Add a comment</Button></DialogTrigger>
+  <DialogContent surface="glass" className="shadow-elevation-5">
+    <DialogHeader>
+      <DialogTitle>Comment on Hero section</DialogTitle>
+      <DialogDescription>
+        Visible to your team and to Studio when it next regenerates this screen.
+      </DialogDescription>
+    </DialogHeader>
+    <Textarea placeholder="What should change about this section?" />
+    <DialogFooter>
+      <Button variant="ghost">Cancel</Button>
+      <Button>Post comment</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
 ```
+
+`surface="glass"` is the canvas-tool signature. The user keeps spatial awareness of what they were just looking at; the dialog feels like a layer above the work, not a separate page.
+
+---
+
+### Scenario 3 — AI suggestion sheet (translucent + aura)
+
+Studio is offering a suggestion. It shouldn't feel as heavy as a destructive confirmation — it's a recommendation, not a demand. Translucent (no blur) is lighter than glass; the aura ring announces "this is from an AI agent".
+
+```jsx
+<Dialog open={hasSuggestion}>
+  <DialogContent
+    surface="translucent"
+    className="shadow-elevation-5 gds-aura-ring"
+    style={{ "--aura-color": "var(--selected-glow)" }}
+  >
+    <DialogHeader>
+      <DialogTitle>Three buttons could align</DialogTitle>
+      <DialogDescription>
+        Toolbar buttons match TabsList height when size="sm". Apply across all three?
+      </DialogDescription>
+    </DialogHeader>
+
+    <Card surface="glass" className="shadow-elevation-2">
+      <CardContent>
+        <Code source={suggestedDiff} language="tsx" diff={{ added: [2, 3, 4] }} bare />
+      </CardContent>
+    </Card>
+
+    <DialogFooter>
+      <Button variant="ghost">Dismiss</Button>
+      <Button>Apply suggestion</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+Three Presence axes layered: `surface="translucent"` (material), `shadow-elevation-5` (depth), `gds-aura-ring` (state signal). The inner Card uses `surface="glass"` for a different reason — to read as a nested floating preview rather than a flat content block.
+
+---
+
+### Anti-patterns
+
+**DO NOT use `surface="glass"` for destructive confirmations.** Glass implies "the page is still alive behind this" — users will be less decisive. Opaque is the right material for high-stakes choices.
+
+**DO NOT roll glass by hand on DialogContent.**
+
+```jsx
+{/* ❌ Misses edge highlight, no theme tuning, no inspector knob. */}
+<DialogContent className="bg-background/50 backdrop-blur-md">
+
+{/* ✅ */}
+<DialogContent surface="glass">
+```
+
+**DO NOT skip DialogTitle.** Screen readers announce the title on open — without it the dialog reads as "[unlabeled dialog]". If the design has no visible title, wrap a visually-hidden title:
+
+```jsx
+<DialogHeader>
+  <DialogTitle className="sr-only">Image preview</DialogTitle>
+</DialogHeader>
+```
+
+**DO NOT use Dialog for ambient messaging.** Toast for transient ("Saved"), Callout for inline ("3 unread comments"), Dialog only when the user MUST respond before continuing.