@gradeui/ui 0.10.0 → 1.1.0

package/components/ui/button.md

@@ -1,16 +1,17 @@
 ---
 name: Button
 import: "@gradeui/ui"
-variants: [default, destructive, outline, secondary, ghost, link]
+variants: [default, destructive, outline, secondary, ghost, link, raised]
 sizes: [sm, md, lg, icon]
 props:
-  - variant? (default | destructive | outline | secondary | ghost | link)
+  - variant? (default | destructive | outline | secondary | ghost | link | raised)
   - size? (sm | md | lg | icon) — t-shirt scale aligned with Tabs/ToggleGroup heights (sm=h-7, md=h-8, lg=h-10). `default` still works as an alias for `md`.
   - asChild?: boolean — renders as the child element (use to wrap <a>/<Link>)
   - disabled?: boolean
   - All native button HTML attrs (onClick, type, etc.)
-when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
+when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, variant="raised" for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment. A Button placed next to a TabsList of the same size lines up edge-to-edge without per-call overrides.
 composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form controls]
+aliases: [button, push button, plain button, bordered button, destructive button, capsule button, link button, action button, cta, raised button, pill button, key button]
 ---
 
 ```jsx
@@ -29,3 +30,34 @@ composes_with: [Dialog, DropdownMenu, Tooltip, Card (in CardFooter), Row, Form c
   <Button size="sm">New issue</Button>
 </Row>
 ```
+
+```jsx
+// Raised variant — tactile bevel + drop shadow + ambient hover glow.
+// Composed from the Presence elevation tokens (--elevation-3 rest,
+// --elevation-hot hover, --elevation-pressed active). Tone is driven
+// by --btn-glow, which defaults to --selected-glow (blue). Override
+// per-button for "traffic light" semantics:
+<Row gap="sm">
+  <Button variant="raised" style={{ "--btn-glow": "var(--warning)" }}>
+    Iterate
+  </Button>
+  <Button variant="raised" style={{ "--btn-glow": "var(--success)" }}>
+    Ship it
+  </Button>
+</Row>
+```
+
+```jsx
+// data-state="on" / aria-pressed="true" gives the held-down "key
+// pressed" look — picks up the --selected blue stroke + heat-inner
+// glow. Works as a Toggle/ToggleGroupItem child via asChild.
+<Button variant="raised" data-state="on">Locked</Button>
+```
+
+```jsx
+// Combine with Aura for AI-attention states. The three Aura styles
+// (ring/gradient/shimmer) stack independently of the variant.
+<Button variant="raised" className="gds-aura-ring">
+  Studio is reviewing this
+</Button>
+```

package/components/ui/calendar.md

@@ -15,7 +15,7 @@ props:
   - className?: string
 when_to_use: An inline date grid — date-of-birth pickers in profile forms, scheduling screens with a month view, range selection in reporting filters. For a compact trigger-and-popover input, use DatePicker / DateRangePicker (which wrap Calendar internally). For one-off relative dates ("yesterday", "last week") use a Select instead.
 composes_with: [Popover (DatePicker composes them), Card (inline scheduling card), Dialog (full-screen mobile date pick)]
-aliases: [calendar, date grid, month view, scheduler grid]
+aliases: [calendar, date grid, month view, scheduler grid, calendar view, multidate picker, react native calendars]
 ---
 
 ```jsx

package/components/ui/callout.md

@@ -0,0 +1,45 @@
+---
+name: Callout
+import: "@gradeui/ui"
+subcomponents: [CalloutTitle, CalloutDescription]
+variants: [default, destructive, success, warning, info]
+props:
+  - variant? (default | destructive | success | warning | info) — semantic colouring; `default` is neutral
+  - All native div HTML attrs
+when_to_use: Inline, ambient, non-blocking status/feedback that sits inside the layout flow. Form-level validation summaries, settings-page notices, page-level banners. NOT a toast (use Sonner for transient). NOT a modal (use Dialog when the user must respond). Put an icon as first child — it's auto-positioned; CalloutTitle + CalloutDescription follow.
+composes_with: [lucide-react icons as first child, Button (inside CalloutDescription), Card (as a section callout)]
+aliases: [callout, banner, notice, inline alert, in-app notification, status banner, info banner, info callout, warning callout, success callout]
+---
+
+Renamed from `Alert` (May 2026). The old name implied modal/interruptive behaviour the component doesn't have — Apple HIG `Alert` is a modal, and `role="alert"` is assertive ARIA. Callout is honest about what it is: ambient, inline, non-blocking. For genuinely interruptive needs, reach for `<Dialog>`.
+
+Variant tokens come from theme (`--destructive-soft`, `--success-deep`, etc.) so they restyle with the active Grade theme.
+
+```jsx
+<Callout variant="warning">
+  <AlertTriangle />
+  <CalloutTitle>Low disk space</CalloutTitle>
+  <CalloutDescription>2GB remaining on /dev/sda1.</CalloutDescription>
+</Callout>
+```
+
+```jsx
+// Ambient success notice — uses role="status" (polite) so screen
+// readers don't interrupt the user. Warning/destructive get
+// role="alert" (assertive) instead.
+<Callout variant="success">
+  <CheckCircle2 />
+  <CalloutTitle>Profile updated</CalloutTitle>
+  <CalloutDescription>Your changes are live.</CalloutDescription>
+</Callout>
+```
+
+### Anti-patterns
+
+DO NOT use `<Callout>` for interruptive or blocking messages. If the user must respond before continuing, use `<Dialog>` — the modal primitive that Apple HIG calls "Alert" and React Native exposes as `Alert.alert()`. Callout is ambient by design.
+
+DO NOT pass `role="alert"` when the variant is `info` / `success` / `default` — the component already routes those to `role="status"` (polite), and overriding makes screen readers interrupt for non-urgent content.
+
+DO NOT reach for `variant="warning"` to convey "this is just notable / FYI" — that's what `variant="info"` is for. Warning is for things that could go wrong if ignored; info is for ambient context.
+
+The previous `variant="highlight"` (yellow) was dropped in the Alert → Callout rename — it overlapped `warning` semantically without offering a distinct intent. Use `warning` for amber attention and `info` for neutral attention.

package/components/ui/card.md

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

package/components/ui/carousel.md

@@ -0,0 +1,56 @@
+---
+name: Carousel
+import: "@gradeui/ui"
+subcomponents: [Carousel.Slide, Carousel.VideoSlide, Carousel.Dots, Carousel.Arrows]
+props:
+  - Carousel: loop?: boolean — wrap last → first (default true)
+  - Carousel: align?: "start" | "center" | "end" — slide alignment (default start)
+  - Carousel: slidesPerView?: number — how many slides visible at once (default 1)
+  - Carousel: autoplay?: boolean | { delay?: number; pauseOnHover?: boolean; pauseWhenOffscreen?: boolean } — true for defaults (5s, hover/offscreen aware)
+  - Carousel: draggable?: boolean — drag-to-swipe (default true)
+  - Carousel: onSlideChange?: (index: number) => void
+  - Carousel.Slide: duration?: number — per-slide autoplay duration in ms; overrides the carousel default for this slide only
+  - Carousel.VideoSlide: src: string — video URL
+  - Carousel.VideoSlide: poster?: string — image shown until the slide is active
+  - Carousel.VideoSlide: alt?: string — accessible label for the video
+  - Carousel.VideoSlide: loop?: boolean — default true (the chosen video-default behaviour)
+  - Carousel.VideoSlide: controls?: boolean — default false (chosen default = no controls)
+  - Carousel.VideoSlide: fit?: "cover" | "contain" — object-fit (default cover)
+  - Carousel.VideoSlide: duration?: number — same as Carousel.Slide; overrides autoplay timing for THIS slide
+  - Carousel.Dots: position?: "below" | "overlay"
+  - Carousel.Arrows: position?: "overlay" | "outside"
+when_to_use: Anywhere a horizontal stack of slides cycles automatically or on user input — marketing hero rotations, featured rails on a TV / streaming app, onboarding tours, image galleries, product carousels, testimonial cycles. Mixed video + still slides are a first-class case; the VideoSlide handles muted-autoplay + poster swap on activation.
+composes_with: [MediaSurface, Card, Stack, Row]
+aliases: [carousel, slideshow, slider, hero rotation, image gallery, featured row, swipe deck, paged view, page tabview, page view, swiper, react native swiper, page control]
+---
+
+```jsx
+<Carousel autoplay={{ delay: 6000 }} loop>
+  <Carousel.Slide duration={15000}>
+    <MediaSurface aspect="wide" hint="poster" alt="Featured: Severance S2" />
+  </Carousel.Slide>
+
+  <Carousel.VideoSlide
+    src="/trailers/the-studio.mp4"
+    poster="/posters/the-studio.jpg"
+    alt="The Studio — official trailer"
+  />
+
+  <Carousel.Slide>
+    <MediaSurface aspect="wide" hint="poster" alt="Coming soon: Foundation S3" />
+  </Carousel.Slide>
+
+  <Carousel.Arrows />
+  <Carousel.Dots position="overlay" />
+</Carousel>
+```
+
+### Anti-patterns
+
+DO NOT confuse `<Carousel>` with `<Slider>`. `Slider` is the range input (a draggable thumb on a track) — the colloquial "slider" you'd put on a marketing page is a `Carousel`. When the user says "add a slider", check whether they want a range control or a slideshow before reaching for either.
+
+DO NOT pass real `<img>` or `<video>` tags directly as `Carousel.Slide` children when the slide is meant to be a hero media tile. Use `<MediaSurface>` (still slots) or `<Carousel.VideoSlide>` (video slots) so themes, aspect ratios, and the future image-generation pipeline stay consistent. Raw `<img>` inside a slide is fine for fully-authored content (logo strips, certificates), but for "media that might get regenerated" the surface primitive is mandatory.
+
+DO NOT set very short `duration` values (sub-2000ms) on still slides — the autoplay timer ignores the request implicitly when the carousel is paused (hover, offscreen) but very fast cycles read as broken to users. 5-15 seconds per slide is the natural range.
+
+DO NOT mount the autoplay timer inside individual slides via `setInterval` and forget to clean up — use `<Carousel.Slide duration>` instead. The carousel root owns the single timer; per-slide overrides feed into it through a context-shared ref.

package/components/ui/chart.md

@@ -12,7 +12,7 @@ props:
   - ChartLegend / ChartLegendContent: pair the same way for the legend
 when_to_use: Reporting dashboards, single-purpose analytics cards (revenue, conversions, active users), or anywhere you'd otherwise hand-roll a Recharts setup. Bring the actual chart type from `recharts` — ChartContainer doesn't pick the chart shape for you, it themes whatever you nest. For sparkline-style decorative trends consider just rendering a small SVG line directly; ChartContainer is overkill for non-interactive ornament.
 composes_with: [Card (chart-in-a-card pattern), Tabs (multi-metric switcher), Recharts components (Bar, Line, Area, Pie, Radar from "recharts")]
-aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart]
+aliases: [chart, charts, graph, bar chart, line chart, area chart, recharts, analytics chart, swift chart, swiftui chart, victory chart, victory native]
 ---
 
 ```jsx

package/components/ui/checkbox.md

@@ -9,6 +9,7 @@ props:
   - id?: string — bind a Label's htmlFor to this
 when_to_use: Binary on/off tied to a list (select multiple, agree to terms). Single on/off that controls a setting is better with Switch.
 composes_with: [Label (via htmlFor), Card, Form rows, Table (for row selection)]
+aliases: [checkbox, tickbox, tick box, check, multi-select item]
 ---
 
 ```jsx

package/components/ui/code.md

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

package/components/ui/collapsible.md

@@ -10,7 +10,7 @@ props:
   - CollapsibleContent: children: React.ReactNode — the content that animates in/out
 when_to_use: A single show/hide reveal — "Show advanced settings" rows, expandable inline help, "More details" sections inside cards. For multiple rows of expandable content where one-at-a-time matters, reach for Accordion. For a separate panel that floats above content, use Popover.
 composes_with: [Button (as the trigger, asChild), Card (expandable settings group), Row (header + chevron)]
-aliases: [collapsible, expand, show more, disclosure, advanced settings]
+aliases: [collapsible, expand, show more, disclosure, advanced settings, disclosure group, expandable section, expandable view, show hide]
 ---
 
 ```jsx

package/components/ui/command.md

@@ -16,7 +16,7 @@ props:
   - CommandDialog: open, onOpenChange — when you want the command palette mounted in a modal (cmd+k pattern)
 when_to_use: A searchable list of actions or destinations — global ⌘K palettes, "jump to" inputs, account switchers with filter. Wrap in CommandDialog when it should pop over the entire app on a hotkey. For straight forms with filter, prefer a Select with a search input. For free-text autocomplete tied to a single value, prefer Combobox built on Popover + Command.
 composes_with: [Dialog (CommandDialog wraps it), Popover (inline combobox), Tooltip]
-aliases: [command palette, command menu, cmd k, quick switcher, action menu]
+aliases: [command palette, command menu, cmd k, quick switcher, action menu, spotlight, spotlight search, quick open, fuzzy finder]
 ---
 
 ```jsx

package/components/ui/date-picker.md

@@ -17,7 +17,7 @@ props:
 when_to_use: Any date or date-range entry. Use DatePicker for a single date (DOB, due date, booking). Use DateRangePicker for a span (report period, stay dates, filter window). Prefer these over <Input type="date"> — consistent theming, keyboard nav, a11y, and no browser-native UI drift.
 composes_with: [Label, Form, Card (in CardContent), Button (form submit)]
 subcomponents: [DateRangePicker]
-aliases: [datepicker, calendar input, date field, date range]
+aliases: [datepicker, calendar input, date field, date range, datepickerios, react native date picker, calendar input field, date field control]
 ---
 
 ```jsx