@gradeui/ui 0.10.0 → 1.1.0

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]
+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,7 +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>
 ```
+
+`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
+<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/progress.md

@@ -7,6 +7,7 @@ props:
   - className?: string
 when_to_use: Determinate progress — file uploads, multi-step forms, quota meters. Indeterminate state → use Skeleton or animated Loader icon.
 composes_with: [Card (as a section), Badge (showing % next to it), Label (describing what's loading)]
+aliases: [progress, progress view, progress indicator, progress bar, determinate progress, loading bar, completion bar]
 ---
 
 ```jsx

package/components/ui/radio-group.md

@@ -14,7 +14,7 @@ props:
   - RadioGroupItem: disabled?: boolean
 when_to_use: A small set of mutually-exclusive options where the user needs to SEE all of them at once — pricing tiers (3-4 options), shipping speed, payment method radio cards. For 5+ options use Select. For a segmented control as part of a toolbar use ToggleGroup. For yes/no use Switch.
 composes_with: [Label (paired with each item via htmlFor), Stack (vertical list), Card (radio card pattern)]
-aliases: [radio group, radio buttons, single-choice, pricing options, payment method]
+aliases: [radio group, radio buttons, single-choice, pricing options, payment method, radio buttons, radio control, single-select]
 ---
 
 ```jsx

package/components/ui/resizable.md

@@ -13,7 +13,7 @@ props:
   - ResizableHandle: withHandle?: boolean — show a visible drag affordance (default just a hit-zone)
 when_to_use: A multi-pane layout where the user wants to drag the divider — Slack/Mail-style list+detail, IDE editor+terminal, side-by-side compare view. Static layouts shouldn't use this — reach for AppShell with nav="three-pane" (fixed widths) or Grid (responsive ladder). Built on react-resizable-panels under the hood.
 composes_with: [AppShellMain (host the splitter inside main), ScrollArea (each panel's content), Card]
-aliases: [resizable, splitter, split pane, drag divider, adjustable panels, resizer]
+aliases: [resizable, splitter, split pane, drag divider, adjustable panels, resizer, split view, draggable divider, split pane resizer, ns split view]
 ---
 
 ```jsx

package/components/ui/row.md

@@ -12,7 +12,7 @@ props:
   - children: React.ReactNode
 when_to_use: Horizontal composition — button groups, inline form rows, logo + nav rows, anything on one line. Reach for Row instead of `flex items-center gap-*` so the alignment and spacing are editable through the settings panel. For two-pane layouts with an explicit ratio (sidebar + content, 1/3 + 2/3) use Split instead — Row evenly flows whatever children it holds.
 composes_with: [Button, Input, NavItem, Stack (can wrap a Row), any content component]
-aliases: [row, hstack, horizontal, inline, horizontal layout]
+aliases: [row, hstack, horizontal, inline, horizontal layout, hstack, h-stack, horizontal stack, lazyhstack]
 ---
 
 ```jsx

package/components/ui/scroll-area.md

@@ -10,7 +10,7 @@ props:
   - ScrollBar: orientation? "vertical" | "horizontal" (default vertical)
 when_to_use: Bounded content that needs custom scroll chrome — sidebars with long item lists, chat transcripts, table panels inside a dashboard, anywhere the OS scrollbar would feel out of place against the design tokens. The wrapping element has to have a height constraint (`h-`, `max-h-`, or grid row sizing) or nothing scrolls — scroll-area can't infer a bound on its own. For body-level scrolling, leave the document to the browser.
 composes_with: [Card (long card body), AppShellNav (long sidebar), Sheet (long modal body), Table (sticky-header scrolling list)]
-aliases: [scroll area, scroll container, custom scrollbar, sidebar scroll, panel scroll]
+aliases: [scroll area, scroll container, custom scrollbar, sidebar scroll, panel scroll, scroll view, scrollview, react native scrollview]
 ---
 
 ```jsx

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

@@ -10,7 +10,7 @@ props:
   - SelectItem: value: string — required; content is the label
 when_to_use: Single-choice from 3+ known options. Fewer than 3 → RadioGroup. Huge list with search → use a Combobox (not in DS yet). Multi-select → not supported by this primitive.
 composes_with: [Label (above SelectTrigger), Form, Card]
-aliases: [dropdown, combobox, picker]
+aliases: [dropdown, combobox, picker, select, pop-up button, popup button, popup picker, picker view, rnpickerselect, react native picker, native picker]
 ---
 
 ```jsx

package/components/ui/separator.md

@@ -7,7 +7,7 @@ props:
   - className?: string
 when_to_use: Light divider between sibling blocks in a Card, list, or header. For section-level partition use extra spacing instead.
 composes_with: [Card (between CardHeader/Content/Footer), navigation menus, any vertical stacks]
-aliases: [divider, rule, hr]
+aliases: [divider, rule, hr, line, horizontal rule]
 ---
 
 ```jsx

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]
+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>
@@ -44,3 +52,93 @@ aliases: [sheet, drawer, side panel, slide-in, nav drawer, mobile drawer, slide-
   </SheetContent>
 </Sheet>
 ```
+
+`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
+{/* ❌ 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.

package/components/ui/side-menu.md

@@ -1,40 +0,0 @@
----
-name: SideMenu
-import: "@gradeui/ui"
-props:
-  - sections: SideMenuSection[] — top-level groups; each section has `{ title?, items }`
-  - sections[].title?: string — optional group heading
-  - sections[].items: SideMenuItem[] — `{ label, href?, icon?, active?, badge?, onClick? }`
-  - activeHref?: string — auto-derives `active` on matching items; falls back to per-item `active`
-  - onItemClick?: (item) => void — fires for client-side routing; complements per-item onClick
-  - className?: string
-when_to_use: The primary navigation rail inside an AppShell — Admin/Settings/Billing, Inbox/Sent/Archive, file-tree-ish sidebars. Always sits inside <AppShellNav placement="side">. For top horizontal nav, compose Row + Button/Link directly — Side Menu is vertical-stack-of-items by design. For palette-style jump-to, use Command.
-composes_with: [AppShellNav, AppShell, Avatar (header above the menu), Badge (item counts)]
-aliases: [side menu, sidebar nav, side nav, vertical nav, sidebar items, rail, side bar]
----
-
-```jsx
-// Inbox/Sent/Archive rail inside AppShellNav.
-<AppShellNav placement="side">
-  <SideMenu
-    activeHref="/inbox"
-    sections={[
-      {
-        title: "Mail",
-        items: [
-          { label: "Inbox", href: "/inbox", icon: <Inbox />, badge: "12" },
-          { label: "Sent", href: "/sent", icon: <Send /> },
-          { label: "Archive", href: "/archive", icon: <Archive /> },
-        ],
-      },
-      {
-        title: "Labels",
-        items: [
-          { label: "Work", href: "/label/work", icon: <Tag /> },
-          { label: "Personal", href: "/label/personal", icon: <Tag /> },
-        ],
-      },
-    ]}
-  />
-</AppShellNav>
-```