@trading-game/design-intelligence-layer 0.17.4 → 1.0.0

package/docs/components/scroll-area.md

@@ -0,0 +1,66 @@
+# Scroll Area
+
+Custom-styled scroll container (Radix ScrollArea) with a themed thumb replacing the native scrollbar.
+
+## When to use
+
+- Fixed-height regions inside cards, menus, and panels where the native scrollbar would clash with the surface.
+- Horizontal strips (chips, thumbnails) via a `ScrollBar orientation="horizontal"`.
+
+**When not:** For whole-page scrolling use the document scrollbar. For resizable split panes use [Resizable](./resizable.md).
+
+## Anatomy
+
+- `ScrollArea` — Radix root (`relative`), renders Viewport + vertical `ScrollBar` + Corner automatically; `data-slot="scroll-area"`.
+- Viewport — internal, `size-full rounded-[inherit]`, focusable with the standard control ring; `data-slot="scroll-area-viewport"`.
+- `ScrollBar` — 10px-wide (`w-2.5` / `h-2.5`) scrollbar rail; `data-slot="scroll-area-scrollbar"`.
+- Thumb — internal `rounded-full` pill; `data-slot="scroll-area-thumb"`.
+
+## API
+
+### ScrollArea
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Rendered inside the viewport. |
+| ...props | Radix `ScrollArea.Root` props | — | e.g. `type`, `scrollHideDelay`. |
+
+### ScrollBar
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | A vertical bar is included by default; add a horizontal one yourself. |
+
+## Variants & sizes
+
+No variants; height comes from your own classes.
+
+```tsx
+import { ScrollArea, ScrollBar } from "@trading-game/design-intelligence-layer"
+
+<ScrollArea className="h-72 rounded-lg border border-border-default-default">
+  {/* long content */}
+  <ScrollBar orientation="horizontal" />
+</ScrollArea>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-border-default-default` (thumb), `ring-ring-focus-strong` (viewport keyboard focus, `focus-visible:ring-[3px]`).
+**Type (private):** none — the component renders no text.
+
+## Behaviour
+
+- `ScrollArea` always mounts a vertical `ScrollBar`; horizontal scrolling needs an explicit second `<ScrollBar orientation="horizontal" />` child.
+- The viewport inherits the root's radius (`rounded-[inherit]`), so putting the radius on `ScrollArea` clips content correctly.
+- The viewport is keyboard-focusable and takes the standard `focus-visible:ring-[3px] ring-ring-focus-strong` control ring.
+
+## Do / Don't
+
+**Do**
+- Give `ScrollArea` an explicit height (or max-height); without one nothing scrolls.
+- Put border and radius on the `ScrollArea` root so the viewport inherits the clip.
+
+**Don't**
+- Don't restyle the thumb with brand colour — it is a neutral `border-default-default` pill by design.
+- Don't nest a `ScrollArea` inside another scroll container on the same axis; wheel events become ambiguous.

package/docs/components/section-message.md

@@ -0,0 +1,99 @@
+# Section Message
+
+Inline status band (renamed from Alert) that reports info, warning, danger, or success context for a section of the page.
+
+## When to use
+
+- Persistent, contextual status tied to a section or form — verification pending, deposit failed, settings saved.
+- Messages that may carry one or two actions and an optional dismiss.
+
+**When not:** For transient confirmations use [Toast](./toast.md). For full-width promotional or app-level strips use Banner. For blocking confirmations use Alert Dialog.
+
+## Anatomy
+
+Single component, slot-driven; `data-slot="section-message"` with `data-variant`, `data-layout`, `data-size` attributes.
+
+- Icon column — per-variant default icon (Info / AlertTriangle / XCircle / CheckCircle2), the only element that carries severity colour.
+- Body — title (semibold) + description (regular), both `text-text-prominent-default`.
+- Action slot — one button beside the text (`row`) or up to two below it (`stack`).
+- Close X — renders only when `onDismiss` is provided; neutral `icon-subtle` at 70% opacity.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"info" \| "warning" \| "danger" \| "success"` | `"info"` | Surface + border + icon colour. |
+| `layout` | `"row" \| "stack" \| "inline" \| "card"` | `"row"` | `inline` and `card` are aliases — `inline`→`row`, `card`→`stack`. @deprecated — removed at v1.0. |
+| `size` | `"sm" \| "md"` | `"md"` | Strict one-step ladder: padding 16→12, gaps 12→8, icon 16→14, radius xl→lg, type 14/20→12/16. |
+| `title` | `ReactNode` | — | At least one of `title`/`description` is required; otherwise renders `null` with a dev warning. |
+| `description` | `ReactNode` | — | Regular weight; hierarchy vs. title is weight-only (600 vs 400). |
+| `icon` | `ReactNode \| null` | variant default | `null` omits the icon; any node overrides it. |
+| `action` | `ReactNode` | — | Honoured only in `layout="row"`; primitives get wrapped in `<Button variant="secondary" size="sm">`. |
+| `actions` | `ReactNode[]` | — | Honoured only in `layout="stack"`; capped at 2. |
+| `onDismiss` | `() => void` | — | Presence renders the close X. |
+| `dismissLabel` | `string` | `"Dismiss"` | aria-label for the close button. |
+
+Deprecated aliases: `Alert`, `alertVariants`, `AlertProps`, `AlertVariant`, `AlertLayout` — @deprecated — removed at v1.0.
+
+## Variants & sizes
+
+```tsx
+import { SectionMessage, Button } from "@trading-game/design-intelligence-layer"
+
+<SectionMessage variant="info" title="Verification pending" description="Usually takes under 2 minutes." />
+
+<SectionMessage
+  variant="danger"
+  layout="row"
+  title="Deposit failed"
+  action={<Button variant="secondary" size="sm">Retry</Button>}
+  onDismiss={() => {}}
+/>
+
+<SectionMessage
+  variant="warning"
+  layout="stack"
+  size="sm"
+  title="Margin call risk"
+  description="Your equity is below 50% of used margin."
+  actions={["Add funds", "Close positions"]}
+/>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- Surfaces/borders: `bg-background-information-default` + `border-border-information-default` (info), same pattern with `warning`, `error` (danger variant), `success`.
+- Title/description ink: `text-text-prominent-default` on every variant.
+- Icon ink: `text-icon-information-default` / `-warning-` / `-error-` / `-success-` — the only severity colour signal.
+- Close X: a composed `NavigationButton` (circular per the icon-button law) carrying the tone ink at 70% opacity; focus `ring-ring-focus-strong` at 3px.
+
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--section-message-title-*` (md) | 14 / semibold (600) / 20 |
+| `--section-message-description-*` (md) | 14 / regular (400) / 20 |
+| `--section-message-title-*-sm` | 12 / semibold (600) / 16 |
+| `--section-message-description-*-sm` | 12 / regular (400) / 16 |
+
+## Behaviour
+
+- `danger` and `warning` render `role="alert"` + `aria-live="assertive"`; `info` and `success` use `role="status"` + `polite`.
+- Row layout is mobile-first: 3 columns × 2 rows so the action drops below the body; at `sm:` (640px) it collapses to one row of 4 columns (icon · body · action · close).
+- Single-line row messages (title only or description only) centre vertically and hold a resting min-height of 48px (md) / 40px (sm), growing when text wraps.
+- Actions are normalized: React elements pass through untouched; string/number actions get wrapped in a Secondary `sm` Button. Dev-mode warns when `actions` is passed to `row` or `action` to `stack`.
+- Rendering with neither `title` nor `description` returns `null` (dev warning).
+
+## Do / Don't
+
+**Do**
+- Let the icon alone carry severity — title and description stay `text-prominent` on all four variants.
+- Use Secondary `sm` buttons for actions; promotional surfaces that need primary-inverse buttons belong on Banner.
+- Pass `onDismiss` only when dismissing is genuinely meaningful; its absence removes the X entirely.
+
+**Don't**
+- Don't use the deprecated `inline`/`card` layout values or the `Alert` alias in new code — both go at v1.0.
+- Don't exceed two actions in `stack`; the component slices at 2.
+- Don't bold the description or push the title past semibold 600 — the 600/400 weight pair is the entire hierarchy.
+- Don't add shadows — status bands are flat tinted surfaces with a hairline border.

package/docs/components/select.md

@@ -0,0 +1,105 @@
+# Select
+
+Single-choice dropdown (Radix Select) with a form-input trigger and a menu-styled option list.
+
+## When to use
+
+- Choosing one value from 5–15 options inside a form — account currency, leverage, market.
+- When the current value must read like an input, sitting on the 32/40/48 field rail.
+
+**When not:** For 2–4 always-visible options use [Toggle Group](./toggle-group.md) or Tabs. For command-style search over long lists use Command. For native mobile pickers use Native Select.
+
+## Anatomy
+
+- `Select` / `SelectGroup` / `SelectValue` — Radix pass-throughs; `data-slot="select"`, `"select-group"`, `"select-value"`.
+- `SelectTrigger` — input-shaped button, `rounded-xs` hairline on `bg-background-primary-surface`, chevron at 50% opacity; `data-slot="select-trigger"`, `data-size`, `data-readonly`.
+- `SelectContent` — portalled `rounded-lg` list on primary surface; `data-slot="select-content"`.
+- `SelectItem` — `rounded-md` row with a right-aligned brand check when selected; `data-slot="select-item"` (+ `select-item-indicator`).
+- `SelectLabel` — group heading, `type-menu-heading`, subtle ink; `data-slot="select-label"`.
+- `SelectSeparator` — 1px hairline between groups; `data-slot="select-separator"`.
+- `SelectScrollUpButton` / `SelectScrollDownButton` — chevron rows for overflowing lists.
+
+## API
+
+### SelectTrigger
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | sm `h-8 px-3`, md `h-10 px-3`, lg `h-12 px-4` — the 32/40/48 rail. |
+| `readOnly` | `boolean` | `false` | Locked but reachable: stays focusable, announces `aria-readonly`, never opens (open triggers are swallowed); full opacity, cursor default, chevron at 30%. |
+| ...props | Radix `Trigger` props | — | `disabled` etc. |
+
+### SelectContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `position` | `"popper" \| "item-aligned"` | `"popper"` | Deliberate override of the Radix default — see Behaviour. |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Popper alignment. |
+
+### Select (root)
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `string` | — | Controlled / uncontrolled. |
+| `onValueChange` | `(value: string) => void` | — | Radix callback. |
+
+`SelectItem` requires `value: string`; other parts take standard Radix props plus `className`.
+
+## Variants & sizes
+
+Trigger sizes only — the type ladder is picked in JSX (`type-select-sm/md/lg`) because `.type-*` classes are plain CSS and Tailwind `data-[]` variants cannot gate them.
+
+```tsx
+import {
+  Select, SelectTrigger, SelectValue, SelectContent,
+  SelectGroup, SelectLabel, SelectItem, SelectSeparator,
+} from "@trading-game/design-intelligence-layer"
+
+<Select defaultValue="usdt">
+  <SelectTrigger size="md" className="w-48">
+    <SelectValue placeholder="Currency" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectLabel>Stablecoins</SelectLabel>
+      <SelectItem value="usdt">USDT</SelectItem>
+      <SelectItem value="usdc">USDC</SelectItem>
+    </SelectGroup>
+    <SelectSeparator />
+    <SelectItem value="btc">BTC</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Tokens
+
+**Colour (semantic):** `border-border-default-default` + `bg-background-primary-surface` + `text-text-prominent-default` (trigger and content), `text-text-subtle-default` (placeholder, labels), `icon-subtle-default` (chevron, item icons), `bg-background-hover-default` (item focus row), `text-text-brand-selected` (checked item text and check icon), `border-border-error-default` + `ring-error-soft` (invalid), soft focus `ring-ring-focus-soft` at 3px.
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--select-*-sm` (trigger) | 12 / regular (400) / 16 |
+| `--select-*-md` (trigger) | 14 / regular (400) / 20 |
+| `--select-*-lg` (trigger) | 16 / regular (400) / 24 |
+| Rows / labels | shared `--menu-*` family — item 14/regular/20, heading 12/medium/16 |
+
+## Behaviour
+
+- `SelectContent` defaults to `position="popper"`, opening the list **below** the trigger. The Radix default (`item-aligned`) was deliberately replaced because it slides the list to overlap the trigger, which reads as a bug next to the other menus.
+- In popper mode the viewport is sized to the trigger (`min-w-[var(--radix-select-trigger-width)]`), and the list is offset 1 unit from the trigger edge.
+- Checked items show `text-text-brand-selected` ink plus a brand `CheckIcon` in the right indicator slot — no fill change on the row.
+- `readOnly` keeps the trigger in the tab order and announced (unlike `disabled`) — keyboard and screen-reader users can still reach and hear the locked value; it just never opens.
+- The trigger uses the text-field soft focus ring (`ring-focus-soft`), not the 50% control ring.
+
+## Do / Don't
+
+**Do**
+- Keep triggers on the 32/40/48 rail via `size`; set width with `className`, not padding overrides.
+- Use `SelectLabel` + `SelectSeparator` to group long lists; labels are 12/medium/16 subtle ink.
+- Use `readOnly` (not `disabled`) for locked-but-meaningful values.
+
+**Don't**
+- Don't pass `position="item-aligned"` — the popper-below behaviour is a system decision.
+- Don't restyle the checked state with a background fill; selection here is ink + check icon only.
+- Don't gate the trigger type with `data-[size]` utilities — `.type-select-*` is plain CSS and beats `font-*` utilities; the size prop already picks it in JSX.
+- Don't add shadows to `SelectContent` — menus are solid surfaces with a hairline border.

package/docs/components/separator.md

@@ -0,0 +1,55 @@
+# Separator
+
+A 1px hairline divider (Radix Separator), horizontal or vertical.
+
+## When to use
+
+- Dividing groups within a surface — menu sections, toolbar clusters, list segments — where spacing alone is not enough.
+
+**When not:** For a draggable divider between panes use [Resizable](./resizable.md). Inside tables, rows already carry their own hairline borders.
+
+## Anatomy
+
+- `Separator` — single element; `h-px w-full` horizontal, `w-px h-full` vertical via `data-[orientation]`; `data-slot="separator"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Drives the `data-orientation` styling. |
+| `decorative` | `boolean` | `true` | `true` removes it from the a11y tree; set `false` only for semantic separation. |
+
+## Variants & sizes
+
+One variant — always a 1px `border-default-default` line.
+
+```tsx
+import { Separator } from "@trading-game/design-intelligence-layer"
+
+<Separator className="my-4" />
+<div className="flex h-5 items-center gap-4">
+  <span>Spot</span>
+  <Separator orientation="vertical" />
+  <span>Futures</span>
+</div>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-border-default-default`.
+**Type (private):** none.
+
+## Behaviour
+
+- Vertical orientation needs a parent with a resolved height (`h-full` on the separator fills it).
+- `decorative` defaults to `true`, so screen readers skip it by default.
+
+## Do / Don't
+
+**Do**
+- Keep it at 1px and `border-default-default` — every divider in the system is the same hairline.
+- Control spacing with margin utilities (`my-4`, `mx-2`) on the separator, not wrapper divs.
+
+**Don't**
+- Don't recolour or thicken it to create emphasis; use spacing or type hierarchy instead.
+- Don't stack a Separator against an element that already has a border — doubles the line.

package/docs/components/sheet.md

@@ -0,0 +1,91 @@
+# Sheet
+
+Edge-anchored overlay panel (built on Radix Dialog) that slides in from a side of the viewport.
+
+## When to use
+
+- Secondary flows that keep page context — filters, order detail, settings panels.
+- The desktop/tablet counterpart to Drawer; the mobile [Sidebar](./sidebar.md) also renders inside a Sheet.
+
+**When not:** For centered blocking confirmation use Dialog / Alert Dialog. For mobile bottom trays use Drawer. For persistent navigation use [Sidebar](./sidebar.md).
+
+## Anatomy
+
+- `Sheet` / `SheetTrigger` / `SheetClose` / `SheetPortal` — Radix Dialog pass-throughs; `data-slot="sheet"`, `"sheet-trigger"`, `"sheet-close"`, `"sheet-portal"`.
+- `SheetOverlay` — full-viewport scrim, `bg-background-overlay-default`; `data-slot="sheet-overlay"`.
+- `SheetContent` — the sliding panel: solid `bg-background-primary-surface`, one hairline border on the attached edge, no radius, no shadow; built-in circular close button; `data-slot="sheet-content"`.
+- `SheetHeader` / `SheetFooter` — `p-4` column layout; footer is `mt-auto`; `data-slot="sheet-header"` / `"sheet-footer"`.
+- `SheetTitle` — `type-sheet-title` prominent ink; `data-slot="sheet-title"`.
+- `SheetDescription` — `type-sheet-description` subtle ink; `data-slot="sheet-description"`.
+
+## API
+
+### Sheet (root)
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `open` / `defaultOpen` | `boolean` | — | Controlled / uncontrolled. |
+| `onOpenChange` | `(open: boolean) => void` | — | Radix callback. |
+
+### SheetContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Anchor edge; left/right are `w-3/4 sm:max-w-sm`, top/bottom are `h-auto`. |
+| `showCloseButton` | `boolean` | `true` | Toggles the built-in circular close (size-8, top-right). |
+
+Other parts take standard Radix/div props plus `className`.
+
+## Variants & sizes
+
+No size prop — the `side` value is the only axis.
+
+```tsx
+import {
+  Sheet, SheetTrigger, SheetContent, SheetHeader,
+  SheetTitle, SheetDescription, SheetFooter, SheetClose,
+  Button,
+} from "@trading-game/design-intelligence-layer"
+
+<Sheet>
+  <SheetTrigger asChild><Button variant="secondary">Filters</Button></SheetTrigger>
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Filters</SheetTitle>
+      <SheetDescription>Narrow the market list.</SheetDescription>
+    </SheetHeader>
+    <SheetFooter>
+      <SheetClose asChild><Button variant="primary">Apply</Button></SheetClose>
+    </SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-overlay-default` (scrim), `bg-background-primary-surface` (panel), `border-border-default-default` (hairline on the attached edge: `border-l` for right, `border-r` for left, `border-b` for top, `border-t` for bottom), `text-text-prominent-default` (title), `text-text-subtle-default` (description), `text-icon-subtle-default` + `bg-background-hover-default` hover glaze (close button), `ring-ring-focus-strong` at 3px (close focus).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--sheet-title-*` | 18 / semibold (600) / 24 |
+| `--sheet-description-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- Enter/exit are directional slides (`slide-in-from-*` / `slide-out-to-*`) on the overlay motion role: `--motion-overlay-open` (320ms, `ease-enter`) in and `--motion-overlay-close` (250ms, `ease-exit`) out; the overlay fades.
+- Left/right sheets are 75% viewport width capped at `sm:max-w-sm`; top/bottom size to content.
+- The built-in close is a `size-8` circle (`rounded-full`) at 70% opacity that gains the `background-hover-default` glaze on hover — the icon-buttons-are-circles rule.
+- The panel has a hairline only on its attached edge and no rounded corners on any side — it meets the viewport edges flush.
+
+## Do / Don't
+
+**Do**
+- Always include `SheetTitle` (visually or `sr-only`) — Radix Dialog requires it for a11y; the mobile Sidebar does exactly this.
+- Put primary actions in `SheetFooter`; it pins to the bottom via `mt-auto`.
+- Keep the built-in close unless the sheet supplies its own explicit dismissal.
+
+**Don't**
+- Don't add shadows or rounded edges to `SheetContent` — the edge hairline is the entire separation; cards/dialogs get `rounded-2xl`, sheets get none.
+- Don't push the title past semibold 600.
+- Don't stack sheets; open at most one overlay layer at a time.

package/docs/components/sidebar.md

@@ -0,0 +1,125 @@
+# Sidebar
+
+Desktop navigation rail with collapsible states, grouped menus, and an automatic mobile Sheet fallback.
+
+## When to use
+
+- Primary app navigation on desktop — market sections, account areas, tool groups.
+- Layouts that need an icon-collapsed rail (`collapsible="icon"`) to reclaim width.
+
+**When not:** For mobile primary navigation use Bottom Navigation. For transient side panels use [Sheet](./sheet.md) directly.
+
+## Anatomy
+
+- `SidebarProvider` — context + state owner; sets `--sidebar-width` (16rem) / `--sidebar-width-icon` (3rem); `data-slot="sidebar-wrapper"`.
+- `Sidebar` — the rail; on mobile renders inside a `Sheet` (18rem wide, hidden built-in close); `data-slot="sidebar"` with `data-state`, `data-collapsible`, `data-variant`, `data-side`.
+- `SidebarTrigger` — Secondary icon Button (`size-7`) that toggles; `data-slot="sidebar-trigger"`.
+- `SidebarRail` — invisible edge strip for click/drag-style toggling; `data-slot="sidebar-rail"`.
+- `SidebarInset` — the `main` content area (`bg-background-primary-canvas`); insets itself when `variant="inset"`; `data-slot="sidebar-inset"`.
+- `SidebarHeader` / `SidebarContent` / `SidebarFooter` — vertical regions; `data-slot="sidebar-header"` / `"sidebar-content"` / `"sidebar-footer"`.
+- `SidebarGroup` / `SidebarGroupLabel` / `SidebarGroupAction` / `SidebarGroupContent` — labelled sections; label is `type-sidebar-label` subtle ink and slides away when icon-collapsed.
+- `SidebarMenu` / `SidebarMenuItem` / `SidebarMenuButton` / `SidebarMenuAction` / `SidebarMenuBadge` / `SidebarMenuSkeleton` — the nav rows.
+- `SidebarMenuSub` / `SidebarMenuSubItem` / `SidebarMenuSubButton` — nested rows behind a hairline left border; hidden when icon-collapsed.
+- `SidebarInput` / `SidebarSeparator` — Input and Separator tuned for the rail.
+- `useSidebar()` — hook exposing `state`, `open`, `setOpen`, `openMobile`, `setOpenMobile`, `isMobile`, `toggleSidebar`; throws outside `SidebarProvider`.
+
+## API
+
+### SidebarProvider
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` | `true` | Uncontrolled initial state. |
+| `open` / `onOpenChange` | `boolean` / `(open) => void` | — | Controlled mode. |
+
+### Sidebar
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `side` | `"left" \| "right"` | `"left"` | Anchor edge. |
+| `variant` | `"sidebar" \| "floating" \| "inset"` | `"sidebar"` | `floating` gets `rounded-lg` + hairline; `inset` pads the main area. |
+| `collapsible` | `"offcanvas" \| "icon" \| "none"` | `"offcanvas"` | `offcanvas` slides fully away; `icon` collapses to the 3rem rail; `none` is static. |
+
+### SidebarMenuButton
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `isActive` | `boolean` | `false` | Sets `data-active` — brand-selected fill + ink + semibold. |
+| `variant` | `"default" \| "outline"` | `"default"` | Outline adds `ring-1 ring-border-default-default` on primary surface. |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | h-8 / h-7 / h-12; sm uses `type-sidebar-menu-sm`. |
+| `tooltip` | `string \| TooltipContent props` | — | Shown only while collapsed on desktop. |
+| `asChild` | `boolean` | `false` | Slot passthrough for links. |
+
+### SidebarMenuSubButton
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md"` | `"md"` | 12/16 vs 14/20 type. |
+| `isActive` | `boolean` | `false` | Same brand-selected treatment as top rows. |
+| `asChild` | `boolean` | `false` | Renders an `<a>` by default. |
+
+`SidebarMenuAction` adds `showOnHover?: boolean`; `SidebarMenuSkeleton` adds `showIcon?: boolean`.
+
+## Variants & sizes
+
+```tsx
+import {
+  SidebarProvider, Sidebar, SidebarContent, SidebarGroup,
+  SidebarGroupLabel, SidebarMenu, SidebarMenuItem,
+  SidebarMenuButton, SidebarTrigger, SidebarInset,
+} from "@trading-game/design-intelligence-layer"
+
+<SidebarProvider>
+  <Sidebar collapsible="icon">
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Markets</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton isActive tooltip="Forex">Forex</SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+  </Sidebar>
+  <SidebarInset>
+    <SidebarTrigger />
+    {/* page */}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-primary-surface` (rail), `text-text-prominent-default` (rows), `bg-background-hover-default` + `text-text-brand-hover` (row hover/active-press), `bg-background-brand-selected` + `text-text-brand-selected` (active rows, icons included), `text-text-subtle-default` (group labels), `border-border-default-default` (rail edge, sub-menu left hairline, separators), `bg-background-secondary-surface` (action-button hover), `ring-ring-focus-default` (focus, `ring-2`).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--sidebar-menu-*` | 14 / regular (400) / 20 |
+| `--sidebar-menu-*-sm` | 12 / regular (400) / 16 |
+| `--sidebar-menu-active-font-weight` | semibold (600), applied via CSS `[data-sidebar="menu-button"][data-active="true"]` |
+| `--sidebar-label-*` (labels and badges) | 12 / medium (500) / 16 |
+
+Legacy `--sidebar` / `--sidebar-foreground` / `--sidebar-accent` aliases still exist in `styles.css` mapped onto semantic tokens.
+
+## Behaviour
+
+- State lives in `SidebarProvider`; desktop open state persists in the `sidebar_state` cookie for 7 days. Controlled mode via `open`/`onOpenChange`.
+- Keyboard shortcut: cmd/ctrl+B toggles the sidebar globally.
+- On mobile (`useIsMobile`) the rail renders inside a `SheetContent` at 18rem with the Sheet's own close hidden and an `sr-only` title/description for a11y; `openMobile`/`setOpenMobile` drive it.
+- Active rows go semibold through the CSS data-attribute rule, not a `font-*` utility — `.type-sidebar-menu` is plain CSS and Tailwind variants can't gate it.
+- When collapsed to `icon`, group labels animate away (`-mt-8 opacity-0`), sub-menus/badges/actions hide, and `SidebarMenuButton` tooltips activate (side="right").
+- Width transitions run at constant speed (`ease-linear`, `duration-base`).
+
+## Do / Don't
+
+**Do**
+- Mark exactly one row per view `isActive` — brand-selected fill (light: 10% brand tint; dark: solid `#121A55`-family fill with blue-200 ink) is the selection signal.
+- Provide `tooltip` on every `SidebarMenuButton` when using `collapsible="icon"`; labels vanish in the rail state.
+- Wrap the whole layout — rail and `SidebarInset` — in one `SidebarProvider`.
+
+**Don't**
+- Don't apply `font-semibold` to active rows yourself — the `data-active` CSS rule already does it, and `.type-sidebar-menu` beats `font-*` utilities anyway.
+- Don't push any row weight past semibold 600 or add shadows to the rail — it is a flat primary surface with a hairline edge.
+- Don't call `useSidebar()` outside `SidebarProvider`; it throws.

package/docs/components/skeleton.md

@@ -0,0 +1,51 @@
+# Skeleton
+
+Pulsing placeholder block shown while real content loads.
+
+## When to use
+
+- Loading states for content with a known shape — table rows, cards, avatars, nav items (see `SidebarMenuSkeleton`).
+
+**When not:** For indeterminate action feedback (button press, background task) use [Spinner](./spinner.md). For measured progress use Progress.
+
+## Anatomy
+
+- `Skeleton` — a single `div` on `bg-background-secondary-surface` with a directional loading sweep (`--animate-skeleton-sweep`); `data-slot="skeleton"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `className` | `string` | — | Sizing and shape overrides; all other div props pass through. |
+
+## Variants & sizes
+
+No variants — shape comes entirely from `className`.
+
+```tsx
+import { Skeleton } from "@trading-game/design-intelligence-layer"
+
+<Skeleton className="h-4 w-40" />          {/* text line */}
+<Skeleton className="size-10 rounded-full" /> {/* avatar */}
+<Skeleton className="h-24 w-full rounded-2xl" /> {/* card */}
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-secondary-surface`.
+**Type (private):** none.
+
+## Behaviour
+
+- Purely presentational; the animation is the named `--animate-skeleton-sweep` token (1.6s directional gradient), replacing the generic pulse.
+- Default radius is `rounded-md` (8px, the row radius); override to match the target shape — `rounded-full` for avatars, `rounded-2xl` for cards.
+
+## Do / Don't
+
+**Do**
+- Match the skeleton's radius to the component it stands in for (rows `rounded-md`, cards `rounded-2xl`, avatars circles).
+- Mirror the real layout's dimensions so content does not jump on load.
+
+**Don't**
+- Don't tint skeletons with brand colour — they stay on the neutral secondary surface.
+- Don't mix Skeleton and Spinner for the same region; pick one loading treatment.

package/docs/components/slider.md

@@ -0,0 +1,61 @@
+# Slider
+
+Continuous or stepped value selection on a track (Radix Slider), single- or multi-thumb.
+
+## When to use
+
+- Picking a value or range along a bounded scale — leverage, risk percentage, price range filters.
+
+**When not:** For exact numeric entry use [Stepper](./stepper.md) or Input. For on/off use [Switch](./switch.md).
+
+## Anatomy
+
+- `Slider` — Radix root; renders track, range, and one thumb per value; `data-slot="slider"`.
+- Track — `h-1.5` `rounded-full` bar on the secondary surface; `data-slot="slider-track"`.
+- Range — filled portion, blue alpha glaze; `data-slot="slider-range"`.
+- Thumb — `size-4` circle, solid brand fill; `data-slot="slider-thumb"`.
+
+## API
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` / `defaultValue` | `number[]` | — | Thumb count = array length; with neither set, two thumbs render at `[min, max]`. |
+| `min` / `max` | `number` | `0` / `100` | Bounds. |
+| `onValueChange` | `(value: number[]) => void` | — | Radix callback. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Vertical gets `min-h-44`. |
+| `step`, `disabled`, ... | Radix `Slider.Root` props | — | Pass through; disabled renders at 50% opacity. |
+
+## Variants & sizes
+
+No variants and no size prop.
+
+```tsx
+import { Slider } from "@trading-game/design-intelligence-layer"
+
+<Slider defaultValue={[25]} max={100} step={1} />
+<Slider defaultValue={[20, 80]} />  {/* range, two thumbs */}
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-secondary-surface` (track), `bg-background-brand-default` (thumb), `ring-ring-focus-strong` (hover/focus ring, `ring-4`).
+**Range fill:** solid `bg-background-brand-default` — the shared track spec with Progress (h-2, rounded-full, secondary-surface trackly, per the glaze exception to the semantic-only rule (a matching `--slider-range` alias exists in `styles.css`).
+**Type (private):** none — the component renders no text.
+
+## Behaviour
+
+- Thumb count is derived from the value array; an uncontrolled slider with no `defaultValue` renders two thumbs at `[min, max]`.
+- The thumb is a `rounded-full size-4` brand circle with `border-0`; hover and keyboard focus both show a 4px `ring-ring-focus-strong` halo.
+- Vertical orientation flips the layout (`flex-col`, `w-1.5` track) and enforces `min-h-44`.
+- Disabled state: root and thumbs at `opacity-24`, pointer events off on thumbs.
+
+## Do / Don't
+
+**Do**
+- Pass an explicit `defaultValue`/`value` array — relying on the `[min, max]` fallback silently creates a two-thumb range slider.
+- Pair the slider with a live numeric readout (or a [Stepper](./stepper.md)) for precise amounts.
+
+**Don't**
+- Don't recolour the range with an opaque brand fill — the 40% blue alpha glaze over the secondary track is the design.
+- Don't resize the thumb; the `size-4` circle matches the circular-control rule.
+- Don't add shadows to track or thumb.