@gradeui/ui 1.0.0 → 1.2.0

package/components/ui/message.md

@@ -0,0 +1,229 @@
+---
+name: Message
+import: "@gradeui/ui"
+props:
+  - author: string — display name of the message author
+  - timestamp?: ReactNode — string ("11:24", "2 hours ago") or any node for custom formatting
+  - avatar?: ReactNode — slot for any `<Avatar>` composition; omit for grouped messages from the same author
+  - badge?: ReactNode — small chip(s) next to the author name (OP, Bot, Admin, role tag)
+  - edited?: boolean | string — renders "(edited)" hint next to timestamp; pass a string to customise ("(edited 2 minutes ago)")
+  - pinned?: boolean — renders a pin glyph + "Pinned" label above the header row for sticky / pinned messages
+  - actions?: ReactNode — end-of-header slot, typically hover-revealed icon buttons (reply / react / more)
+  - reactions?: ReactNode — slot below the body, typically a Row of reaction chips (emoji + count)
+  - threadCount?: number — renders a "N replies" link affordance below the body
+  - onThreadClick?: () => void — handler for the threadCount affordance
+  - align?: "start" | "end" — `start` (default) puts the avatar on the left; `end` mirrors for "your messages" in DM threads
+  - children: ReactNode — body content (plain text or rich nodes)
+  - className?: string
+when_to_use: |
+  The canonical "avatar + author + timestamp + body" row. THE PRIMITIVE
+  for any chat surface, comment thread, post-reply, activity log, or
+  notification feed that follows the people-and-text shape.
+
+  CONCRETE TEST — if you find yourself composing an `<Avatar>` followed
+  by a `<Row>` of author name + timestamp, with a `<p>` or `<span>`
+  body below, STOP. That is `<Message>`. Reach for it directly.
+
+  Slack-style channel feed, Discord messages, Teams chat, Linear /
+  GitHub / Jira comments, Reddit replies, Twitter/X posts in a thread,
+  Notion comment sidebars, in-app activity logs, notification rows —
+  every one of these IS `<Message>`. Do not roll the layout inline.
+
+  For non-people activity (system events, log lines, status pings) use
+  Callout or a plain Row instead — Message implies a human author.
+composes_with: [Avatar (in the avatar slot — pair with AvatarFallback tone="..." for stable per-author colour), Badge (in the badge slot for role / OP / bot tags), Button (in actions, typically size="icon" + variant="ghost"), Stack (host multiple Messages in a thread), Card (wrap a Stack of Messages for a comment-thread block)]
+aliases: [
+  message, chat message, comment, post, reply, activity row, notification row,
+  thread row, channel message, dm message, slack message, discord message,
+  teams message, channel feed message, feed item, feed row, message row,
+  user message, user post, conversation message, conversation row,
+  inline comment, threaded reply, message bubble, chat bubble, talk bubble
+]
+---
+
+```jsx
+// Comment thread shape — avatar left, body below the author row.
+<Stack gap="md">
+  <Message
+    author="alice"
+    timestamp="2 hours ago"
+    avatar={
+      <Avatar size="sm">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Splitting this into two PRs makes the review tractable.
+  </Message>
+  <Message
+    author="ben"
+    timestamp="1 hour ago"
+    badge={<Badge variant="outline" className="text-[10px]">OP</Badge>}
+    avatar={
+      <Avatar size="sm">
+        <AvatarFallback tone="amber">B</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Agreed. I'll take the schema PR.
+  </Message>
+</Stack>
+```
+
+```jsx
+// Chat shape — your messages right-aligned via align="end".
+<Stack gap="md">
+  <Message
+    author="alice"
+    timestamp="11:24"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="violet">A</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Hey, how's the launch going?
+  </Message>
+  <Message
+    author="you"
+    timestamp="11:26"
+    align="end"
+    avatar={
+      <Avatar size="xs">
+        <AvatarFallback tone="emerald">Y</AvatarFallback>
+      </Avatar>
+    }
+  >
+    Launch image is in, scheduling now.
+  </Message>
+</Stack>
+```
+
+```jsx
+// Full Slack-style message — edited indicator, pinned flag, reactions
+// row, threaded reply count, role badge, hover actions.
+<Message
+  author="alice"
+  timestamp="11:24"
+  edited
+  pinned
+  badge={<Badge variant="secondary" className="text-[10px]">Designer</Badge>}
+  avatar={
+    <Avatar size="md">
+      <AvatarFallback tone="violet">A</AvatarFallback>
+    </Avatar>
+  }
+  reactions={
+    <>
+      <Badge variant="outline" className="gap-1 cursor-pointer">👍 4</Badge>
+      <Badge variant="outline" className="gap-1 cursor-pointer">🎉 2</Badge>
+    </>
+  }
+  threadCount={3}
+  onThreadClick={() => openThread(messageId)}
+>
+  Updated the token spec — review when you have a chance.
+</Message>
+```
+
+```jsx
+// Slack / Discord channel feed — with role badge + hover-revealed actions.
+<Stack gap="lg">
+  {messages.map((m) => (
+    <Message
+      key={m.id}
+      author={m.user}
+      timestamp={m.time}
+      badge={<Badge variant="secondary" className="text-[10px]">{m.role}</Badge>}
+      avatar={
+        <Avatar size="md">
+          <AvatarImage src={m.avatar} />
+          <AvatarFallback tone="sky">{m.user.charAt(0)}</AvatarFallback>
+        </Avatar>
+      }
+      actions={
+        <Row gap="xs" className="opacity-0 group-hover:opacity-100 transition-opacity">
+          <Button size="icon" variant="ghost" className="h-6 w-6"><Smile className="h-3 w-3" /></Button>
+          <Button size="icon" variant="ghost" className="h-6 w-6"><Reply className="h-3 w-3" /></Button>
+          <Button size="icon" variant="ghost" className="h-6 w-6"><MoreHorizontal className="h-3 w-3" /></Button>
+        </Row>
+      }
+      className="group"
+    >
+      {m.text}
+    </Message>
+  ))}
+</Stack>
+```
+
+## Anti-patterns
+
+```jsx
+// ❌ Rolling the message layout by hand from Avatar + Row + Badge + spans.
+//    This is the EXACT shape Message exists to consolidate — caught in
+//    the wild on a "Slack clone" prompt where the model assembled this
+//    inline instead of reaching for Message. The result loses the
+//    align="end" knob, the actions slot, the data-gds-part hooks, and
+//    duplicates the same flex template across every consumer.
+{messages.map((msg) => (
+  <div className="group flex gap-4">
+    <Avatar className="w-9 h-9 shrink-0">
+      <AvatarImage src={msg.avatar} />
+      <AvatarFallback>{msg.user.charAt(0)}</AvatarFallback>
+    </Avatar>
+    <div className="flex-1 min-w-0">
+      <Row gap="sm" align="baseline">
+        <span className="font-semibold text-sm">{msg.user}</span>
+        <Badge variant="secondary" className="text-[10px]">{msg.role}</Badge>
+        <span className="text-[10px] text-muted-foreground">{msg.time}</span>
+      </Row>
+      <p className="text-sm mt-1">{msg.text}</p>
+    </div>
+  </div>
+))}
+
+// ✅ The Grade way.
+{messages.map((msg) => (
+  <Message
+    key={msg.id}
+    author={msg.user}
+    timestamp={msg.time}
+    badge={<Badge variant="secondary" className="text-[10px]">{msg.role}</Badge>}
+    avatar={
+      <Avatar size="md">
+        <AvatarImage src={msg.avatar} />
+        <AvatarFallback>{msg.user.charAt(0)}</AvatarFallback>
+      </Avatar>
+    }
+  >
+    {msg.text}
+  </Message>
+))}
+```
+
+```jsx
+// ❌ Building a custom "AuthorDot" or "MessageRow" component inline as
+//    a one-off helper inside a scaffold. Three scaffolds did this before
+//    Message landed; the pattern is always identical.
+function MessageRow({ user, body, time }) {
+  return (
+    <div className="flex gap-3 items-start">
+      <div className="h-7 w-7 rounded-full bg-violet-500/20 ...">{user[0]}</div>
+      <div>
+        <Row><strong>{user}</strong> <small>{time}</small></Row>
+        <p>{body}</p>
+      </div>
+    </div>
+  );
+}
+
+// ✅ Use Message. The colored-initials avatar pattern is covered by
+//    Avatar + AvatarFallback tone="...".
+<Message
+  author={user}
+  timestamp={time}
+  avatar={<Avatar size="sm"><AvatarFallback tone="violet">{user[0]}</AvatarFallback></Avatar>}
+>
+  {body}
+</Message>
+```

package/components/ui/popover.md

@@ -6,18 +6,26 @@ props:
   - Popover: open?, defaultOpen?, onOpenChange?, modal? (default false)
   - PopoverTrigger: asChild?: boolean — usually a Button
   - PopoverContent: side? "top" | "right" | "bottom" | "left"; align? "start" | "center" | "end"; sideOffset?, alignOffset?, collisionPadding?, className?
+  - PopoverContent: surface? (solid | translucent | glass | glass-strong) — what the popover surface is *made of*. `solid` is the default opaque `bg-popover`. `translucent` is the Apple HIG menu-sheet feel. `glass` for floating panels over rich canvases (Studio inspector, image-tool palette).
   - PopoverAnchor: asChild?: boolean — pin the popover to a different element than the trigger
 when_to_use: A floating panel anchored to a trigger that contains interactive content — date pickers, color pickers, filter pickers, "more info" panels, inline forms. Differs from Tooltip (hover-only, no focusable content) and Dialog (modal, blocks the page). DatePicker, DateRangePicker, and the Combobox pattern all compose Popover internally.
-composes_with: [Button (as trigger), Calendar (date picker), Command (combobox), Form controls (inline edit popover)]
-aliases: [popover, dropdown panel, floating panel, inline editor, attached panel, filter pop, popover view, popoverpresentation, attached popover]
+composes_with: [Button (as trigger), Calendar (date picker), Command (combobox), Form controls (inline edit popover), Code (code-detail popovers)]
+aliases: [popover, dropdown panel, floating panel, inline editor, attached panel, filter pop, popover view, popoverpresentation, attached popover, glass popover, frosted popover, inspector popover]
 ---
 
+PopoverContent sits at elevation-4. Three scenario recipes — match the material to the canvas the popover floats over.
+
+---
+
+### Scenario 1 — Filter popover (default opaque)
+
+You're attaching a filter picker to a button in a list/table header. The page behind is mostly white space and a table — there's nothing visually important to preserve through the popover. Opaque is the right default.
+
 ```jsx
-// Filter popover anchored to a Button trigger.
 <Popover>
   <PopoverTrigger asChild>
     <Button variant="outline" size="sm">
-      <Filter /> Filters
+      <Filter className="h-4 w-4" /> Filters
     </Button>
   </PopoverTrigger>
   <PopoverContent className="w-72" align="end">
@@ -30,14 +38,118 @@ aliases: [popover, dropdown panel, floating panel, inline editor, attached panel
         <Label>Status</Label>
         <Select>{/* … */}</Select>
       </Stack>
+      <Row justify="end" gap="xs">
+        <Button variant="ghost" size="sm">Clear</Button>
+        <Button size="sm">Apply</Button>
+      </Row>
     </Stack>
   </PopoverContent>
 </Popover>
 ```
 
-PopoverContent ships at elevation-4. Opt into glass for a frosted look, or layer in aura when the popover is AI-driven:
+`solid` keeps the form fields maximally legible. Filter popovers are read-heavy; legibility wins over aesthetic.
+
+---
+
+### Scenario 2 — Glass inspector popover (creative tool aesthetic)
+
+You're building Studio, a presentation editor, or a vector tool. The user clicked a selected layer and a popover offers per-element knobs. The canvas behind is the work — they need to keep spatial awareness of what they just clicked. Glass is the canonical signal.
 
 ```jsx
-<PopoverContent className="gds-surface-glass">…</PopoverContent>
-<PopoverContent className="gds-aura-ring">Studio suggestion</PopoverContent>
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="ghost" size="icon"><Palette className="h-4 w-4" /></Button>
+  </PopoverTrigger>
+  <PopoverContent
+    surface="glass"
+    className="w-80 shadow-elevation-4"
+    align="end"
+    sideOffset={8}
+  >
+    <Stack gap="md">
+      <Row justify="between" align="center">
+        <span className="text-sm font-medium">Button — selected</span>
+        <Badge variant="outline">raised</Badge>
+      </Row>
+
+      <Stack gap="xs">
+        <Label>Tone</Label>
+        <Row gap="xs">
+          <Button size="sm" variant="raised" style={{ "--btn-glow": "var(--selected-glow)" }} />
+          <Button size="sm" variant="raised" style={{ "--btn-glow": "var(--success)" }} />
+          <Button size="sm" variant="raised" style={{ "--btn-glow": "var(--warning)" }} />
+          <Button size="sm" variant="raised" style={{ "--btn-glow": "var(--destructive)" }} />
+        </Row>
+      </Stack>
+
+      <Stack gap="xs">
+        <Label>Size</Label>
+        <ToggleGroup type="single" defaultValue="md">
+          <ToggleGroupItem value="sm">sm</ToggleGroupItem>
+          <ToggleGroupItem value="md">md</ToggleGroupItem>
+          <ToggleGroupItem value="lg">lg</ToggleGroupItem>
+        </ToggleGroup>
+      </Stack>
+    </Stack>
+  </PopoverContent>
+</Popover>
 ```
+
+`surface="glass"` + `shadow-elevation-4` is the Studio-inspector signature. The user's eye stays on the canvas; the popover reads as chrome layered above it.
+
+---
+
+### Scenario 3 — AI suggestion popover (translucent + aura)
+
+A different shape from the destructive Dialog confirmation: an inline AI suggestion that surfaces while the user keeps working. Translucent stays light; aura announces the AI origin.
+
+```jsx
+<Popover open={hasSuggestion}>
+  <PopoverAnchor>
+    <Code source={selectedSnippet} language="tsx" highlight={[3]} bare />
+  </PopoverAnchor>
+  <PopoverContent
+    surface="translucent"
+    className="w-96 shadow-elevation-4 gds-aura-ring"
+    style={{ "--aura-color": "var(--selected-glow)" }}
+    side="bottom"
+    align="start"
+  >
+    <Stack gap="sm">
+      <Row gap="xs" align="center">
+        <Sparkles className="h-4 w-4" />
+        <span className="text-sm font-medium">Studio suggestion</span>
+      </Row>
+      <p className="text-sm">
+        This Toolbar would line up edge-to-edge with the TabsList below if it used <code>size="sm"</code>. Apply?
+      </p>
+      <Row justify="end" gap="xs">
+        <Button variant="ghost" size="sm">Dismiss</Button>
+        <Button size="sm">Apply</Button>
+      </Row>
+    </Stack>
+  </PopoverContent>
+</Popover>
+```
+
+Note `PopoverAnchor` — the popover is pinned to the selected snippet, not to a trigger button. This is the "annotation surfaces next to the thing it annotates" pattern.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand on PopoverContent.**
+
+```jsx
+{/* ❌ Misses edge highlight, fixed-step blur. */}
+<PopoverContent className="bg-popover/50 backdrop-blur-md">
+
+{/* ✅ */}
+<PopoverContent surface="glass">
+```
+
+**DO NOT use Popover for content that needs a modal interaction.** Popover is non-modal — pointer-down outside dismisses it. If the user must decide before continuing, reach for Dialog.
+
+**DO NOT use `surface="glass-strong"` on PopoverContent.** It's tuned for full-page overlays; on a 288px popover it just reads as washed out.
+
+**DO NOT use Popover when the trigger is a hover target with no focusable content.** That's Tooltip's job — Popover requires focus, Tooltip dismisses on hover-out.

package/components/ui/section-block.md

@@ -0,0 +1,153 @@
+---
+name: SectionBlock
+import: "@gradeui/ui"
+props:
+  - padding? (none | sm | md | lg | xl) — vertical rhythm. Defaults to `lg`.
+  - background? (transparent | muted | card | primary | gradient) — tonal direction of the section bg.
+  - surface? (solid | translucent | glass | glass-strong) — what the section is *made of*. Orthogonal to `background`. Use `glass` for hero sections that float over a generative backdrop / image / dot grid.
+  - container? (default | wide | narrow | full) — max-width of the inner content.
+  - alignment? (left | center | right) — header / CTA alignment.
+  - titleSize? (sm | md | lg | xl)
+  - title?: string
+  - subtitle?: string
+  - cta1? / cta2? — string or `{ text, variant, href, onClick }` config
+  - backgroundImage?: string — direct CSS background image url
+  - as? "section" | "div" | "article" — semantic root
+  - fullBleed?: boolean
+when_to_use: The top-level container for a marketing page section — hero, feature row, pricing table, testimonial strip, FAQ section. Always reach for SectionBlock over a hand-rolled `<section>` so vertical rhythm, container width, and tonal background stay consistent across the page. Pair `background="gradient"` + `surface="glass"` inner Cards for the "modern marketing hero" pattern.
+composes_with: [Card (the most common child — especially with surface="glass"), Grid (feature rows), Stack (hero column), MediaSurface (hero imagery), Code (developer hero), Carousel (logo strips)]
+aliases: [section, section block, hero section, marketing section, page section, content section, container section, feature section, hero, page hero, marketing hero, glass section, gradient section, mesh hero]
+---
+
+SectionBlock is the **container axis** of a marketing page; Card is the **content axis** inside it. Three Presence axes still apply to SectionBlock: `background` (tonal direction), `surface` (material), `padding` (depth of vertical rhythm).
+
+---
+
+### Scenario 1 — Standard feature row (default)
+
+You're laying out a feature section on a marketing page — a row of cards explaining capabilities. Calm tonal background, generous padding, default container width.
+
+```jsx
+<SectionBlock
+  padding="lg"
+  background="muted"
+  title="Built for production"
+  subtitle="The hard primitives every team eventually needs."
+  alignment="center"
+>
+  <Grid cols="3" gap="md">
+    <Card>
+      <CardHeader>
+        <Database className="h-5 w-5" />
+        <CardTitle>Data tables</CardTitle>
+        <CardDescription>Sorting, filtering, virtualisation.</CardDescription>
+      </CardHeader>
+    </Card>
+    <Card>
+      <CardHeader>
+        <Map className="h-5 w-5" />
+        <CardTitle>Maps</CardTitle>
+        <CardDescription>MapLibre default. Mapbox + Google adapters.</CardDescription>
+      </CardHeader>
+    </Card>
+    <Card>
+      <CardHeader>
+        <MoveVertical className="h-5 w-5" />
+        <CardTitle>Drag and drop</CardTitle>
+        <CardDescription>dnd-kit underneath, themed against tokens.</CardDescription>
+      </CardHeader>
+    </Card>
+  </Grid>
+</SectionBlock>
+```
+
+No `surface` prop. The default `solid` is the right answer for in-flow feature rows — the muted background sets the section apart from neighbouring sections cleanly.
+
+---
+
+### Scenario 2 — Gradient hero with glass cards (modern marketing pattern)
+
+The canonical "shadcn-killer marketing hero" pattern. SectionBlock supplies the gradient mesh; Card children opt into glass; the two compose without either having to know about the other.
+
+```jsx
+<SectionBlock
+  padding="xl"
+  background="gradient"
+  alignment="center"
+  title="Open the markup. Tell me which one you would merge."
+  subtitle="GradeUI produces code you would actually integrate."
+  cta1={{ text: "Open Studio", href: "/studio" }}
+  cta2={{ text: "Install the library", variant: "outline" }}
+>
+  <Grid cols="2" gap="md" className="mt-8">
+    <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>
+```
+
+This is the pattern the home-diff-hero scaffold uses. `background="gradient"` paints the mesh; the Cards float through it via `surface="glass"`; `gds-aura-ring` on the second card draws the eye to the recommended path. No Tailwind soup anywhere.
+
+---
+
+### Scenario 3 — Glass section over a backgroundImage (image hero)
+
+You're using a hero image as the section background. A solid section panel over it would defeat the image. A glass section keeps the image visible while focusing the eye on the content overlay.
+
+```jsx
+<SectionBlock
+  padding="xl"
+  surface="glass"
+  backgroundImage="/hero/teams-shipping.jpg"
+  alignment="center"
+  title="For teams shipping software"
+  subtitle="The primitive layer modern product teams actually use."
+  cta1={{ text: "Open Studio" }}
+  container="narrow"
+>
+  <Row justify="center" gap="lg" className="text-sm text-muted-foreground">
+    <span>Linear</span><span>Vercel</span><span>Stripe</span><span>Anthropic</span>
+  </Row>
+</SectionBlock>
+```
+
+`background` stays at the default `transparent` so the image shows through; `surface="glass"` paints the frosted overlay on top with edge highlight + theme-tuned blur. The narrow container caps content width so the hero stays readable over the image.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand at the section level.**
+
+```jsx
+{/* ❌ */}
+<section className="py-20 bg-card/40 backdrop-blur-md">
+
+{/* ✅ */}
+<SectionBlock surface="glass" padding="xl">
+```
+
+**DO NOT use `background="primary"` + `surface="glass"`.** The primary fill is intentionally opaque (it's a brand statement). Layering glass on top makes the brand colour read as washed-out. Pick one signal.
+
+**DO NOT skip SectionBlock for marketing rows.** Hand-rolling `<section className="py-20">` means every section gets a slightly different vertical rhythm and container width — the page reads as drift. SectionBlock is the rhythm primitive.
+
+**DO NOT use `padding="xl"` for in-app sections.** xl padding is marketing-page territory. In-app section breaks should use `sm` or `md` — anything more and your dashboard reads as a marketing page.
+
+**DO NOT use `surface="glass-strong"` on SectionBlock unless the section is acting as a full-page overlay.** It's tuned for very heavy de-emphasis of what's underneath; on a regular section it just looks washed-out.

package/components/ui/sheet.md

@@ -6,16 +6,24 @@ props:
   - Sheet: open?, defaultOpen?, onOpenChange?, modal? (default true)
   - SheetTrigger: asChild?: boolean
   - SheetContent: side? "top" | "right" | "bottom" | "left" (default "right")
+  - SheetContent: surface? (solid | translucent | glass | glass-strong) — what the sheet panel is *made of*. `solid` is the default opaque `bg-background`. Reach for `glass` whenever the canvas behind the sheet (a layout in progress, a media gallery, a dashboard) should remain visible.
   - SheetContent: className?: string — usually set a width (right/left) or height (top/bottom)
   - SheetTitle / SheetDescription: identify the sheet to screen readers; required for accessibility even if visually styled differently
   - SheetClose: asChild? — usually wraps a Button labelled Cancel or Done
-when_to_use: A panel that slides in from a screen edge — mobile nav drawers, side panels for editing a single record without leaving the list, filter trays on small viewports. For a centered focus modal use Dialog. For a transient announcement use Toast (Sonner). For inline reveals use Collapsible.
-composes_with: [Form controls (an inline edit sheet), Button (trigger + close), AppShellNav (mobile-only swap)]
-aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over, action sheet, modal sheet, bottom sheet, side sheet, react native modal sheet, bottom-sheet, ios action sheet]
+when_to_use: A panel that slides in from a screen edge — mobile nav drawers, side panels for editing a single record without leaving the list, filter trays on small viewports, Studio-style inspector panels. For a centered focus modal use Dialog. For a transient announcement use Toast (Sonner). For inline reveals use Collapsible.
+composes_with: [Form controls (an inline edit sheet), Button (trigger + close), AppShellNav (mobile-only swap), Code (changelog drawers), MediaSurface (image-detail sheets)]
+aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-over, action sheet, modal sheet, bottom sheet, side sheet, react native modal sheet, bottom-sheet, ios action sheet, inspector panel, glass sheet, frosted drawer]
 ---
 
+SheetContent sits at elevation-5. The `surface` axis controls material independently of `side` (which controls layout direction) — every combination is valid.
+
+---
+
+### Scenario 1 — Edit-record drawer (default opaque)
+
+A right-edge drawer that lets a user edit one record without losing their place in a list. The list is the user's context — the drawer doesn't need to blur it; it just needs to be visibly distinct.
+
 ```jsx
-// Edit-record drawer from the right edge.
 <Sheet>
   <SheetTrigger asChild>
     <Button variant="outline">Edit user</Button>
@@ -45,8 +53,92 @@ aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-
 </Sheet>
 ```
 
-SheetContent ships at elevation-5. Opt into a frosted glass sheet when the canvas behind it should remain visible:
+`solid` is the right default for editing workflows. Form fields need maximum legibility; blur behind them works against that.
+
+---
+
+### Scenario 2 — Glass inspector panel (creative tool aesthetic)
+
+You're building a creative tool. The canvas is the work — a Studio layout, an image being annotated, a presentation slide. The inspector panel needs to live alongside the work without obscuring it. Glass is the canonical "I am chrome, not content" signal.
+
+```jsx
+<Sheet open={hasSelection} modal={false}>
+  <SheetContent
+    side="right"
+    surface="glass"
+    className="w-96 shadow-elevation-5"
+  >
+    <SheetHeader>
+      <SheetTitle>Selection</SheetTitle>
+      <SheetDescription>Button — Toolbar &gt; trailing</SheetDescription>
+    </SheetHeader>
+
+    <Stack gap="md" className="py-4">
+      <Stack gap="xs">
+        <Label>Variant</Label>
+        <Select defaultValue="raised">{/* … */}</Select>
+      </Stack>
+      <Stack gap="xs">
+        <Label>Size</Label>
+        <ToggleGroup type="single" defaultValue="md">
+          <ToggleGroupItem value="sm">sm</ToggleGroupItem>
+          <ToggleGroupItem value="md">md</ToggleGroupItem>
+          <ToggleGroupItem value="lg">lg</ToggleGroupItem>
+        </ToggleGroup>
+      </Stack>
+    </Stack>
+  </SheetContent>
+</Sheet>
+```
+
+Three things to notice: `modal={false}` so the user keeps interacting with the canvas while the inspector is open; `surface="glass"` so the canvas reads through; `shadow-elevation-5` to lift the panel cleanly off the canvas. This is the Studio inspector pattern.
+
+---
+
+### Scenario 3 — Bottom action sheet (mobile, glass for iOS feel)
+
+The iOS-native action sheet has glass behind it. Matching that material on mobile flows is "feels like a native app" by default.
+
+```jsx
+<Sheet open={pickerOpen} onOpenChange={setPickerOpen}>
+  <SheetContent
+    side="bottom"
+    surface="glass"
+    className="rounded-t-2xl"
+  >
+    <SheetHeader className="text-center">
+      <SheetTitle>Share screen</SheetTitle>
+    </SheetHeader>
+    <Stack gap="xs" className="py-4">
+      <Button variant="ghost" className="justify-start"><Mail /> Email</Button>
+      <Button variant="ghost" className="justify-start"><MessageCircle /> Message</Button>
+      <Button variant="ghost" className="justify-start"><Copy /> Copy link</Button>
+    </Stack>
+    <SheetClose asChild>
+      <Button variant="outline" className="w-full">Cancel</Button>
+    </SheetClose>
+  </SheetContent>
+</Sheet>
+```
+
+`side="bottom"` + `surface="glass"` + `rounded-t-2xl` is the iOS action-sheet recipe. The rounded top corners signal "this can be dismissed by dragging down" even before any gesture handler is wired up.
+
+---
+
+### Anti-patterns
+
+**DO NOT roll glass by hand on SheetContent.**
 
 ```jsx
-<SheetContent className="gds-surface-glass">…</SheetContent>
+{/* ❌ Tailwind soup — no edge highlight, blur isn't theme-tuned. */}
+<SheetContent className="bg-background/60 backdrop-blur-md">
+
+{/* ✅ */}
+<SheetContent surface="glass">
 ```
+
+**DO NOT use `surface="glass"` for a modal sheet that contains a long form.** Form legibility wins over aesthetic. If the user is going to spend 30 seconds in this sheet, give them an opaque background.
+
+**DO NOT pair `surface="glass"` with `modal={true}` and the default scrim.** The scrim already dims the canvas — adding glass on top of a dimmed canvas reads as "two competing layers of de-emphasis". Either turn off the scrim (`modal={false}`), or use `surface="solid"`.
+
+**DO NOT skip SheetTitle.** Screen readers announce it on open. If the design has no visible title, wrap a `sr-only` one.