@psnext/design-system 2.2.0 → 2.4.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).
@@ -290,6 +381,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`
@@ -327,6 +432,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 +459,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 +470,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 +543,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`
@@ -397,6 +576,14 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **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)
@@ -456,6 +643,21 @@ Stories in `src/<layer>/<Component>/<Component>.stories.tsx` are the canonical e
 - **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 +693,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 +801,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`; `onCloseProjectOverlay`; `logoAddon` — node between logo and picker; `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? }`.
+- **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 +810,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 +844,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 +887,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 +968,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 -->

package/README.md

@@ -7,7 +7,7 @@ Bodhi, Sustain, …), in light and dark.
 
 - **65 primitives** (Button, Dialog, Input, Select, Table, Tabs, Card, Chart, …)
 - **7 patterns** (Header, Footer, DataTable, MediaObject, SectionCard, …)
-- **5 layouts** (Container, Stack, TwoColumn, PageBackground, …)
+- **5 layouts** (Container, MultiColumn, Stack, TwoColumn, PageBackground)
 - Dual **ESM + CJS** builds with **TypeScript declarations**; deep imports are tree-shakeable.
 
 > **Browse every component in Storybook** — each has a live preview, a props
@@ -43,7 +43,7 @@ will write DS-native code instead of guessing:
 
 ### Install them as an Agent Skill (recommended)
 
-Run this in your app to copy both docs into `.agents/skills/design-system/`,
+Run this in your app to copy both docs into `.agent/skills/design-system/`,
 where coding agents pick them up automatically:
 
 ```bash
@@ -128,7 +128,7 @@ shown on its **Storybook Docs** page (generated from the source types + JSDoc).
 |---|---|
 | `@psnext/design-system/primitives/*` · `…/primitives` | Button, Dialog, Input, Select, Table, Tabs, Card, Chart, Badge, Text, Heading, Icon, `Logo`, Credits, `ThemeProvider`/`useTheme`, … (65) |
 | `@psnext/design-system/patterns/*` · `…/patterns` | `Header`, `Footer`, `DataTable`, `MediaObject`, `NavRail`, `SectionCard`, `SectionHeading` |
-| `@psnext/design-system/layouts/*` · `…/layouts` | `Container`, `Stack`, `TwoColumn`, `PageBackground` |
+| `@psnext/design-system/layouts/*` · `…/layouts` | `Container`, `MultiColumn`, `Stack`, `TwoColumn`, `PageBackground` |
 | `@psnext/design-system/styles` | the single raw-CSS entry (tokens + themes + bridge) |
 
 The package is **side-effect-free** (`sideEffects: ["**/*.css"]`), so unused