@gradeui/ui 1.0.0 → 1.1.0

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.

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.