@gradeui/ui 3.0.0 → 3.2.0

package/components/ui/button.md

@@ -4,12 +4,13 @@ import: "@gradeui/ui"
 variants: [default, destructive, outline, secondary, ghost, link, raised]
 sizes: [sm, md, lg, icon]
 props:
-  - variant? (default | destructive | outline | secondary | ghost | link | raised)
+  - variant? (default | destructive | outline | secondary | ghost | link | raised) — `raised` here is a back-compat alias (the raised TRAIT on a neutral key surface); prefer the `raised` prop
+  - raised?: boolean — presence TRAIT: tactile elevation (bevel + drop + hover glow + pressed sink) layered onto ANY variant — raised primary, raised outline, etc. Glow tone reads --btn-glow → --accent-glow → --selected-glow; override per-button via style={{ "--btn-glow": "var(--warning)" }}
   - 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, 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.
+when_to_use: Any clickable action. Use size="icon" for square icon-only buttons, variant="link" for inline links that should look like Button, the `raised` prop for high-commitment / weighty actions where the chrome can afford a tactile "physical key" treatment (composes with any variant; variant="raised" remains the neutral-key alias). 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]
 ---
@@ -32,16 +33,19 @@ aliases: [button, push button, plain button, bordered button, destructive button
 ```
 
 ```jsx
-// Raised variant — tactile bevel + drop shadow + ambient hover glow.
+// Raised TRAIT — tactile bevel + drop shadow + ambient hover glow,
+// layered onto any variant (raised primary, raised outline, ...).
 // 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)" }}>
+  <Button raised>Raised primary</Button>
+  <Button variant="outline" raised>Raised outline</Button>
+  <Button raised style={{ "--btn-glow": "var(--warning)" }}>
     Iterate
   </Button>
-  <Button variant="raised" style={{ "--btn-glow": "var(--success)" }}>
+  <Button raised style={{ "--btn-glow": "var(--success)" }}>
     Ship it
   </Button>
 </Row>
@@ -51,13 +55,13 @@ aliases: [button, push button, plain button, bordered button, destructive button
 // 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>
+<Button 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">
+<Button raised className="gds-aura-ring">
   Studio is reviewing this
 </Button>
 ```

package/components/ui/combobox.md

@@ -0,0 +1,46 @@
+---
+name: Combobox
+import: "@gradeui/ui"
+props:
+  - options: { value, label, icon?, keywords?, disabled? }[] — the selectable pool
+  - value?: string | null — controlled selection (wire onValueChange)
+  - defaultValue?: string | null — uncontrolled initial selection
+  - onValueChange?: (next: string | null) => void — fired with the next value, or null when cleared
+  - placeholder?: string — trigger text when nothing is selected
+  - searchPlaceholder?: string — search-input placeholder
+  - emptyMessage?: string — shown when search returns no rows
+  - searchable?: boolean — show the search input (default true)
+  - clearable?: boolean — add a Clear row so the value can return to unset
+  - triggerVariant?: "default" | "inline" — default = form-control surface (like Select); inline = chrome-free token trigger
+  - renderValue?: (option) => ReactNode — render the selected value yourself (e.g. a Badge); falls back to icon + label
+  - hideChevron?: boolean — drop the trailing chevron (inline token look)
+  - disabled?: boolean — lock to a read-only display of the current value
+  - align?: "start" | "center" | "end" — popover alignment
+when_to_use: Single-pick searchable picker — the single-select sibling of MultiSelect and the Linear "selectable badge" pattern (status / priority / assignee). Use triggerVariant="inline" with renderValue returning a Badge to make a value read as a clickable token that opens a command menu. For multiple selection use MultiSelect; for a small fixed list with no search use Select; for free-form command palettes use Command directly. Pass disabled (driven by a permission check) to show the value without letting the user edit it.
+composes_with: [Popover, Command, Badge, Avatar, PropertyList, Table, Field]
+aliases: [combobox, single select, searchable select, picker, status picker, priority picker, assignee picker, command select, autocomplete, dropdown select, selectable badge, inline select, token select, linear combobox]
+---
+
+```jsx
+<Combobox
+  options={[
+    { value: "low", label: "Low" },
+    { value: "medium", label: "Medium" },
+    { value: "high", label: "High" },
+  ]}
+  defaultValue="low"
+  placeholder="Set priority"
+/>
+```
+
+```jsx
+// Linear-style: the value IS the trigger.
+<Combobox
+  triggerVariant="inline"
+  hideChevron
+  options={priorityOptions}
+  value={priority}
+  onValueChange={setPriority}
+  renderValue={(opt) => <Badge variant="warning-soft">{opt.label}</Badge>}
+/>
+```

package/components/ui/data-view.md

@@ -0,0 +1,59 @@
+---
+name: DataView
+import: "@gradeui/ui"
+props:
+  - data: T[] — the rows
+  - columns: { key, header, type?, options?, cell?, role?, sortable?, pinned?, width?, align?, hideable?, defaultHidden? }[] — the schema; one list drives table, cards, and grid
+  - getRowId?: (row, i) => string — defaults to row.id
+  - view? / defaultView? / onViewChange?: "table" | "cards" | "grid" — controlled or uncontrolled view
+  - views?: ("table" | "cards" | "grid")[] — allowed views; one entry = single view, no toggle
+  - activeId? / defaultActiveId? / onActiveChange?: string | null — the selected row; click emits it
+  - sorting? / defaultSorting? / onSortingChange? — TanStack SortingState
+  - columnVisibility? / defaultColumnVisibility? / onColumnVisibilityChange? — which fields show
+  - stickyHeader?: boolean — freeze the header row on scroll
+  - toolbar?: boolean — render the built-in columns menu + view toggle above the view
+  - renderCard?: (row, { active }) => ReactNode — override card / grid tiles
+  - emptyMessage?: ReactNode
+when_to_use: One dataset, drawn as a table, a list of cards, or a grid — without re-typing the TanStack boilerplate (sortable headers, flexRender, selection, view switch) on every page. Hand it data + a columns schema; columns declare a `type` (badge/tags/number/currency/percent/date/boolean/url/text) that DataView renders, with a `cell` override for bespoke cells (avatars, relations). The view toggle can live anywhere — `useDataView()` holds the state so a `<DataViewToggle>` or `<DataViewColumns>` in a page header drives a `<DataView>` lower down. Mark a column `pinned="left"` (with a `width`) for a fixed column and `stickyHeader` to freeze the header. For a single record's fields use PropertyList; for the raw table primitive use Table.
+composes_with: [Table, Card, Badge, Avatar, ToggleGroup, DropdownMenu, PropertyList, Combobox]
+aliases: [data view, data table, datatable, data grid, dataview, table view, card view, grid view, list view, gallery, records list, master list, tanstack table, sortable table, column visibility, pinned column, frozen column, sticky header, view switcher]
+---
+
+```jsx
+const dv = useDataView({ defaultView: "table", defaultActiveId: rows[0].id });
+
+// The toggle / columns menu can live anywhere — they just read dv.
+<Row justify="between">
+  <h1>Alerts</h1>
+  <Row gap="sm">
+    <DataView.Columns columns={columns} visibility={dv.columnVisibility} onVisibilityChange={dv.setColumnVisibility} />
+    <DataView.Toggle value={dv.view} onChange={dv.setView} views={dv.views} />
+  </Row>
+</Row>
+
+<DataView
+  data={rows}
+  columns={columns}
+  view={dv.view}
+  activeId={dv.activeId}
+  onActiveChange={dv.setActiveId}
+  sorting={dv.sorting}
+  onSortingChange={dv.setSorting}
+  columnVisibility={dv.columnVisibility}
+  onColumnVisibilityChange={dv.setColumnVisibility}
+  stickyHeader
+/>
+```
+
+```jsx
+// Self-contained: built-in toolbar, single column pinned, table only.
+<DataView
+  data={rows}
+  toolbar
+  columns={[
+    { key: "name", header: "Name", role: "title", pinned: "left", width: 220 },
+    { key: "status", header: "Status", type: "badge", options: statusOptions, sortable: true },
+    { key: "arr", header: "ARR", type: "currency", align: "end", sortable: true },
+  ]}
+/>
+```

package/components/ui/dropdown-menu.md

@@ -13,6 +13,7 @@ props:
   - 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
+  - DropdownMenuSub: open?, defaultOpen?, onOpenChange? — nested-menu open state (Radix passthrough); pass `open` to compose a pre-opened submenu in static screens and captures
   - 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)]

package/components/ui/logo.md

@@ -3,12 +3,14 @@ name: Logo
 import: "@gradeui/ui"
 subcomponents: []
 props:
-  - sources?: LogoSources — artwork keyed by lockup then appearance:
-      { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }.
-      Each slot is any node (inline <svg>, <img>, component). OMIT ENTIRELY
-      and the GRADE MARK renders (the square G-arrow, painted with
-      currentColor so it sits correctly on any surface). A bare <Logo /> is
-      always correct branding.
+  - sources?: LogoSources — artwork keyed by lockup then appearance: { square?: { light?, dark?, mono? }, horizontal?: {...}, icon?: {...} }. Each slot is any node (inline <svg>, <img>, component). OMIT ENTIRELY and the GRADE MARK renders (the square G-arrow, painted with currentColor so it sits correctly on any surface). A bare <Logo /> is always correct branding.
+  - size? ("sm" | "md" | "lg" | "xl") — height of the mark: 20 / 28 / 40 / 56px (a raw pixel number also works). Width is intrinsic (square/icon 1:1, horizontal keeps its ratio). Default "md"; use "sm" in dense rails and toolbars.
+  - lockup? ("square" | "horizontal" | "icon") — which shape to show; falls back to the next-best available artwork. Default "horizontal".
+  - mode? ("light" | "dark") — the background the logo SITS ON, selecting light/dark artwork. Explicit, not theme-coupled. Default "light".
+  - mono?: boolean — render the single-colour treatment; inherits currentColor from the parent. Default false.
+  - label?: string — accessible name (aria-label + role="img"); pair with decorative when the brand name is already beside it.
+  - decorative?: boolean — aria-hidden, no role; use when text nearby names the brand.
+  - href?: string — renders the logo as a link (logo-links-home).
   - lockup?: "square" | "horizontal" | "icon" (default "horizontal")
   - mode?: "light" | "dark" (default "light") — the background the logo sits on
   - mono?: boolean (default false) — use the single-colour artwork (inherits currentColor)

package/components/ui/map.md

@@ -10,7 +10,10 @@ props:
   - Map: bounds — `[[swLng, swLat], [neLng, neLat]]`. When set, takes precedence over center+zoom.
   - Map: appearance — "light" | "dark" | "satellite" | "auto" (default "auto", follows GradeThemeProvider mode).
   - Map: hoveredId — controlled string id, pairs with onHoveredIdChange. The matching MapMarker gets `data-gds-state="hovered"` automatically. This is how you build list ↔ map two-way sync.
+  - Map: onHoveredIdChange — `(id: string | null) => void`. The other half of the controlled hover pair: fires when the pointer enters/leaves a marker so the sibling list can highlight in step. Without this entry in the contract, screens using the documented two-way sync fail save validation.
   - Map: interactive — false freezes pan/zoom, useful for static cards.
+  - Map: tools — "auto" (default, zoom buttons follow `interactive`) | "zoom" (force zoom buttons) | "none" (chrome-free map; attribution always stays — license). One vocabulary across all providers.
+  - Map: toolsPosition — "top-left" (default) | "top-right" | "bottom-left" | "bottom-right". Corner the tools dock to; use when a search bar or legend sits over the default corner.
   - Map: onLoad(handle) / onError(error) — handle exposes flyTo, panTo, fitBounds, getCenter, getZoom, getBounds, instance.
   - Map: tilerKey? — MapLibre only (provider="maplibre"). Optional everywhere: omit on `gradeui.com`/`localhost` and the referrer-locked demo key is used; set it only when embedding off-domain. The contract never requires it.
   - Map: accessToken? — Mapbox only. Pass it whenever provider="mapbox" — the component itself enforces this at runtime (throws a clear `provider="mapbox" requires an accessToken prop` error via onError if missing). It is OPTIONAL in the contract on purpose, so the validator never demands it from maplibre/google maps.
@@ -87,3 +90,9 @@ ANTI-PATTERNS — don't do these:
 - DO NOT render >500 markers without clustering. The component warns in dev. For larger datasets, drop to `.instance` and use the provider's clustering layer.
 
 Markers are DOM — children inherit `--gds-*` tokens. Drop a `<Card>`, `<Badge>`, `<Avatar>`, or anything else inside `<MapMarker>` and it themes correctly.
+
+Stacking inside a marker follows normal DOM order on every provider — you do NOT need `z-index` hacks to layer content (e.g. a count label sitting on top of an inline pin-shield `<svg>`). The DS neutralizes Leaflet's vendor rule that sets `z-index: 200` on map `<svg>` elements (via `[data-gds-part="map-marker-content"] svg { z-index: auto }` in `globals.css`); without it, an inline SVG would paint above later siblings on Leaflet (the default provider) but not on Mapbox/MapLibre/Google, making the same marker markup look provider-dependent. If you nest an inline SVG behind text in a marker, just rely on source order.
+
+For a floating text label over busy tiles, add the `gds-map-label` class — it applies a mode-aware halo (`--gds-map-label-halo`: white stroke on light tiles, near-black on dark) so the label never washes out. Don't hard-code a white `-webkit-text-stroke`.
+
+Note: `<Map>` carries no border-radius or border of its own — it's an unopinionated primitive (the container clips with `overflow: hidden`). Round or frame it from the call site with `className` (e.g. `rounded-xl border`).

package/components/ui/media-surface.md

@@ -8,6 +8,7 @@ props:
   - loading?: boolean — renders the muted skeleton overlay
   - hint?: "album" | "portrait" | "landscape" | "poster" | "product" | "food" | "video" | "audio" | "embed" | "3d" | "generic" (default "generic") — picks the placeholder glyph + the default aspect + the future generation provider
   - alt?: string — becomes the eventual `<img alt>`; also drives the placeholder caption and small-tier initials
+  - instanceId?: string — stable per-instance id stamped as `data-gds-instance-id`. Use when rendering MediaSurfaces from a data array (`.map(item => <MediaSurface instanceId={item.id} …/>)`): it's how Studio's selection + Fill flows tell one card apart from its siblings and patch only that entry's data
   - source?: { kind, …per-kind fields } — structured metadata for the generation pipeline. Shapes per kind — album: { artist, title, year? } · poster: { title, year? } · portrait: { name?, role? } · landscape: { location?, mood? } · product: { name?, brand? } · food: { dish?, cuisine? } · generic: { prompt } · video/audio/embed/3d: no fields
   - src?: string — when set, renders an `<img>` filling the slot via object-cover; the wrapper keeps its chrome
   - glyph?: ReactNode — per-instance override of the hint-derived placeholder glyph (escape hatch for unusual slots)

package/components/ui/property-list.md

@@ -0,0 +1,43 @@
+---
+name: PropertyList
+import: "@gradeui/ui"
+props:
+  - layout?: "row" | "stack" — row (default): label column beside value; stack: label above value for narrow panels
+  - density?: "compact" | "default" | "relaxed" — row rhythm
+  - align?: "start" | "center" — default vertical alignment of label vs value; use start when values wrap (tag groups, multi-line)
+  - divider?: boolean — hairline rule between rows
+  - labelWidth?: string — override the label column width (any CSS length); sets --gds-property-list-label-width
+  - children: PropertyList.Row[]
+when_to_use: Read-only display of the properties of a SINGLE item — detail panels, inspectors, "about this" cards, order/record summaries. It is a Table row transposed (schema vertical, one record). The value side is a polymorphic slot, so the same renderers that fill a Table cell (text, Badge, tag group, Avatar stack, date, link) drop straight into a row. For an EDITABLE field (label + control) use Field instead; a panel that flips between read and edit swaps a PropertyList for a stack of Fields.
+composes_with: [Badge, Avatar, Table, Field, Separator, Card]
+aliases: [property list, properties, property panel, description list, definition list, detail list, key value, key-value, data list, field list, attributes, metadata list, record summary, detail panel, inspector fields, spec list]
+---
+
+```jsx
+<PropertyList>
+  <PropertyList.Row label="Status" icon={<Activity />}>
+    <Badge variant="warning-soft">Low</Badge>
+  </PropertyList.Row>
+  <PropertyList.Row label="Published">2026-06-18</PropertyList.Row>
+  <PropertyList.Row label="Owner">
+    <Avatar className="h-5 w-5"><AvatarFallback>EO</AvatarFallback></Avatar>
+  </PropertyList.Row>
+</PropertyList>
+```
+
+```jsx
+<PropertyList density="compact" divider align="start">
+  <PropertyList.Row label="Topics">
+    <Row gap="xs" wrap>
+      <Badge variant="secondary">Pricing</Badge>
+      <Badge variant="secondary">Onboarding</Badge>
+    </Row>
+  </PropertyList.Row>
+  <PropertyList.Row label="Business profiles">
+    <Row gap="xs" wrap>
+      <Badge variant="outline">Acme</Badge>
+      <Badge variant="outline">Kite</Badge>
+    </Row>
+  </PropertyList.Row>
+</PropertyList>
+```

package/components/ui/sidebar.md

@@ -11,7 +11,8 @@ props:
   - SidebarHeader: any children — brand / logo / org switcher; hides nothing when collapsed (centred)
   - SidebarContent: any children — scrollable body
   - SidebarFooter: any children — user block, settings link, pinned chrome
-  - SidebarSection: title?: ReactNode — group label; **uppercase tracking-wide muted** styling auto-applied (Notion / Linear / Slack-style "GAMES", "FAVORITES", "WORKSPACE" headers); hidden when sidebar is collapsed
+  - SidebarSection: title?: ReactNode — group label, tracking-wide muted styling; hidden when sidebar is collapsed. CASE: static (non-collapsible) headers historically render UPPERCASE (Notion / Linear / Slack-style "GAMES", "FAVORITES"); collapsible headers render the authored case. Control it explicitly with titleTransform.
+  - SidebarSection: titleTransform? ("uppercase" | "none") — title casing for BOTH header variants. "none" renders the authored case (sentence-case headers like a "Recents" list); "uppercase" forces the shouty group label. Unset = the per-variant legacy default above.
   - SidebarSection: icon?: ReactNode — optional icon beside the title
   - SidebarSection: trailing?: ReactNode — **action(s) on the right edge of the header** — the canonical "+" / "..." slot (Notion's "+ Add page" next to Pages, Linear's "+" next to Favorites, Slack's "+" next to Channels). Pointer events isolated so a Button here doesn't toggle collapse.
   - SidebarSection: collapsible?: boolean — title acts as expand/collapse trigger with a **chevron indicator** (default true). Set `false` for a static, non-clickable header.

package/components/ui/swatch.md

@@ -0,0 +1,88 @@
+---
+name: Swatch
+import: "@gradeui/ui"
+subcomponents: [SwatchGroup]
+sizes: [xs, sm, md, lg, xl]
+props:
+  - color?: string — any raw CSS colour (`#1f6feb`, `oklch(...)`, `rgb(...)`, or `var(--x)`). Takes precedence over `token`. Use for one-off or external colours.
+  - token?: string — a Grade colour token NAME with no `--` and no `oklch()` wrap; resolved internally to `oklch(var(--<token>))`. THE design-system path — e.g. `token="brand-3"`, `token="primary"`, `token="chart-2"`. Re-voices live when the theme changes.
+  - size? (xs | sm | md | lg | xl) — t-shirt scale, 20px → 56px; default md (32px). Prefer over h-*/w-* utilities.
+  - shape? (square | rounded | circle) — default rounded (rides `--radius`); circle for dot pickers; square for a hard tile.
+  - selected?: boolean — draws the shared selection ring (`--selected`). For palette / accent pickers.
+  - onSelect?: () => void — makes the swatch a pickable <button> (adds aria-pressed, focus ring, hover lift). Omit for a static display chip.
+  - onColorChange?: (value: string) => void — makes the swatch an editable colour well: hosts a native `<input type="color">` (the OS picker) behind the DS chip and fires with the new `#rrggbb`. Presentation stays the chip, interaction stays native. Use for inspector / control-panel colour fields instead of styling a raw colour input. Takes precedence over `onSelect`.
+  - label?: ReactNode — caption rendered beneath the chip; also becomes the accessible name + tooltip.
+  - SwatchGroup: layout? (row | stack) — `row` (default) spaces chips out; `stack` overlaps them into a coin-stack (the theme-picker / "key colours" treatment, where each chip's ring reads as the separating edge).
+  - SwatchGroup: size? / shape? — cascade to every child Swatch so a strip stays consistent without repeating the prop.
+  - SwatchGroup: gap? (xs | sm | md | lg) — spacing between chips in `row` layout; default sm.
+when_to_use: Showing a colour as a small chip — brand-pop strips, palette / accent pickers, theme previews, token galleries, "pick a colour" rows. Reach for `token` to bind to a live theme variable; `color` for raw values. A transparency checkerboard sits behind the fill so semi-transparent values read honestly.
+composes_with: [Row (strip of swatches), Stack, Grid (palette wall), Field (as a colour-picker trailing slot), Card (in a theme-preview), RadioGroup (selectable accent set), Label]
+aliases: [colour swatch, color swatch, colour chip, color chip, palette swatch, token swatch, brand pop, accent swatch, colour tile, color tile, paint chip, react native colour swatch]
+notes: |
+  Anti-patterns to avoid:
+
+  - DO NOT hand-roll a colour chip as a bare `<div className="h-10 w-10 rounded">`
+    with an inline `style={{ background: ... }}`. That is exactly what
+    <Swatch> is — use it so the chip is selectable in Studio, sizes on
+    tokens, and gets the transparency checkerboard + selection ring for free.
+  - DO NOT wrap a token in oklch() yourself for the `token` prop —
+    pass the bare name. `token="brand-3"`, NOT `token="oklch(var(--brand-3))"`.
+    (If you already have a wrapped string, pass it as `color` instead.)
+  - DO NOT size with h-*/w-* utilities — use `size` so the scale stays on
+    the t-shirt tokens.
+  - DO NOT use Swatch for an avatar, status dot, or icon background. It is
+    specifically a COLOUR specimen. A status dot is a tiny Badge/indicator;
+    a person is an Avatar.
+---
+
+```jsx
+// Brand-pop strip — eight live theme accents.
+<SwatchGroup size="lg">
+  {[1, 2, 3, 4, 5, 6, 7, 8].map((n) => (
+    <Swatch key={n} token={`brand-${n}`} />
+  ))}
+</SwatchGroup>
+```
+
+```jsx
+// Theme-picker "key colours" — overlapping coin-stack of circles.
+<SwatchGroup layout="stack" shape="circle" size="md">
+  <Swatch token="background" />
+  <Swatch token="muted" />
+  <Swatch token="primary" />
+  <Swatch token="accent" />
+</SwatchGroup>
+```
+
+```jsx
+// Captioned token chips.
+<Row gap="md" wrap>
+  <Swatch token="primary" label="Primary" />
+  <Swatch token="accent" label="Accent" />
+  <Swatch token="muted" label="Muted" />
+</Row>
+```
+
+```jsx
+// Pickable accent set — selection ring + button semantics.
+<Row gap="sm">
+  {["brand-1", "brand-2", "brand-3", "brand-4"].map((t) => (
+    <Swatch
+      key={t}
+      token={t}
+      shape="circle"
+      selected={t === selectedToken}
+      onSelect={() => setSelectedToken(t)}
+    />
+  ))}
+</Row>
+```
+
+```jsx
+// Raw colour, including a semi-transparent value over the checkerboard.
+<Row gap="sm">
+  <Swatch color="#1f6feb" />
+  <Swatch color="oklch(0.7 0.18 30)" />
+  <Swatch color="rgb(16 185 129 / 0.4)" />
+</Row>
+```