@psnext/design-system 2.3.0 → 2.5.0

package/DESIGN.md

@@ -201,6 +201,21 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `flipIcon` — moves leading icon to trailing edge (default `false`).
 - **Notes**: `role="alert"`; compose `AlertContent` (title+description) with a leading `<svg>` and optional `AlertAction`. Not dismissible (use InfoBanner for that).
 
+<!-- variant-facts:Alert:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | fill | text | border | hover fill | tell |
+|---|---|---|---|---|---|---|
+| `default`\* | inline contextual notice inside the content flow | #ffffff → #111827 | #111827 → #f3f4f6 | — | — | white card with icon, neutral text |
+| `destructive` | inline error notice tied to nearby content | #ffffff → #111827 | #bc0126 → #f699ac | — | — | red text on a white card (not a red band) |
+
+Confusable: Alert vs InfoBanner vs toast → Alert = static notice inline in the content flow; InfoBanner = full-width severity band at page/section level; toast (sonner) = transient overlay.
+
+<!-- variant-facts:Alert:end -->
+
 ### AlertDialog
 - **Exports**: AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogMedia, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger
 - **Variants**: AlertDialogContent `size: default* | large`; AlertDialogAction `variant: default* | destructive`
@@ -221,6 +236,30 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `asChild` — render child element via Radix Slot (default `false`).
 - **Notes**: Renders `<span>` by default; `ai` variant is a gradient ring with brand label.
 
+<!-- variant-facts:Badge:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | fill | text | border | hover fill | tell |
+|---|---|---|---|---|---|---|
+| `default`\* | high-emphasis label or count (new, selected filter, unread) | #111827 → #ffffff | #f3f4f6 → #111827 | hairline | — | the only filled high-contrast badge |
+| `secondary` | neutral metadata label (category, tag, version) | #e5e7eb → #4b5563 | #374151 → #e5e7eb | hairline | — | quiet gray fill |
+| `destructive` | error / blocking status | #fde6ea → #6c0016 | #bc0126 → #f699ac | hairline | — | red-tint fill + red text |
+| `outline` | neutral label on busy/colored/glass surfaces | rgb(255 255 255 / 0.1) → rgb(255 255 255 / 0.05) | #111827 → #f3f4f6 | #e5e7eb → #374151 | — | visible border, translucent fill |
+| `ghost` | quietest label; inline counts | rgb(255 255 255 / 0.0001) → rgb(255 255 255 / 0.0001) | #111827 → #f3f4f6 | hairline | — | no visible fill — just padded text |
+| `success` | positive status (done, active, healthy) | #ecfccb → #365314 | #4d7c0f → #bef264 | hairline | — | green tint |
+| `warning` | caution status (pending, degraded) | #ffedd5 → #431407 | #c2410c → #fdba74 | hairline | — | orange tint |
+| `info` | informational status (beta, new feature) | #e0f2fe → #0c4a6e | #0369a1 → #7dd3fc | hairline | — | blue tint |
+| `ai` | AI-generated / AI-related markers only | — | #e90130 → #e90130 | — | — | gradient border, brand-colored text |
+
+Confusable: Severity tints (`info`/`success`/`warning`/`destructive`) are for STATUS; `default`/`secondary` are for plain labels — don't color a neutral tag. `outline` vs `ghost` → outline keeps a visible border (busy/colored surfaces); ghost is text-only quietness.
+
+**shape**: `default`\* 8px radius · `round` pill
+
+<!-- variant-facts:Badge:end -->
+
 ### Breadcrumb
 - **Exports**: Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis
 - **Custom props**: BreadcrumbLink `asChild` — render passed child (e.g. router Link) instead of `<a>`.
@@ -232,12 +271,45 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `asChild` — Radix Slot composition (default `false`); `loading` — show Spinner + disable (default `false`).
 - **Notes**: forwardRef (usable as overlay trigger via `asChild`); spinner only rendered when not `asChild`.
 
+<!-- variant-facts:Button:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | fill | text | border | hover fill | tell |
+|---|---|---|---|---|---|---|
+| `default`\* | THE one main action of a view (submit, save, primary CTA) | #111827 → #ffffff | #f3f4f6 → #111827 | — | #374151 → #d1d5db | the only filled high-contrast button |
+| `destructive` | irreversible action (delete, remove) | #fde6ea → #6c0016 | #bc0126 → #f699ac | — | #fde6ea @80% → #6c0016 @80% | red fill |
+| `outline` | secondary action on busy/colored/glass surfaces | rgb(255 255 255 / 0.1) → rgb(255 255 255 / 0.05) | #111827 → #f3f4f6 | #d1d5db → #374151 | rgb(31 40 50 / 0.0333) → rgb(255 255 255 / 0.1) | has a visible border |
+| `secondary` | secondary action next to a primary | #ffffff → #111827 | #111827 → #f3f4f6 | — | #f9fafb → #111827 | filled but low-contrast, no border |
+| `ghost` | low-emphasis: toolbars, icon rows, cancel | rgb(255 255 255 / 0.0001) → rgb(255 255 255 / 0.0001) | #111827 → #f3f4f6 | — | rgb(31 40 50 / 0.05) → rgb(255 255 255 / 0.1) | invisible at rest — only the label/icon shows |
+| `link` | inline navigation styled as text | — | #111827 → #f3f4f6 | — | — | no box at all |
+| `ai` | AI-powered affordances only | #ffffff → #111827 | #bc0126 → #fbccd6 | — | — | animated gradient border, brand-colored label |
+| `destructive-ghost` | destructive icon buttons / low-emphasis delete | rgb(255 255 255 / 0.0001) → rgb(255 255 255 / 0.0001) | #bc0126 → #f699ac | — | #fde6ea → #6c0016 | red text without a red fill |
+
+Confusable: `outline` vs `ghost` → outline has a border (survives on photos / colored bg); ghost is borderless (dense toolbars). `secondary` vs `outline` → secondary is a solid gray fill; outline is translucent with a border.
+
+**size**: `xs` 30px · `sm` 36px · `default`\* 40px · `lg` 44px · `xl` 48px · `icon` 36px square · `icon-xs` 24px square · `icon-sm` 32px square · `icon-lg` 40px square · `icon-xl` 48px square
+
+**shape**: `default`\* pill · `square` 6px radius
+
+<!-- variant-facts:Button:end -->
+
 ### ButtonGroup
 - **Exports**: ButtonGroup, ButtonGroupSeparator, ButtonGroupText, buttonGroupVariants
 - **Variants**: ButtonGroup `orientation: horizontal* | vertical`
 - **Custom props**: ButtonGroupText `asChild` (default `false`).
 - **Notes**: Merges child borders/corners into one attached unit; `role="group"`.
 
+<!-- variant-facts:ButtonGroup:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**orientation**: `horizontal`\* · `vertical`
+
+<!-- variant-facts:ButtonGroup:end -->
+
 ### Calendar
 - **Exports**: Calendar, CalendarDayButton
 - **Custom props**: `buttonVariant` — Button variant for prev/next nav (default `outline`); `showOutsideDays` (default `true`); `captionLayout` (default `label`, `dropdown` for month/year selects).
@@ -248,6 +320,25 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Variants**: Card `variant: default* | glass | brand | ai | inverted`, `tint: subtle | light* | medium | heavy` (glass only); CardHeader `align: start | center* | end`; CardFooter `tone: default* | brand | muted | card`
 - **Notes**: `tint` applies only to `variant="glass"`; footer `brand`/`muted`/`card` render a full-width band — pair with `<Card className="overflow-hidden">`. Card defaults to `justify-between` vertical distribution (overridable via className).
 
+<!-- HAND-WRITTEN choosing table (compoundVariants — not generated; keep in sync with cardVariants). -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | looks like | tell |
+|---|---|---|---|
+| `default`\* | standard content container on plain page chrome | opaque `#ffffff → #111827`, hairline border, shadow-sm | solid card with border + shadow |
+| `glass` | card floating over `PageBackground` / imagery | translucent white → translucent dark-navy, backdrop-blurred; `tint` sets opacity | see-through + blurred, borderless |
+| `brand` | promotional / product-branded surface | left→right brand gradient (`--theme-brand-700` → `-500`), white text — does **not** flip in dark mode | colorful gradient fill |
+| `ai` | AI feature surface | normal surface wrapped in the gradient AI ring | gradient border, normal inside |
+| `inverted` | contrast block (CTA band, spotlight) | dark card in light mode `#111827`, light card in dark `#ffffff` | opposite of the page |
+
+**tint** (glass only): `subtle` 20% · `light`\* 40% · `medium` 40% (no 50% token yet) · `heavy` 60%.
+
+Confusable: `default` vs `glass` → default is opaque with border+shadow; glass is
+translucent+blurred with no border, and needs a textured layer behind it
+(`PageBackground`) to read as glass.
+
 ### Carousel
 - **Exports**: CarouselApi (type), Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
 - **Custom props**: `opts` (Embla options), `plugins`, `orientation: horizontal* | vertical`, `setApi` (receives Embla API).
@@ -269,6 +360,12 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `nodes` (hierarchical `{id, label, children}` data); `value` (controlled selected ids, required); `onValueChange`; `defaultExpandedIds`.
 - **Notes**: Controlled only; tri-state propagation across subtrees; `role="tree"`. This is the DS answer to hierarchical multi-select.
 
+### CircularProgress
+- **Exports**: CircularProgress, CircularProgressProps (type), CircularProgressVariant (type)
+- **Variants**: `variant: default* | brand | success | warning | info | destructive | analyzing | ingesting` (indicator stroke); `trackVariant` — same scale for the track (defaults to `variant`, rendered at /20 opacity)
+- **Custom props**: `value` (omit → indeterminate spinning arc), `min`/`max` (aria/value normalization, default 0/100), `size` (diameter px, default `48`), `strokeWidth` (px, default `4`), `progressColor`/`trackColor` (explicit CSS colours, override the variant classes), `label` (centered node), `showValueLabel` (centered `%` text when determinate, default `false`), `indeterminateLabel` (a11y text for loading state, default `Loading`).
+- **Notes**: `role="progressbar"` with normalized aria values and a polite live region. Determinate animates stroke-dashoffset (500ms, motion-reduce respected); indeterminate spins a 35% arc (`motion-safe`). Circular counterpart to the linear `Progress` bar.
+
 ### Collapsible
 - **Exports**: Collapsible, CollapsibleTrigger, CollapsibleContent
 - **Notes**: Radix Collapsible passthrough (controlled/uncontrolled via `open`/`defaultOpen`); no styling applied.
@@ -290,6 +387,20 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `value` (balance, required); `lowThreshold` (default `200`); `icon` override; `format` override (default floor+thousands).
 - **Notes**: Color escalates as balance drops (neutral → amber ≤ threshold → red ≤ 0).
 
+<!-- variant-facts:Credits:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | rgb(255 255 255 / 0.1) → rgb(255 255 255 / 0.05) | #111827 → #f3f4f6 | #e5e7eb → #374151 | — |
+| `warning` | #ffedd5 → #431407 | #c2410c → #fdba74 | hairline | — |
+| `critical` | #fde6ea → #6c0016 | #bc0126 → #f699ac | hairline | — |
+
+<!-- variant-facts:Credits:end -->
+
 ### Dialog
 - **Exports**: Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger
 - **Variants**: DialogContent `size: sm | default* | lg | xl`
@@ -298,7 +409,8 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 
 ### Drawer
 - **Exports**: Drawer, DrawerPortal, DrawerOverlay, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerFooter, DrawerTitle, DrawerDescription
-- **Notes**: Built on `vaul`; slide `direction` (top/bottom/left/right) set on the `Drawer` root. `DrawerContent` self-portals + renders overlay; bottom drawer shows a drag handle.
+- **Variants**: DrawerContent `size: small | default* | medium | large | extraLarge`
+- **Notes**: Built on `vaul`; slide `direction` (top/bottom/left/right) set on the `Drawer` root. `DrawerContent` self-portals + renders overlay; bottom drawer shows a drag handle. `size` scales the panel per direction — left/right width caps: `small` xs (20rem) · `default` sm (24rem) · `medium` md (28rem) · `large` lg (32rem) · `extraLarge` 2xl (42rem); top/bottom max-heights: 60 / 80 / 85 / 90 / 95vh. Prefer `size` over a width/height `className` override.
 
 ### DropdownMenu
 - **Exports**: DropdownMenu, DropdownMenuPortal, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuLabel, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent
@@ -317,6 +429,11 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: FieldError accepts `errors` array (deduped, listed when >1) or `children`; FieldSeparator optional centered label.
 - **Notes**: Layout primitives for forms (non-react-hook-form); `FieldError` is `role="alert"` and renders nothing when empty.
 
+### FileUpload
+- **Exports**: FileUpload, FileUploadHandler (type), FileUploadItem (type), FileUploadProps (type), FileUploadStatus (type)
+- **Custom props**: `multiple` (default `false`); `accept` — native accept filter (e.g. `"image/*,.pdf"`); `maxFiles` (default unlimited when `multiple`, `1` otherwise); `maxFileSize` — bytes, oversized files rejected with a message; `validateFile` — custom validator, return a message to reject or `null` to accept; `onUpload` — async handler per accepted file, receives `{ file, signal, reportProgress }`; `onItemsChange` — fires whenever file entries change (added/progress/completed/removed); `dropzoneAriaLabel` (default `"File upload drop zone"`); `disabled`.
+- **Notes**: Click-to-browse + drag-and-drop dropzone with per-file states (`idle | uploading | success | error`), progress bars, and remove/cancel controls. Wire real uploads via `onUpload` — call `reportProgress(0–100)` as bytes stream and throw to mark the file failed; the `signal` aborts when the user cancels/removes. Validation errors (accept/size/custom/maxFiles) render in an `aria-live` list under the dropzone.
+
 ### Form
 - **Exports**: useFormField, Form, FormItem, FormLabel, FormControl, FormDescription, FormMessage, FormField
 - **Notes**: react-hook-form binding layer over the Field primitives; `Form` = RHF `FormProvider`, `FormField` wraps `Controller`. `FormControl` wires id/aria-describedby/aria-invalid via Slot; must be used within `FormField`/`FormItem`.
@@ -327,6 +444,25 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `as` — semantic element (default `h2`, independent of visual `size`).
 - **Notes**: `gradient` fills text with the brand gradient.
 
+<!-- variant-facts:Heading:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `gradient`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| gradient | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `true` | — | — | — | — |
+| `false`\* | — | #111827 → #f3f4f6 | — | — |
+
+**size**: `1` · `2`\* · `3` · `4` · `5` · `6` · `7`
+
+**weight**: `normal` · `medium` · `semibold`
+
+**align**: `left` · `center` · `right`
+
+<!-- variant-facts:Heading:end -->
+
 ### HoverCard
 - **Exports**: HoverCard, HoverCardTrigger, HoverCardContent
 - **Custom props**: HoverCardContent `align` (default `center`), `sideOffset` (default `4`).
@@ -335,8 +471,10 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 ### Icon
 - **Exports**: Icon, IconProps (type), IconName (type), ICON_NAMES
 - **Variants**: `color: default* | muted | primary | success | destructive | inverted`, `shape: square | round` (unset = bare glyph), `fill: subtle* | solid` (boxed only), `size: xs | sm | md* | lg | xl`
-- **Custom props**: `icon` (typed lucide name, required); `strokeWidth`; `label` — a11y label (sets `role="img"`, else aria-hidden).
-- **Notes**: Lazily code-splits each lucide icon; `shape` wraps the glyph in a padded box where `fill`/`color` apply.
+- **Glyph source (pass exactly one)**: `icon` — a typed lucide NAME string (`<Icon icon="search" />`), lazily code-split one chunk per icon; best for app/content icons chosen at runtime. `as` — an icon COMPONENT, lucide **or your own custom icon** (`<Icon as={Search} />`), rendered synchronously and, when un-boxed, as a bare `<svg>` so it drops into a component's direct-child `[&>svg]` slot styling; best inside components and for static/custom icons.
+- **Custom props**: `strokeWidth`; `label` — a11y label (sets `role="img"`, else aria-hidden).
+- **Color**: `color="default"` **inherits** the surrounding text color (currentColor — deliberately no `text-*` class, so guarded slot rules like Select's `[&_svg:not([class*='text-'])]` still apply) — a bare icon on a Button matches the label instead of forcing a dark glyph on a dark surface. On normal chrome it still resolves to `text-primary-txt` (via `<body>`). Override with a semantic `color` or a `text-*` className.
+- **Notes**: `shape` wraps the glyph in a padded box where `fill`/`color` apply. Existing `icon="name"` usage is unchanged — `as` is purely additive.
 
 ### InfoBanner
 - **Exports**: InfoBanner, infoBannerVariants, InfoBannerProps (type)
@@ -344,11 +482,48 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `title` (required); `description`; `icon` override; `dismissible` (default `true`); `visible` (controlled); `onDismiss`.
 - **Notes**: `role="status"`; dismissible — distinct from the non-dismissible Alert.
 
+<!-- variant-facts:InfoBanner:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | fill | text | border | hover fill | tell |
+|---|---|---|---|---|---|---|
+| `info`\* | announcements, tips, FYI messaging | #e0f2fe → #0c4a6e | #0369a1 → #7dd3fc | — | — | blue band |
+| `success` | operation completed / healthy state | #ecfccb → #365314 | #4d7c0f → #bef264 | — | — | green band |
+| `warning` | caution or degraded state, action may be needed | #ffedd5 → #431407 | #c2410c → #fdba74 | — | — | orange band |
+| `error` | failure that needs attention | #fde6ea → #6c0016 | #bc0126 → #f699ac | — | — | red band |
+| `neutral` | generic notice with no severity | #f3f4f6 → #111827 | #111827 → #f3f4f6 | — | — | gray band |
+
+Confusable: InfoBanner vs Alert → banner is a full-width severity band at page/section level; Alert sits inline in the content flow.
+
+<!-- variant-facts:InfoBanner:end -->
+
 ### Input
 - **Exports**: Input, inputVariants
 - **Variants**: `variant: default* | ai`, `size: xs | sm | default* | lg`, `shape: default* (12px) | round (pill)`
 - **Notes**: Native `<input>` passthrough; `ai` swaps border for the AI gradient; `aria-invalid` triggers the error ring.
 
+<!-- variant-facts:Input:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | use when | fill | text | border | hover fill | tell |
+|---|---|---|---|---|---|---|
+| `default`\* | any standard text entry | #ffffff → #1f2832 | — | #e5e7eb → #374151 | — | white fill, gray hairline border |
+| `ai` | AI prompt / ask-anything fields only | — | — | — | — | gradient AI border |
+
+Confusable: `ai` is reserved for AI prompt fields — a normal field with AI autofill is still `default`.
+
+**size**: `xs` 24px · `sm` 32px · `default`\* 36px · `lg` 40px
+
+**shape**: `default`\* 12px radius · `round` pill
+
+<!-- variant-facts:Input:end -->
+
 ### InputGroup
 - **Exports**: InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea
 - **Variants**: InputGroup `variant: default* | ai`; InputGroupAddon `align: inline-start* | inline-end | block-start | block-end`; InputGroupButton `size: xs* | sm | icon-xs | icon-sm`
@@ -380,6 +555,22 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Variants**: `variant: default* | muted | subtle`, `underline: always* | hover`
 - **Custom props**: `asChild` — render a router link instead of `<a>` (default `false`).
 
+<!-- variant-facts:Link:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | — | #111827 @80% → #f3f4f6 @80% | — | — |
+| `muted` | — | #111827 → #f3f4f6 | — | — |
+| `subtle` | — | #111827 @80% → #f3f4f6 @80% | — | — |
+
+**underline**: `always`\* · `hover`
+
+<!-- variant-facts:Link:end -->
+
 ### Logo
 - **Exports**: Logo, LogoBrand (type), LogoVariant (type)
 - **Variants**: `variant: logo* | icon`
@@ -392,16 +583,35 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: Item/Label/SubTrigger `inset` (default `false`)
 - **Notes**: Radix Menubar; content self-portals; auto-indents plain items when checkbox/radio items present.
 
+### Mosaic
+- **Exports**: Mosaic, MosaicWindow, MosaicProps (type), MosaicWindowProps (type), and tree types re-exported from Mosaic.utils: MosaicNode, MosaicParent, MosaicKey, MosaicDirection, MosaicPath, DropZone
+- **Custom props**: `value` / `defaultValue` — the pane tree, controlled or uncontrolled (`MosaicNode<T>` = leaf id `T` or `{ direction: "row" | "column", first, second, splitPercentage? }`); `onChange` — fires with the updated tree after resize/split/remove/drag (no strict veto); `renderTile` — renders a leaf's content (required); `renderTitle` — pane toolbar title (default `String(id)`); `renderControls` — extra toolbar actions after split/remove; `createNode` — id factory for toolbar splits (required); `dragToRearrange` (default `true`); `dropZoneFraction` — edge-zone fraction 0–1 (default `0.25`); `minPaneSizePercentage` (default `10`); `emptyPlaceholder` — rendered when every pane is removed; `renamable` (default `false`) — pencil button + double-click title to rename a pane in place; `paneNames` / `defaultPaneNames` / `onPaneNamesChange` — custom pane names keyed by leaf id, controlled or uncontrolled.
+- **Notes**: Recursive tiling layout (react-mosaic-style) built on the DS Resizable panels: panes split into rows/columns, resize via draggable dividers, and rearrange by dragging a pane's title bar onto another pane's edge (splits there) or center (swaps). Every drag outcome is also reachable via each pane's keyboard-operable toolbar split/remove buttons. `useMosaic` is intentionally not exported — `MosaicWindow` is the supported extension point.
+
 ### NativeSelect
 - **Exports**: NativeSelect, nativeSelectVariants
 - **Variants**: `size: xs | sm | default* | lg`
 - **Notes**: Styled native `<select>` with chevron affordance; pass `<option>`/`<optgroup>` children; mirrors Input visuals.
 
+<!-- variant-facts:NativeSelect:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**size**: `xs` 24px · `sm` 32px · `default`\* 36px · `lg` 40px
+
+<!-- variant-facts:NativeSelect:end -->
+
 ### NavigationMenu
 - **Exports**: NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuContent, NavigationMenuTrigger, NavigationMenuLink, NavigationMenuIndicator, NavigationMenuViewport, navigationMenuTriggerStyle
 - **Custom props**: NavigationMenu `viewport` (default `true` — shared animated viewport; `false` renders content inline)
 - **Notes**: Radix NavigationMenu; `NavigationMenuLink` takes `active` to mark the current page.
 
+### NotchedCard
+- **Exports**: NotchedCard, buildNotchedCardPath, notchedCardVariants, NotchedCardProps (type), NotchedCardVariant (type)
+- **Variants**: `variant: default* | muted | glass | brand | inverted` (surface fill + inherited text colour)
+- **Custom props**: `topLeftComponent` / `topRightComponent` / `bottomLeftComponent` / `bottomRightComponent` (corner slots — each occupied corner notches the background around its content), `backgroundImage` (cover image inside the clipped surface), `backgroundImageOpacity` (default `0.8`), `radius` (px, default `16`), `notchRadius` (concave fillet px, default `12`), `notchGap` (gutter px between corner content and background edge, default `12`), `padding` (px, default `24`), `avoidNotches` (default `true` — float spacers with `shape-outside` keep flowing content wrapped around the cutouts; set `false` when `contentClassName` makes the wrapper flex/grid, floats have no effect there), `bordered` (default on for `default`/`muted`, off otherwise), `backgroundClassName` (classes for the clipped background layer — put custom `bg-*`/gradient fills here, NOT in `className`; the layer sits behind the content so hover fills need `group-hover:bg-*`, keyed off the root's `group` marker), `contentClassName`
+- **Notes**: With no corner content it renders a plain rounded rectangle (no clipping/measuring). Corner sizes are tracked with ResizeObserver, so slots can be any content — text, icons, buttons, clusters. `className` styles the root (size/placement); the surface fill lives on an inner clipped layer, hence `backgroundClassName`. Outline is an SVG stroke following the notches (`primary-border`); surface shadow is a drop-shadow filter (box-shadow would be clipped away).
+
 ### Pagination
 - **Exports**: Pagination, PaginationContent, PaginationLink, PaginationItem, PaginationPrevious, PaginationNext, PaginationEllipsis
 - **Custom props**: PaginationLink `isActive` (aria-current; default `false`), `size` (default `icon`)
@@ -416,7 +626,7 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Exports**: Progress
 - **Variants**: `variant: default* | brand | success | warning | info | destructive | analyzing | ingesting`
 - **Custom props**: `value` (omit/null → indeterminate sliding segment)
-- **Notes**: Radix Progress; variant sets both track and indicator colors.
+- **Notes**: Radix Progress; variant sets both track and indicator colors. Radial counterpart: `CircularProgress`.
 
 ### RadioGroup
 - **Exports**: RadioGroup, RadioGroupItem, RichRadioItem
@@ -447,15 +657,30 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 
 ### Sheet
 - **Exports**: Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription
-- **Variants**: SheetContent `side: top | right* | bottom | left`, `overlay: default* | dark | glass | none`
+- **Variants**: SheetContent `side: top | right* | bottom | left`, `overlay: default* | dark | glass | none`, `size: small | default* | medium | large | extraLarge`
 - **Custom props**: SheetContent `showCloseButton` (default `true`)
-- **Notes**: Radix Dialog under the hood; content self-portals with overlay; radius on the inward edge only.
+- **Notes**: Radix Dialog under the hood; content self-portals with overlay; radius on the inward edge only. `size` scales the panel per side — left/right width caps: `small` xs (20rem) · `default` sm (24rem) · `medium` md (28rem) · `large` lg (32rem) · `extraLarge` 2xl (42rem); top/bottom heights: 40vh / auto (content) / 60vh / 80vh / 95vh. Prefer `size` over a width/height `className` override.
 
 ### Sidebar
 - **Exports**: Sidebar, SidebarProvider, SidebarTrigger, SidebarRail, SidebarInset, SidebarInput, SidebarHeader, SidebarFooter, SidebarContent, SidebarGroup, SidebarGroupLabel, SidebarGroupAction, SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuAction, SidebarMenuBadge, SidebarMenuSkeleton, SidebarMenuSub, SidebarMenuSubItem, SidebarMenuSubButton, SidebarSeparator, useSidebar
 - **Variants**: Sidebar `side: left* | right`, `variant: sidebar* | floating | inset`, `collapsible: offcanvas* | icon | none`
 - **Notes**: Wrap the layout in `SidebarProvider` (owns open state, cookie persistence, and the keyboard shortcut); renders as a fixed desktop rail or a mobile Sheet. `useSidebar()` must be inside the provider. For a compact app rail prefer `NavRail`.
 
+<!-- variant-facts:Sidebar:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | — | #111827 → #f3f4f6 | — | #e5e7eb @50% → #4b5563 @50% |
+| `outline` | #ffffff → #111827 | #111827 → #f3f4f6 | — | #e5e7eb @50% → #4b5563 @50% |
+
+**size**: `default`\* 32px · `sm` 28px · `lg` 48px
+
+<!-- variant-facts:Sidebar:end -->
+
 ### Skeleton
 - **Exports**: Skeleton, SkeletonAvatar, SkeletonLine, SkeletonObject
 - **Notes**: `skeleton-shimmer` divs; presets: Avatar (size-10 round), Line (h-4 full), Object (96px block).
@@ -491,17 +716,79 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: TabsList `tabPrefix`/`tabSuffix` (nodes)
 - **Notes**: Set variant/size/orientation on the root only (shared via context). `segmented` has an animated sliding indicator; `fancy` merges the active tab into the TabsContent glass panel.
 
+<!-- HAND-WRITTEN choosing table (compoundVariants — not generated; keep in sync with tabsListVariants/tabsTriggerVariants). -->
+
+**Choosing a `variant`** — never re-skin a variant with paint classes (SKILL.md →
+"Never re-skin a variant").
+
+| variant | use when | looks like | tell |
+|---|---|---|---|
+| `line` | quiet content-section switching inside a page | plain text row; 2px underline slides beneath the active tab | underline only, no fills |
+| `pill`\* | default control-style switching | track row; active tab is a raised solid pill (`#ffffff → #111827` fill + shadow) | active tab looks like a pressed pill |
+| `segmented` | tight toggle-group of 2–5 short options | track with ONE animated indicator that slides behind triggers | single sliding thumb |
+| `fancy` | hero/login compositions on glass — tab cards that merge into the panel | translucent gradient tab cards (glass 60→20 vertical); the active card turns flat-bottomed and fuses into the glass `TabsContent` panel with concave 16px corner curves | card-shaped tabs joined to their panel |
+
+**size** — track heights (`pill`/`segmented`, horizontal): `sm` 24px · `md`\* 35px ·
+`lg` 40px. `fancy` trigger padding: `sm` 8/16px (text-sm) · `md` 12/24px (text-sm) ·
+`lg` 16/24px (text-base) — an `lg` fancy tab card runs ≈56px tall.
+
+Confusable: `pill` vs `segmented` → both are tracks, but segmented animates one
+shared indicator while pill styles the active trigger itself. `fancy` is only for
+glass compositions (needs `PageBackground` behind it); everywhere else pick one of
+the other three.
+
 ### Text
 - **Exports**: Text, textVariants, TextProps (type)
 - **Variants**: `size: large | regular* | small | mini | caption`, `weight: normal* | medium | semibold`, `variant: default* | muted | primary | destructive | success`, `font: body* | heading | mono`, `align: left | center | right`, `truncate: true`
 - **Custom props**: `as` (default `p`)
 - **Notes**: Body-copy primitive; sizes map to the paragraph type-scale tokens.
 
+<!-- variant-facts:Text:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | — | #111827 → #f3f4f6 | — | — |
+| `muted` | — | #6b7280 → #9ca3af | — | — |
+| `primary` | — | #111827 → #f3f4f6 | — | — |
+| `destructive` | — | #bc0126 → #f699ac | — | — |
+| `success` | — | #4d7c0f → #bef264 | — | — |
+
+**size**: `large` · `regular`\* · `small` · `mini` · `caption`
+
+**weight**: `normal`\* · `medium` · `semibold`
+
+**font**: `body`\* · `heading` · `mono`
+
+**align**: `left` · `center` · `right`
+
+**truncate**: `true`
+
+<!-- variant-facts:Text:end -->
+
 ### Textarea
 - **Exports**: Textarea, textareaVariants
 - **Variants**: `variant: default* | ai` (gradient border), `shape: default* (12px) | round (16px)`
 - **Notes**: Auto-grows via `field-sizing-content`; chrome matches Input; supports aria-invalid.
 
+<!-- variant-facts:Textarea:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | #ffffff → #1f2832 | — | #e5e7eb → #374151 | — |
+| `ai` | — | — | — | — |
+
+**shape**: `default`\* 12px radius · `round` 16px radius
+
+<!-- variant-facts:Textarea:end -->
+
 ### ThemeProvider
 - **Exports**: ThemeProvider, useTheme, ThemeContext, ThemeMode (type), ThemeProduct (type)
 - **Custom props**: `defaultTheme: light* | dark`, `defaultProduct: slingshot* | sustain | bodhi | psai`, `storageKey` (default `ds-theme-preferences`)
@@ -537,8 +824,8 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 
 ### Header
 - **Exports**: `Header` (wired), `HeaderBar`, `HeaderLogo`, `OrgPill`, `ProfileMenu`, `ThemeToggle`, `ProjectPicker`; hooks/data layer `useGlobalHeader`, `useHeaderCredits`, `useHeaderProject`, `getSessionToken`, `getSessionClaims`, `isSessionValid`, `buildEndpoints`, `DEFAULT_LABELS`; consts/types `TOGGLE_PROJECT_DROPDOWN_EVENT`, `GlobalHeaderState`, `ToggleProjectDropdownDetail`, `HeaderSelection`, `UseHeaderProjectResult`, `Labels`, `Fetcher`, `HeaderEndpoints`, `HeaderProps`, `ProjectNode`, `SessionClaims`
-- **Custom props** (HeaderProps): `apiBaseUrl` — studio-auth API host (required); `environmentId` — reads `{environmentId}-sessionId` cookie (required); `logoType` — ThemeProduct, defaults to active product; `logoHref` — logo link destination (defaults to the product's public site); `showOrg`/`showProjectDropdown`/`showProfile`/`showThemeSwitcher`/`showCredits` — visibility toggles (all default `false`); `pageTitle`; `feedbackUrl`; `clientId` — active org id; `_dangerouslyInjectAccessToken` — escape hatch, avoid; `onProjectChange` — fires on user pick or automatic default; `logoAddon` — node between logo and picker; `actionsStart`/`actionsEnd` — nodes at the start/end of the right-hand actions cluster; `endpoints` — per-path overrides; `fetcher` — custom fetch (default global); `staleTime` (default 5 min); `gcTime` (default 10 min).
-- **Notes**: Must render inside a `<ThemeProvider>`; owns an internal singleton QueryClient (no app setup). Auth state and user identity (email, client id) are decoded from the `{environmentId}-sessionId` JWT cookie — no `/me` call. Logged-out users see no user content; `ProjectNode` shape = `{ id, name, children: ProjectNode[], isContextOnly? }`. Project selection is per-tab (sessionStorage); explicit picks are remembered cross-tab in localStorage `lastSelectedProject`, and a tab with no valid selection auto-defaults to that (else the first selectable project) — there is no selection overlay.
+- **Custom props** (HeaderProps): `apiBaseUrl` — studio-auth API host (required); `environmentId` — reads `{environmentId}-sessionId` cookie (required); `logoType` — ThemeProduct, defaults to active product; `logoHref` — logo link destination (defaults to the product's public site); `showOrg`/`showProjectDropdown`/`showProfile`/`showThemeSwitcher`/`showCredits` — visibility toggles (all default `false`); `pageTitle`; `feedbackUrl`; `clientId` — active org id; `defaultProjectId` — auto-selected when the tab has no selection and `lastSelectedProject` is absent/invalid; `_dangerouslyInjectAccessToken` — escape hatch, avoid; `onProjectChange` — fires on user pick or automatic default; `logoAddon` — node between logo and picker; `actionsStart`/`actionsEnd` — nodes at the start/end of the right-hand actions cluster; `endpoints` — per-path overrides; `fetcher` — custom fetch (default global); `staleTime` (default 5 min); `gcTime` (default 10 min).
+- **Notes**: Must render inside a `<ThemeProvider>`; owns an internal singleton QueryClient (no app setup). Auth state and user identity (email, client id) are decoded from the `{environmentId}-sessionId` JWT cookie — no `/me` call. Logged-out users see no user content; `ProjectNode` shape = `{ id, name, children: ProjectNode[], isContextOnly? }`. Project selection is per-tab (sessionStorage); explicit picks are remembered cross-tab in localStorage `lastSelectedProject`, and a tab with no valid selection auto-defaults to that (else `defaultProjectId`, else the first selectable project) — there is no selection overlay. The paginated projects API is fetched page-by-page until exhausted and the merged tree is cached in sessionStorage keyed by client id + user id, so it is hit once per tab session per identity.
 
 ### MediaObject
 - **Exports**: `MediaObject`, `MediaObjectImage`, `MediaObjectIcon`, `MediaObjectContent`, `MediaObjectTitle`, `MediaObjectText`, `MediaObjectActions`, `MediaObjectGroup`, `mediaObjectGroupVariants`, types `MediaObjectProps`, `MediaObjectImageProps`, `MediaObjectTitleProps`, `MediaObjectGroupProps`
@@ -546,6 +833,16 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: (MediaObject) `interactive` — CSS hover lift + shadow. (MediaObjectImage) `alt` — required alt text. (MediaObjectTitle) `size` — Heading size (default `"4"`).
 - **Notes**: Radix-style compositional card; root is `<article>`, image is 16/9 cover; pure-CSS hover (no JS state).
 
+<!-- variant-facts:MediaObject:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**columns**: `1` · `2` · `3`\* · `4`
+
+**gap**: `sm` · `md` · `lg`\*
+
+<!-- variant-facts:MediaObject:end -->
+
 ### NavRail
 - **Exports**: NavRail, NavRailItem, NavRailUser, NavRailSeparator, NavRailMenu, NavRailMenuTrigger, NavRailMenuContent, NavRailMenuItem, + prop types
 - **Variants**: NavRail `mode: icon* | text | expanded | expand-on-hover`
@@ -570,6 +867,39 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Custom props**: `as` — element/component to render (default `div`).
 - **Notes**: Centered max-width column with gutters; `glass` uses `bg-glass-40-bg backdrop-blur-glass`.
 
+<!-- variant-facts:Container:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+**Choosing a `variant`** — colors are `light → dark` mode actuals. Never re-skin a
+variant with paint classes (SKILL.md → "Never re-skin a variant").
+
+| variant | fill | text | border | hover fill |
+|---|---|---|---|---|
+| `default`\* | — | — | — | — |
+| `glass` | rgb(255 255 255 / 0.4) → rgb(31 40 50 / 0.4) | — | — | — |
+
+**size**: `narrow` · `content`\* · `wide` · `full`
+
+<!-- variant-facts:Container:end -->
+
+### MultiColumn
+- **Exports**: `MultiColumn`, `MultiColumnItem`, `multiColumnVariants`, types `MultiColumnProps`, `MultiColumnItemProps`
+- **Variants** (MultiColumn): `gap`: `none` | `sm` | `md` | `lg`* | `xl`; `stackBelow`: `sm` | `md` | `lg`* | `xl` — breakpoint the grid activates at.
+- **Custom props**: `columns` (MultiColumn, required) — one CSS grid track per column (`"240px"` fixed, `"20%"` percent, `"1fr"` fractional, `"minmax(200px,1fr)"`); array length sets the column count (3, 4, 5, ...N). `order` (MultiColumnItem) — visual position via CSS `order`, independent of DOM order; also the initial position when the parent is `reorderable`. `align` (MultiColumnItem) — `start` | `center` | `end` | `stretch` (`align-self`). `id` (MultiColumnItem) — native `id`; give every item one when the parent is `reorderable` so `onReorderChange` reports stable identities.
+- **Resizable** (opt-in, default off): `resizable` renders a drag/Arrow-key handle between adjacent columns; `onColumnsChange(columns)` fires with the updated array (pass a `columns` value you update to control it, omit for internal/uncontrolled tracking); `minColumnSize` (default `"80px"`) floors how small a column can be dragged. A dragged pair freezes to explicit px; a `minmax(min,max)` column keeps its own authored bounds even after being resized (never silently discarded). Handles are keyboard-operable (`role="separator"`, Arrow Left/Right) and hidden below `stackBelow`.
+- **Reorderable** (opt-in, default off): `reorderable` renders a drag grip on every `MultiColumnItem`; drag onto another item to swap positions, or focus a grip and press Ctrl+Left/Ctrl+Right. `onReorderChange(orderedIds)` fires with the new left-to-right order of each item's `id` (falls back to a generated id with a console warning if `id` is omitted). Grips hidden below `stackBelow`.
+- **Notes**: CSS Grid (not flex) so `minmax()` and mixed fixed/%/fr tracks work in one template; `TwoColumn` stays the recommended API for the aside+main pattern. Compose `<MultiColumn columns={[...]}><MultiColumnItem/>...</MultiColumn>`; stacks to `flex flex-col` below `stackBelow`. The per-instance track list is set via the `--mc-columns` custom property (inline style) and read by a static `<bp>:grid-cols-[var(--mc-columns)]` class, so Tailwind's source scanner still sees a literal class to generate (same technique as `Sidebar`'s `w-(--sidebar-width)`). Resize math and reorder math are pure functions in `MultiColumn.utils.ts` (unit-tested); the actual browser layout resolution (`getComputedStyle`) they depend on is real-browser-only and verified manually/in Storybook, not by jsdom.
+
+<!-- variant-facts:MultiColumn:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**gap**: `none` · `sm` · `md` · `lg`\* · `xl`
+
+**stackBelow**: `sm` · `md` · `lg`\* · `xl`
+
+<!-- variant-facts:MultiColumn:end -->
+
 ### PageBackground
 - **Exports**: `PageBackground`, type `PageBackgroundProps`
 - **Custom props**: `fixed` — fixed to viewport (default `true`) vs absolute-fill of positioned parent.
@@ -580,11 +910,35 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **Variants**: `direction`: `vertical`* | `horizontal`; `gap`: `none` | `xs` | `sm` | `md`* | `lg` | `xl` | `2xl`; `align`: `start` | `center` | `end` | `stretch`*; `justify`: `start` | `center` | `between` | `end`
 - **Custom props**: `as` — render as different element (default `div`).
 
+<!-- variant-facts:Stack:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**direction**: `vertical`\* · `horizontal`
+
+**gap**: `none` · `xs` · `sm` · `md`\* · `lg` · `xl` · `2xl`
+
+**align**: `start` · `center` · `end` · `stretch`\*
+
+**justify**: `start` · `center` · `between` · `end`
+
+<!-- variant-facts:Stack:end -->
+
 ### TwoColumn
 - **Exports**: `TwoColumn`, `TwoColumnAside`, `TwoColumnMain`, `twoColumnVariants`, type `TwoColumnProps`
 - **Variants** (TwoColumn): `gap`: `none` | `sm` | `md` | `lg`* | `xl`; `reverse`: aside after main at lg+
 - **Notes**: Compose `<TwoColumn><TwoColumnAside/><TwoColumnMain/></TwoColumn>`; stacks below `lg`. Aside default `lg:w-64` (override via className); Main is `min-w-0 flex-1`.
 
+<!-- variant-facts:TwoColumn:start — GENERATED by `pnpm docs:variants`; edit
+     scripts/variant-intent.json (judgment) or the component (facts), not this block. -->
+
+
+**gap**: `none` · `sm` · `md` · `lg`\* · `xl`
+
+**reverse**: `true`
+
+<!-- variant-facts:TwoColumn:end -->
+
 ### Utils
 
 ### cn
@@ -637,3 +991,134 @@ Both mode files define the identical names (`mode-light.css` on `:root`, `mode-d
 - Charts: `--chart-1`…`--chart-5`; `--chart-blue(-subtle)`, `--chart-emerald(-subtle)`, `--chart-amber(-subtle)`, `--chart-red(-subtle)`, `--chart-purple(-subtle)`, `--chart-lime(-subtle)`, `--chart-indigo(-subtle)`, `--chart-orange(-subtle)`
 - AI affordance: `--ai-surface`, `--ai-gradient-from`, `--ai-gradient-to`
 - Logo ink: `--logo-mark-dark` (mode-driven, defined in base.css)
+
+<!-- token-facts:start — GENERATED by `pnpm docs:variants` from
+     docs/css-variables.json; edit src/styles/tokens/* and re-run, not this block. -->
+
+### 7.3 Resolved token values
+
+Actual values per mode, `light → dark` (a single value is identical in both
+modes). Product-scoped tokens are listed per product; `slingshot` is the
+default (`:root`) product.
+
+**Backgrounds**
+
+| token | light → dark |
+|---|---|
+| `--danger-bg` | #fde6ea → #6c0016 |
+| `--ghost-bg` | rgb(255 255 255 / 0.0001) |
+| `--ghost-hover-bg` | rgb(31 40 50 / 0.05) → rgb(255 255 255 / 0.1) |
+| `--info-bg` | #e0f2fe → #0c4a6e |
+| `--input-bg` | #ffffff → #1f2832 |
+| `--muted-bg` | #f3f4f6 → #111827 |
+| `--navbar-active-bg` | #e90130 |
+| `--outline-bg` | rgb(255 255 255 / 0.1) → rgb(255 255 255 / 0.05) |
+| `--outline-hover-bg` | rgb(31 40 50 / 0.0333) → rgb(255 255 255 / 0.1) |
+| `--overlay-bg` | rgb(31 40 50 / 0.4) |
+| `--primary-bg` | #ffffff → #111827 |
+| `--primary-invert-bg` | #111827 → #ffffff |
+| `--primary-invert-hover-bg` | #374151 → #d1d5db |
+| `--secondary-bg` | #e5e7eb → #4b5563 |
+| `--secondary-hover-bg` | #f9fafb → #111827 |
+| `--success-bg` | #ecfccb → #365314 |
+| `--switch-active-bg` | #84cc16 |
+| `--toggle-active-bg` | rgb(31 40 50 / 0.05) → rgb(255 255 255 / 0.1) |
+| `--warning-bg` | #ffedd5 → #431407 |
+
+**Glass**
+
+| token | light → dark |
+|---|---|
+| `--glass-20-bg` | rgb(255 255 255 / 0.2) → rgb(31 40 50 / 0.2) |
+| `--glass-40-bg` | rgb(255 255 255 / 0.4) → rgb(31 40 50 / 0.4) |
+| `--glass-60-bg` | rgb(255 255 255 / 0.6) → rgb(31 40 50 / 0.6) |
+| `--glass-blur` | 45px |
+| `--glass-none-bg` | #ffffff → #111827 |
+
+**Text**
+
+| token | light → dark |
+|---|---|
+| `--danger-txt` | #bc0126 → #f699ac |
+| `--info-txt` | #0369a1 → #7dd3fc |
+| `--muted-txt` | #6b7280 → #9ca3af |
+| `--primary-invert-txt` | #f3f4f6 → #111827 |
+| `--primary-txt` | #111827 → #f3f4f6 |
+| `--secondary-txt` | #374151 → #e5e7eb |
+| `--success-txt` | #4d7c0f → #bef264 |
+| `--warning-txt` | #c2410c → #fdba74 |
+
+**Borders**
+
+| token | light → dark |
+|---|---|
+| `--danger-border` | #bc0126 → #f699ac |
+| `--info-border` | #0369a1 → #7dd3fc |
+| `--muted-border` | #f3f4f6 → #111827 |
+| `--primary-border` | #e5e7eb → #374151 |
+| `--primary-invert-border` | #9ca3af → #4b5563 |
+| `--secondary-border` | #d1d5db → #374151 |
+| `--selected-border` | #1f2937 → #f9fafb |
+| `--success-border` | #4d7c0f → #bef264 |
+| `--warning-border` | #c2410c → #fdba74 |
+
+**Focus**
+
+| token | light → dark |
+|---|---|
+| `--focus` | #d1d5db → #374151 |
+| `--focus-error` | #f699ac → #6c0016 |
+
+**Charts**
+
+| token | light → dark |
+|---|---|
+| `--chart-1` | #f54a00 |
+| `--chart-2` | #009689 |
+| `--chart-3` | #104e64 |
+| `--chart-4` | #ffb900 |
+| `--chart-5` | #fe9a00 |
+| `--chart-amber` | #fbbf24 → #b45309 |
+| `--chart-amber-subtle` | #fde68a → #78350f |
+| `--chart-blue` | #60a5fa → #1d4ed8 |
+| `--chart-blue-subtle` | #bfdbfe → #1e3a8a |
+| `--chart-emerald` | #34d399 → #047857 |
+| `--chart-emerald-subtle` | #a7f3d0 → #064e3b |
+| `--chart-indigo` | #818cf8 → #4338ca |
+| `--chart-indigo-subtle` | #c7d2fe → #312e81 |
+| `--chart-lime` | #a3e635 → #4d7c0f |
+| `--chart-lime-subtle` | #d9f99d → #365314 |
+| `--chart-orange` | #fb923c → #c2410c |
+| `--chart-orange-subtle` | #fed7aa → #7c2d12 |
+| `--chart-purple` | #c084fc → #7e22ce |
+| `--chart-purple-subtle` | #e9d5ff → #581c87 |
+| `--chart-red` | #f26783 → #bc0126 |
+| `--chart-red-subtle` | #fbccd6 → #6c0016 |
+
+**Logo ink**
+
+| token | light → dark |
+|---|---|
+| `--logo-mark-dark` | #111827 → #ffffff |
+
+**Other**
+
+| token | light → dark |
+|---|---|
+| `--ai-gradient-to` | #9ca3af → #4b5563 |
+| `--brand-gradient-to` | #e2e8f0 → #020617 |
+
+**Brand & gradients (per product)**
+
+| token | slingshot | bodhi | sustain |
+|---|---|---|---|
+| `--ai-gradient-from` | #e90130 | #3b82f6 | #6366f1 |
+| `--brand-200` | #fbccd6 → #6c0016 | #bfdbfe → #6c0016 | #c7d2fe → #6c0016 |
+| `--brand-50` | #fef2f5 → #3d000d | #eff6ff → #3d000d | #eef2ff → #3d000d |
+| `--brand-500-primary` | #e90130 | #3b82f6 | #6366f1 |
+| `--brand-700` | #bc0126 → #fbccd6 | #1d4ed8 → #bfdbfe | #4338ca → #c7d2fe |
+| `--brand-800` | #8d011d → #fbccd6 | #1e40af → #bfdbfe | #3730a3 → #c7d2fe |
+| `--brand-950` | #3d000d → #fef2f5 | #172554 → #eff6ff | #1e1b4b → #eef2ff |
+| `--brand-gradient-from` | #fbccd6 → #3d000d | #bfdbfe → #172554 | #c7d2fe → #1e1b4b |
+
+<!-- token-facts:end -->