@gradeui/ui 1.0.0 → 1.2.0

package/components/ui/composer.md

@@ -0,0 +1,226 @@
+---
+name: Composer
+import: "@gradeui/ui"
+props:
+  - placeholder?: string
+  - initialText?: string — plain text content to seed on mount
+  - initialJson?: string — Lexical state JSON (from a previous onSubmit round-trip)
+  - formats?: ComposerFormat[] | false — available formats (defaults to bold/italic/underline/strikethrough/code/h1/h2/blockquote/ul/ol); pass false for plain text only
+  - toolbar?: boolean | "top" — show the formatting toolbar above the editor; default false
+  - triggers?: ComposerTriggerConfig[] — mention/slash configs, eg. `[{ char: "@", items: people }, { char: "/", items: commands }]`
+  - attachments?: boolean | ComposerAttachmentConfig — enable image paste + paperclip when true/object; default off
+  - onSubmit?: (content: ComposerContent, attachments?: ComposerAttachment[]) => void
+  - isLoading?: boolean — disables editor, swaps default Send for Stop
+  - onStop?: () => void
+  - maxLength?: number
+  - autoFocus?: boolean
+  - submitOnEnter?: boolean — default true (Shift-Enter still inserts newline)
+  - leftActions?: ReactNode — override the default paperclip
+  - rightActions?: ReactNode — override the default Send/Stop
+  - hideSend?: boolean — hide the default Send without replacing it
+  - steps?: ComposerStep[] — scripted demo sequence
+  - trigger?: DemoTrigger — "mount" | "inView" | "manual"; default "mount"
+  - play?: boolean — for trigger="manual"
+  - speed?: DemoSpeed — "slow" | "normal" | "fast"; default "normal"
+  - loop?: boolean
+  - loopDelay?: number — ms between loop iterations, default 2000
+  - readOnly?: boolean — disables editing AND focusability; programmatic playback still works; use for marketing demos so the script doesn't steal focus
+  - bare?: boolean — strip the card chrome
+  - className?: string
+when_to_use: |
+  THE PRIMITIVE for any text composition surface — Slack / Discord /
+  Teams chat input, AI chat / copilot prompt box, comment thread input,
+  GitHub / Linear / Jira comment box, Reddit / Twitter reply box,
+  Notion / Linear document body, email composer, post body, anywhere
+  a user types text and submits.
+
+  CONCRETE TEST — if you find yourself writing a `<textarea>` (or
+  `<Input>` styled tall) with a row of `<Bold>` / `<Italic>` /
+  `<Paperclip>` / `<Send>` buttons below or beside it, STOP. That is
+  `<Composer>`. Use it.
+
+  Common shapes:
+    Chat input with formatting + attachments + send
+      → <Composer formats={["bold","italic","code"]} toolbar attachments />
+    AI prompt box with paperclip + send
+      → <AIChatComposer />  (preset wrapping Composer)
+    Comment / reply input
+      → <ComposerReply triggers={[{char:"@", items: people}]} />
+    Document body editor
+      → <Composer toolbar formats={[...]} bare />
+
+  Built on Lexical for rich text, mentions, slash commands. The
+  `attachments` prop wires image paste + paperclip + chip preview row
+  with object URL lifecycle handled internally — don't roll that
+  plumbing yourself. The `triggers` prop wires @mentions and /slash
+  commands with a typeahead popover. The `formats` array picks which
+  toolbar buttons render when `toolbar` is on.
+
+  Shares the lib/demo step vocabulary with <Code> so scripted
+  typing/format/mention demos animate in the same rhythm as your
+  terminal demos.
+composes_with: [AIChatComposer (preset wrapping this with paperclip + send + attachments), ComposerReply (preset for comment threads), AIChat (uses AIChatComposer internally), Card (host above for reply boxes), Avatar (in leftActions slot for "your" avatar next to the input)]
+aliases: [
+  composer, message input, message bar, rich text editor, rich text input,
+  mention input, slash input, text editor, prompt input, comment composer,
+  comment input, reply input, reply box,
+  chat input, chat box, chat input bar, chat composer, chat field,
+  slack input, slack composer, slack message box, discord input,
+  discord composer, teams chat input, message composer, post composer,
+  textarea with toolbar, formatting input, formatted text input,
+  message field, send message input, write a message, compose message
+]
+---
+
+```jsx
+// Plain text chat-style composer
+<Composer
+  placeholder="Ask anything…"
+  onSubmit={(content) => send(content.text)}
+  formats={false}
+/>
+
+// Comment composer with mentions
+<Composer
+  placeholder="Add a comment…"
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content) => postComment(content.text, content.mentions)}
+  submitOnEnter={false}
+  formats={["bold", "italic", "code"]}
+  toolbar
+/>
+
+// AI chat composer with attachments, mentions AND slash commands
+<Composer
+  placeholder="Describe a UI, or paste a screenshot…"
+  triggers={[
+    { char: "@", items: docs },
+    { char: "/", items: commands, stripTrigger: true },
+  ]}
+  attachments
+  onSubmit={(content, atts) => {
+    sendToAssistant(content.text, content.mentions, atts?.map(a => a.file));
+  }}
+  isLoading={isStreaming}
+  onStop={stop}
+/>
+
+// Marketing demo — scripted playback
+<Composer
+  placeholder="Type a message…"
+  triggers={[{ char: "@", items: [{ id: "1", value: "alice" }] }]}
+  steps={[
+    { type: "type", text: "Hey " },
+    { type: "mention", trigger: "@", value: "alice", query: "ali" },
+    { type: "type", text: ", check out " },
+    { type: "select", text: "check out" },
+    { type: "format", format: "italic" },
+    { type: "wait", ms: 800 },
+    { type: "submit" },
+  ]}
+  trigger="inView"
+  speed="normal"
+  loop
+/>
+```
+
+## Demo step vocabulary
+
+Shares `type` / `wait` / `clear` with `<Code>` (driven by the same `useScriptedDemo` hook). Adds Composer-specific verbs:
+
+- `{ type: "mention", trigger, value, query? }` — insert a mention/slash token. Pass `query` to show the typeahead in flight, then resolve to `value`.
+- `{ type: "format", format }` — apply a format to the current selection.
+- `{ type: "select", text }` — select a substring (precondition for `format`).
+- `{ type: "newline" }` — insert a paragraph break.
+- `{ type: "submit" }` — fire `onSubmit`.
+
+## Imperative handle
+
+```tsx
+const ref = useRef<ComposerHandle>(null);
+ref.current?.focus();
+ref.current?.clear();
+ref.current?.insert("…");
+ref.current?.restart();       // replay scripted steps from the start
+ref.current?.restart(3000);   // replay after a 3s delay
+ref.current?.getContent();    // { text, json, mentions }
+ref.current?.getEditor();     // underlying Lexical editor (escape hatch)
+```
+
+## Themes
+
+All colours read from CSS variables (`--gds-composer-*` palette in `globals.css`). The mention pills, toolbar buttons, attachment chips, and editor surface all rebrand with the active gradeui theme without component changes.
+
+## Anti-patterns
+
+```jsx
+// ❌ Rolling a chat / Slack / Discord input as <textarea> + manual
+//    toolbar buttons + Send button. This is the EXACT shape Composer
+//    exists to consolidate — caught in the wild on a "Slack clone"
+//    generation where the model assembled this inline.
+//    Loses: attachment intake + object URL lifecycle, mention popover,
+//    slash commands, action-row slots, the Lexical state graph for
+//    rich content round-trip, the scripted-demo step machine.
+<div className="border rounded-xl bg-card">
+  <textarea
+    placeholder="Message #general"
+    value={inputText}
+    onChange={(e) => setInputText(e.target.value)}
+    onKeyDown={(e) => { if (e.key === "Enter" && !e.shiftKey) handleSend(); }}
+    rows={3}
+    className="w-full bg-transparent p-3 resize-none focus:outline-none"
+  />
+  <Row justify="between" align="center" className="px-3 py-2 border-t">
+    <Row gap="xs">
+      <Button size="icon" variant="ghost"><Bold /></Button>
+      <Button size="icon" variant="ghost"><Italic /></Button>
+      <Button size="icon" variant="ghost"><List /></Button>
+      <Button size="icon" variant="ghost"><Smile /></Button>
+      <Button size="icon" variant="ghost"><Paperclip /></Button>
+    </Row>
+    <Button onClick={handleSend}>Send</Button>
+  </Row>
+</div>
+
+// ✅ The Grade way. Same shape, every affordance free.
+<Composer
+  placeholder="Message #general"
+  formats={["bold", "italic", "code", "ul"]}
+  toolbar
+  attachments
+  triggers={[{ char: "@", items: teamMembers }]}
+  onSubmit={(content, atts) => handleSend(content.text, atts)}
+/>
+```
+
+```jsx
+// ❌ Reaching for <Input> (single-line) for a multi-line chat / reply
+//    surface. Input is for one-line text fields. Use Composer for any
+//    surface where the user might type more than one line — chat,
+//    comments, post bodies.
+<Input
+  placeholder="Reply to thread…"
+  value={reply}
+  onChange={(e) => setReply(e.target.value)}
+/>
+<Button onClick={postReply}>Reply</Button>
+
+// ✅ ComposerReply preset has the right defaults for a reply box.
+<ComposerReply
+  placeholder="Reply to thread…"
+  triggers={[{ char: "@", items: people }]}
+  onSubmit={(content) => postReply(content.text)}
+/>
+```
+
+```jsx
+// ❌ Importing TipTap, Lexical, Slate, or any other editor framework
+//    directly into a scaffold. Composer already wraps Lexical and
+//    handles all the plumbing.
+import { useEditor, EditorContent } from "@tiptap/react";
+const editor = useEditor({ extensions: [StarterKit, ...] });
+<EditorContent editor={editor} />
+
+// ✅ Use Composer. Same capability, integrated with the design system.
+<Composer toolbar formats={["bold", "italic", "h1", "h2", "blockquote", "ul", "ol"]} />
+```

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.

package/components/ui/dropdown-menu.md

@@ -6,17 +6,26 @@ props:
   - DropdownMenu: open?, defaultOpen?, onOpenChange?, modal? (default true)
   - DropdownMenuTrigger: asChild?: boolean — usually wraps a Button
   - DropdownMenuContent: align? "start" | "center" | "end"; side? "top" | "right" | "bottom" | "left"; sideOffset? number
+  - DropdownMenuContent: surface? (solid | translucent | glass | glass-strong) — what the menu surface is *made of*. `solid` (default) is `bg-popover`. `translucent` matches Apple HIG / iOS menu sheets. `glass` for menus floating over rich canvases.
+  - DropdownMenuSubContent: surface? (solid | translucent | glass | glass-strong) — same axis applied to nested submenu surfaces
   - DropdownMenuItem: onSelect?, disabled?, asChild?, inset?
   - DropdownMenuCheckboxItem / DropdownMenuRadioItem: checked? / value, onCheckedChange? / onValueChange? (radio is on the group)
   - DropdownMenuSub / DropdownMenuSubTrigger / DropdownMenuSubContent: nested menu — sub-trigger shows children, sub-content holds the deeper items
   - DropdownMenuShortcut: children — right-aligned kbd hint
 when_to_use: A small action menu attached to a trigger — overflow "…" buttons on cards, user-avatar menus in headers, "Insert" menus in editors. For a full searchable list, use Command. For ONE primary action plus a secondary, use a Button next to a smaller ghost Button instead of a dropdown.
 composes_with: [Button (as trigger asChild), Avatar (user menu), Card (overflow on a tile), Tooltip (on the trigger)]
-aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu, menu, pull-down menu, pulldown menu, context menu, popup menu, actions menu]
+aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action menu, context-style menu, menu, pull-down menu, pulldown menu, context menu, popup menu, actions menu, glass menu, frosted menu, ios menu, hig menu]
 ---
 
+DropdownMenuContent sits at elevation-4. Pick the material from the scenarios below — the `surface` prop is the discoverable lever.
+
+---
+
+### Scenario 1 — Overflow menu on a row/card (default opaque)
+
+The canonical "…" menu attached to a row or card. The content behind is a list — readability of the menu items matters more than seeing what's underneath.
+
 ```jsx
-// Overflow menu on a card/row — trigger an icon-only Button.
 <DropdownMenu>
   <DropdownMenuTrigger asChild>
     <Button variant="ghost" size="icon" aria-label="Open menu">
@@ -26,6 +35,7 @@ aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action
   <DropdownMenuContent align="end">
     <DropdownMenuItem onSelect={onDuplicate}>
       <Copy /> Duplicate
+      <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
     </DropdownMenuItem>
     <DropdownMenuItem onSelect={onShare}>
       <Share2 /> Share
@@ -38,8 +48,87 @@ aliases: [dropdown, dropdown menu, overflow menu, kebab menu, more menu, action
 </DropdownMenu>
 ```
 
-DropdownMenuContent ships at elevation-4. For frosted overlays on rich canvases, opt into glass:
+`solid` is the right default. Menu items are read-targets — give them a clean opaque background.
+
+---
+
+### Scenario 2 — Translucent menu (iOS / Apple HIG)
+
+You want the iOS-native menu feel: light translucency that picks up the colour of whatever's beneath without committing to a full blur. The Apple HIG canonical material for context menus.
+
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon"><MoreVertical /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent
+    surface="translucent"
+    className="shadow-elevation-4"
+    align="end"
+  >
+    <DropdownMenuLabel>Sort by</DropdownMenuLabel>
+    <DropdownMenuRadioGroup value={sort} onValueChange={setSort}>
+      <DropdownMenuRadioItem value="recent">Most recent</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="alpha">A–Z</DropdownMenuRadioItem>
+      <DropdownMenuRadioItem value="size">Size</DropdownMenuRadioItem>
+    </DropdownMenuRadioGroup>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+82% opacity. The background tints the menu without demanding the user filter it out.
+
+---
+
+### Scenario 3 — Glass menu in a canvas tool
+
+Studio's layer-context menu, an image editor's right-click, a slide-tool insert menu. The canvas behind is the work. Glass lets the menu float without cutting a hole through the work.
+
+```jsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild>
+    <Button variant="ghost" size="icon"><Plus /></Button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent
+    surface="glass"
+    className="shadow-elevation-4 w-56"
+    align="start"
+  >
+    <DropdownMenuLabel>Insert</DropdownMenuLabel>
+    <DropdownMenuItem><LayoutTemplate /> Layout</DropdownMenuItem>
+    <DropdownMenuItem><Image /> Media</DropdownMenuItem>
+    <DropdownMenuItem><Code2 /> Code block</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>
+      <DropdownMenuSubTrigger><Sparkles /> AI suggestion</DropdownMenuSubTrigger>
+      <DropdownMenuSubContent surface="glass" className="shadow-elevation-4">
+        <DropdownMenuItem>Layout variant</DropdownMenuItem>
+        <DropdownMenuItem>Tone shift</DropdownMenuItem>
+        <DropdownMenuItem>Density pass</DropdownMenuItem>
+      </DropdownMenuSubContent>
+    </DropdownMenuSub>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+Pass `surface="glass"` to BOTH the root content AND the sub-content — submenus default to `solid` so a glass parent with an opaque child looks broken. Match the surface consistently down the menu tree.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand on DropdownMenuContent.**
 
 ```jsx
-<DropdownMenuContent className="gds-surface-glass">…</DropdownMenuContent>
+{/* ❌ Misses the iOS-native edge highlight + theme blur tuning. */}
+<DropdownMenuContent className="bg-popover/55 backdrop-blur-md">
+
+{/* ✅ */}
+<DropdownMenuContent surface="glass">
 ```
+
+**DO NOT mix surfaces between content and sub-content.** A glass root with a solid submenu (or vice-versa) reads as two materials competing for attention. Pick one for the whole tree.
+
+**DO NOT use DropdownMenu for searchable lists.** Past ~7 items the menu becomes a scrollable list and the right primitive is Command (a search-first list inside a Popover or Dialog).
+
+**DO NOT put long-form text in menu items.** Items are action labels — verbs. If you need help text, that's a Popover surface, not a menu.

package/components/ui/hover-card.md

@@ -6,13 +6,21 @@ props:
   - HoverCard: open?, defaultOpen?, onOpenChange?, openDelay? (default 700), closeDelay? (default 300)
   - HoverCardTrigger: asChild?: boolean — usually a Link or Button
   - HoverCardContent: side?, align?, sideOffset?, alignOffset?, className?
-when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
-composes_with: [Avatar (user preview), Card (richer content), Link (the trigger)]
-aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card]
+  - HoverCardContent: surface? (solid | translucent | glass | glass-strong) — what the preview surface is *made of*. `solid` (default) is `bg-popover`. `glass` for hover previews over rich content (a media feed, a layout canvas).
+when_to_use: Rich preview content surfaced on hover — user profile mini-cards on @-mentions, link previews, definition popups, layer-thumbnail peeks. Pointer-only by design (no touch-friendly trigger); pair with a click target for touch devices, or fall back to Popover. NEVER use HoverCard for critical info — if the user can't reach it via keyboard or touch, it might as well not exist for accessibility.
+composes_with: [Avatar (user preview), Card (richer content), Link (the trigger), MediaSurface (link/layer previews), Code (snippet previews)]
+aliases: [hover card, hover preview, mention preview, profile peek, link preview, rich tooltip, link preview card, profile hover, peek card, glass preview, frosted preview]
 ---
 
+HoverCardContent sits at elevation-4. The surface choice depends entirely on what's behind the trigger.
+
+---
+
+### Scenario 1 — User mention preview (default opaque)
+
+The trigger is inline text in a comment thread, document, or feed. The reader's eye is on the prose; the hover-card needs to feel like a small contained card popping up next to the link. Opaque is correct.
+
 ```jsx
-// User mention preview — pointer-only enrichment.
 <HoverCard>
   <HoverCardTrigger asChild>
     <a href="/u/elena" className="font-medium underline">@elena</a>
@@ -28,8 +36,94 @@ aliases: [hover card, hover preview, mention preview, profile peek, link preview
         <span className="text-sm text-muted-foreground">
           Design lead · Joined Mar 2025
         </span>
+        <span className="text-sm">Currently focused on the layout-quality skill suite.</span>
       </Stack>
     </Row>
   </HoverCardContent>
 </HoverCard>
 ```
+
+---
+
+### Scenario 2 — Glass layer preview in a canvas tool
+
+You're hovering a layer name in the Studio layer list. The canvas alongside shows the actual layer in context. A glass hover-card carrying a thumbnail of the layer keeps the canvas visible AND gives the preview presence.
+
+```jsx
+<HoverCard openDelay={300}>
+  <HoverCardTrigger asChild>
+    <button className="text-sm hover:underline">Hero card · v0</button>
+  </HoverCardTrigger>
+  <HoverCardContent
+    surface="glass"
+    className="w-80 shadow-elevation-4"
+    side="right"
+    align="start"
+  >
+    <Stack gap="sm">
+      <MediaSurface
+        aspect="video"
+        source={{ kind: "image", src: "/previews/hero-v0.png" }}
+        alt="Hero card v0 thumbnail"
+      />
+      <Stack gap="xs">
+        <span className="text-sm font-medium">Hero card · v0</span>
+        <span className="text-xs text-muted-foreground">Last edited 2m ago by Elena</span>
+      </Stack>
+    </Stack>
+  </HoverCardContent>
+</HoverCard>
+```
+
+Tighter `openDelay` (300ms vs the default 700) because the user is scanning a list — they want previews to come up faster.
+
+---
+
+### Scenario 3 — Code snippet preview (translucent)
+
+You're showing a hover preview of a code reference (a function name in docs, a symbol in a comment). Translucent lets the page peek through without committing to glass blur — feels lighter for a quick read.
+
+```jsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <code className="font-mono text-sm rounded bg-muted px-1.5 py-0.5">surfaceBg()</code>
+  </HoverCardTrigger>
+  <HoverCardContent
+    surface="translucent"
+    className="w-96 shadow-elevation-4 p-0"
+  >
+    <Stack gap="xs" className="p-4 pb-2">
+      <span className="text-sm font-medium">surfaceBg(surface, defaultBgClass)</span>
+      <span className="text-xs text-muted-foreground">@gradeui/ui · lib/surface</span>
+    </Stack>
+    <Code
+      source={`function surfaceBg(surface, defaultBgClass) {
+  return surface === "solid" ? defaultBgClass : "";
+}`}
+      language="ts"
+      bare
+      className="text-xs p-4"
+    />
+  </HoverCardContent>
+</HoverCard>
+```
+
+---
+
+### Anti-patterns
+
+**DO NOT use HoverCard on touch devices for critical info.** There's no hover on touch — the preview is unreachable. Either provide a click fallback or use Popover.
+
+**DO NOT roll glass by hand on HoverCardContent.**
+
+```jsx
+{/* ❌ */}
+<HoverCardContent className="bg-popover/60 backdrop-blur-md">
+
+{/* ✅ */}
+<HoverCardContent surface="glass">
+```
+
+**DO NOT use HoverCard for tooltips.** Tooltips are tiny, label-only, and dismiss instantly. HoverCard is for rich content with delay. If the content is a few words, reach for Tooltip.
+
+**DO NOT use HoverCard as a primary navigation surface.** It dismisses on pointer-out — if the user has to traverse a path to reach a button inside, the preview will close before they get there.