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

package/docs/components/navigation-menu.md

@@ -0,0 +1,99 @@
+# Navigation Menu
+
+Site navigation with dropdown panels — triggers in a row, rich link panels beneath.
+
+## When to use
+
+- Top-level site/app navigation where sections expand into panels of links.
+
+**When not:** For application command menus use [Menubar](./menubar.md). For a single circular back/forward control use [Navigation Button](./navigation-button.md). For page number navigation use [Pagination](./pagination.md).
+
+## Anatomy
+
+- `NavigationMenu` — Radix root; renders the shared `NavigationMenuViewport` unless `viewport={false}`. `data-slot="navigation-menu"`, `data-viewport`.
+- `NavigationMenuList` — horizontal `<ul>`, `gap-1`. `data-slot="navigation-menu-list"`.
+- `NavigationMenuItem` — one entry. `data-slot="navigation-menu-item"`.
+- `NavigationMenuTrigger` — `h-10 rounded-md px-4` button with an auto-appended `ChevronDownIcon` that rotates 180° while open. `data-slot="navigation-menu-trigger"`.
+- `NavigationMenuContent` — the panel content; when `viewport={false}` it becomes its own `rounded-lg` bordered dropdown. `data-slot="navigation-menu-content"`.
+- `NavigationMenuViewport` — shared panel frame below the bar: `rounded-lg`, hairline border, solid surface, animated height/width. `data-slot="navigation-menu-viewport"`.
+- `NavigationMenuLink` — link row, `rounded-md p-2`. `data-slot="navigation-menu-link"`.
+- `NavigationMenuIndicator` — small rotated-square arrow under the active trigger. `data-slot="navigation-menu-indicator"`.
+- `navigationMenuTriggerStyle` — exported cva to give plain links the trigger look.
+
+## API
+
+### NavigationMenu
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `viewport` | `boolean` | `true` | `true` = panels render in the single shared viewport; `false` = each content is its own dropdown under its item. |
+
+### NavigationMenuLink
+
+Radix `Link` props pass through; set `active` (renders `data-active=true`) to mark the current page, and use `asChild` for router links.
+
+Other parts take Radix/native props plus `className` only.
+
+## Variants & sizes
+
+No size rail — fixed density from the shared menu type family.
+
+```tsx
+import {
+  NavigationMenu,
+  NavigationMenuList,
+  NavigationMenuItem,
+  NavigationMenuTrigger,
+  NavigationMenuContent,
+  NavigationMenuLink,
+  navigationMenuTriggerStyle,
+} from "@trading-game/design-intelligence-layer"
+
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Markets</NavigationMenuTrigger>
+      <NavigationMenuContent>
+        <NavigationMenuLink active href="/markets/forex">Forex</NavigationMenuLink>
+        <NavigationMenuLink href="/markets/synthetics">Synthetics</NavigationMenuLink>
+      </NavigationMenuContent>
+    </NavigationMenuItem>
+    <NavigationMenuItem>
+      <NavigationMenuLink className={navigationMenuTriggerStyle()} href="/pricing">
+        Pricing
+      </NavigationMenuLink>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- trigger/viewport/panels: `bg-background-primary-surface`, `border-border-default-default`, ink `text-text-prominent-default`
+- hover/focus/open: `bg-background-hover-default` + `text-text-prominent-default`
+- active link (`data-active=true`): `bg-background-brand-selected` + `text-text-brand-selected` — held on hover and focus
+- link icons `text-icon-subtle-default` (16px default)
+- focus: 3px `ring-ring-focus-strong`; indicator arrow `bg-border-default-default`
+
+**Type (private):** shared `--menu-*` family — trigger `type-menu-trigger` 14/medium/20, links `type-menu-item` 14/regular/20.
+
+## Behaviour
+
+- With the default shared viewport, panels cross-fade and the viewport animates to each panel's size; content slides in from the direction of travel (`data-motion`).
+- `viewport={false}` gives per-item dropdowns: `top-full mt-1.5`, own `rounded-lg` border and surface.
+- The trigger chevron rotates 180° while open (`duration-slow`).
+- The current page keeps the brand-selected fill and ink even when hovered or focused — selection outranks hover.
+- On small screens content is full-width static (`md:absolute md:w-auto` gates the dropdown positioning).
+
+## Do / Don't
+
+**Do**
+- Mark the current route with `active` on `NavigationMenuLink` so it takes the brand-selected pair.
+- Use `navigationMenuTriggerStyle()` for panel-less top-level links so heights and hover states match triggers.
+- Keep panels `rounded-lg` (10px) with `rounded-md` (8px) link rows.
+
+**Don't**
+- Don't repaint the active state — `bg-background-brand-selected`/`text-text-brand-selected` are the selection contract, and dark mode has its own values (solid #121A55 fill + blue-200 ink), not a mirror of light.
+- Don't add shadows to the viewport or dropdowns; hairline on solid surface.
+- Don't nest a `Link` component inside `NavigationMenuLink`; use `asChild`/`href` on the menu link itself.

package/docs/components/numpad.md

@@ -0,0 +1,78 @@
+# Numpad
+
+The mobile amount-entry tray — a bare 3×4 digit grid with no key backgrounds; only glazes mark a touch.
+
+## When to use
+
+- Mobile amount entry: stake, deposit, withdrawal amounts, paired with an amount display the consumer owns.
+
+**When not:** For general text/number typing with a system keyboard use [Input](./input.md) (`inputMode="decimal"`). For code entry use [Input OTP](./input-otp.md).
+
+## Anatomy
+
+- `Numpad` — the whole grid: `role="group"`, `aria-label="Number pad"`, `grid-cols-3 gap-1`. `data-slot="numpad"`.
+- Keys — internal `<button>`s, `h-12 rounded-lg`, one per digit plus "." and backspace (a 22px `Delete` icon). `data-slot="numpad-key"`, `data-key`.
+- With `decimal={false}` the "." cell is an empty `aria-hidden` span — the slot stays, the grid never reflows.
+
+## API
+
+### Numpad
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `onKeyPress` | `(key: NumpadKey) => void` | — | Fires for every tap. `NumpadKey = "0"–"9" \| "." \| "backspace"`. |
+| `onClear` | `() => void` | — | Fires when backspace is long-pressed (~600ms). The release tap after a fired long-press is swallowed — no `onKeyPress("backspace")` follows. |
+| `decimal` | `boolean` | `true` | `false` hides the "." key; its grid slot stays empty. |
+| `disabled` | `boolean` | `false` | Dims the tray to 50% and blocks pointer events on grid and keys. |
+
+`onKeyDown`/`onKeyPress` DOM handlers are omitted from the div props; everything else passes through.
+
+## Variants & sizes
+
+No variants; keys are fixed at 48px rows (`h-12`) in a full-width 3-column grid.
+
+```tsx
+import { Numpad, type NumpadKey } from "@trading-game/design-intelligence-layer"
+
+const [amount, setAmount] = React.useState("")
+
+<Numpad
+  onKeyPress={(key: NumpadKey) => {
+    if (key === "backspace") setAmount((a) => a.slice(0, -1))
+    else setAmount((a) => a + key)
+  }}
+  onClear={() => setAmount("")}
+/>
+
+// Integer-only entry:
+<Numpad decimal={false} onKeyPress={handleKey} onClear={handleClear} />
+```
+
+## Tokens
+
+**Colour (semantic):**
+- keys: transparent at rest, `text-text-prominent-default`; backspace icon `text-icon-subtle-default`
+- hover glaze `bg-background-hover-default`, press glaze `bg-background-pressed-default` — the only fills the keys ever get
+- focus: 3px `ring-ring-focus-strong`
+
+**Type (private):** `--numpad-*`: 20 / medium / 28 (`type-numpad`).
+
+## Behaviour
+
+- Fully controlled: the component owns no amount — it only emits keys; the consumer owns the string.
+- Long-press clear: pointer-down on backspace starts a ~600ms timer; if it fires, `onClear` runs and the subsequent click is swallowed. Pointer-up or leaving the key cancels the timer. Context menu on backspace is suppressed so the long-press isn't hijacked on touch.
+- The hold timer is cleaned up on unmount.
+- Key order is 1–9 then [".", "0", backspace]; `decimal={false}` replaces "." with an empty `aria-hidden` span.
+- Backspace's accessible name is "Backspace — hold to clear".
+
+## Do / Don't
+
+**Do**
+- Own the amount string and its validation (decimal places, max) in the consumer — the tray is dumb by design.
+- Wire `onClear`; users expect hold-to-clear on trading numpads.
+- Keep keys at 48px height — the touch-target floor.
+
+**Don't**
+- Don't give keys resting backgrounds, borders, or shadows; per the design file, only the hover/press glazes mark a touch.
+- Don't emit your own backspace on long-press release — the component already swallows it; double handling double-deletes.
+- Don't collapse the empty "." slot when `decimal={false}`; the 0 key must stay centred under 8.

package/docs/components/pagination.md

@@ -0,0 +1,84 @@
+# Pagination
+
+Page navigation as a row of 40px circles — the active page lit with the brand-selected tokens.
+
+## When to use
+
+- Paged tables and lists: trade history, statements, leaderboards.
+
+**When not:** For prev/next-only stepping without page numbers use two [Navigation Buttons](./navigation-button.md). For loading more inline, use a "Load more" Button.
+
+## Anatomy
+
+- `Pagination` — `<nav role="navigation" aria-label="pagination">`, centred. `data-slot="pagination"`.
+- `PaginationContent` — `<ul>` row, `gap-1`. `data-slot="pagination-content"`.
+- `PaginationItem` — `<li>` wrapper. `data-slot="pagination-item"`.
+- `PaginationLink` — a page number: `size-10` circle `<a>`. `data-slot="pagination-link"`, `data-active`.
+- `PaginationPrevious` / `PaginationNext` — chevron links rendered as tertiary icon Buttons (`variant="tertiary" size="icon-md"`, 20px chevrons). `data-slot="pagination-link"`.
+- `PaginationEllipsis` — non-interactive `size-10` cell with `MoreHorizontalIcon` + sr-only "More pages". `data-slot="pagination-ellipsis"`.
+
+## API
+
+### PaginationLink
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `isActive` | `boolean` | — | Sets `aria-current="page"` and the brand-selected fill/border/ink. |
+
+`PaginationPrevious`/`PaginationNext` accept `<a>` props (`href`, etc.); the aria-labels "Go to previous page"/"Go to next page" are built in.
+
+## Variants & sizes
+
+One size: 40px circular cells.
+
+```tsx
+import {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+} from "@trading-game/design-intelligence-layer"
+
+<Pagination>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious href="?page=1" /></PaginationItem>
+    <PaginationItem><PaginationLink href="?page=1">1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationLink href="?page=2" isActive>2</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationEllipsis /></PaginationItem>
+    <PaginationItem><PaginationLink href="?page=9">9</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationNext href="?page=3" /></PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- rest page: transparent fill and border, `text-text-prominent-default`, hover `bg-background-hover-default`
+- active page: `bg-background-brand-selected` + `border-border-brand-selected` + `text-text-brand-selected` (light: 10% brand tint + blue-600 ink; dark: solid #121A55 + blue-200 ink + blue-300 border)
+- focus: 3px `ring-ring-focus-strong`
+- prev/next inherit the tertiary Button recipe
+
+**Type (private):** `--pagination-*`: 14 / semibold / 20 (`type-pagination`, `font-display`).
+
+## Behaviour
+
+- Pure links — no internal state; the consumer renders the right `isActive` page and hrefs.
+- `isActive` drives both `aria-current="page"` and `data-active` plus the selected paint.
+- Every cell carries a border (transparent at rest) so the active border-color change never shifts layout.
+- Prev/next are real Buttons via `asChild`, so they inherit Button's hover/press/disabled behaviour.
+
+## Do / Don't
+
+**Do**
+- Keep cells 40px circles (`size-10 rounded-full`) — buttons/chips round fully in this system.
+- Use `PaginationEllipsis` for gaps; it stays non-interactive and announces "More pages" to screen readers.
+- Render page numbers at the token type: 14/semibold/20 — semibold is the ceiling.
+
+**Don't**
+- Don't restyle the active cell with raw brand fills; the brand-selected trio is the selection contract, and dark theme is not a mirror.
+- Don't turn page links into `<button>`s when they change the URL — they are navigation.
+- Don't drop the transparent rest border; you'll get a 1px jump when the active ring appears.

package/docs/components/popover.md

@@ -0,0 +1,89 @@
+# Popover
+
+Click-opened floating card for small interactive surfaces — filters, quick settings, confirm-lite content.
+
+## When to use
+
+- Small interactive panels anchored to a trigger: column pickers, mini forms, share sheets.
+
+**When not:** For hover-only previews use [Hover Card](./hover-card.md). For command lists use a dropdown menu. For flows needing full attention use a Dialog.
+
+## Anatomy
+
+- `Popover` — Radix root. `data-slot="popover"`.
+- `PopoverTrigger` — the opening control. `data-slot="popover-trigger"`.
+- `PopoverContent` — portalled card: 288px (`w-72`), `rounded-2xl`, `p-4`, hairline border, no shadow. `data-slot="popover-content"`.
+- `PopoverAnchor` — optional custom anchor. `data-slot="popover-anchor"`.
+- `PopoverHeader` — title + description stack, `gap-1`. `data-slot="popover-header"`.
+- `PopoverTitle` — 14/medium/20 heading. `data-slot="popover-title"`.
+- `PopoverDescription` — 14/regular/20 subtle copy. `data-slot="popover-description"`.
+
+## API
+
+### Popover (root)
+
+Radix `Popover.Root` props: `open`, `defaultOpen`, `onOpenChange`, `modal`.
+
+### PopoverContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `align` | `"start" \| "center" \| "end"` | `"center"` | |
+| `sideOffset` | `number` | `4` | Gap to the anchor in px. |
+
+Other Radix `Popover.Content` props (`side`, `collisionPadding`, …) pass through. Header/Title/Description take only element props plus `className`.
+
+## Variants & sizes
+
+No variants; one `w-72` card — widen via `className` when the content demands it.
+
+```tsx
+import {
+  Popover,
+  PopoverTrigger,
+  PopoverContent,
+  PopoverHeader,
+  PopoverTitle,
+  PopoverDescription,
+  Button,
+} from "@trading-game/design-intelligence-layer"
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="secondary">Chart settings</Button>
+  </PopoverTrigger>
+  <PopoverContent align="end">
+    <PopoverHeader>
+      <PopoverTitle>Chart settings</PopoverTitle>
+      <PopoverDescription>Applies to this chart only.</PopoverDescription>
+    </PopoverHeader>
+    {/* controls */}
+  </PopoverContent>
+</Popover>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- card: `bg-background-primary-surface` (solid), `border-border-default-default`, ink `text-text-prominent-default`
+- title `text-text-prominent-default`; description `text-text-subtle-default`
+
+**Type (private):** `--popover-title-*`: 14 / medium / 20; `--popover-description-*`: 14 / regular / 20. (The base `--popover`/`--popover-foreground` aliases map to primary surface / prominent ink.)
+
+## Behaviour
+
+- Radix popover semantics: opens on trigger click, closes on outside click and Escape, focus moves into the content.
+- Content is portalled and animated (fade + 95% zoom + side-aware slide) from the trigger's transform origin.
+- The card shell is the system overlay-card recipe: `rounded-2xl` (18px), hairline border, solid surface, **no shadow**.
+
+## Do / Don't
+
+**Do**
+- Use `PopoverTitle`/`PopoverDescription` for headings — 14/medium and 14/regular subtle are the fixed pair.
+- Keep the trigger a real focusable control (`asChild` with a Button).
+- Use `align`/`sideOffset` rather than margin hacks to position the card.
+
+**Don't**
+- Don't add `shadow-*` classes — surfaces are solid and shadowless by law; the hairline is the depth cue.
+- Don't shrink the 18px radius to menu radius; popovers are cards, not menus.
+- Don't stack a popover inside a hover card; pick the interaction model that fits.

package/docs/components/profile-photo.md

@@ -0,0 +1,81 @@
+# Profile Photo
+
+Page-level profile photo with a verification progress ring, photo-change button, and status badge slot.
+
+## When to use
+
+- Account/profile pages where the photo carries verification progress and a change affordance.
+
+**When not:** For identity chips in lists, nav, and comments use Avatar (24–48px) — ProfilePhoto is a fixed 112px page element, not a list glyph.
+
+## Anatomy
+
+- `ProfilePhoto` — the 112px composite. `data-slot="profile-photo"`, `data-progress`, `data-complete`.
+- Ring — SVG track + progress circle, 5px stroke flush to the outer edge, 3px gap to the photo. Progress arc: `data-slot="profile-photo-ring"`.
+- Photo — 96px circle (`data-slot="profile-photo-image"`); placeholder is a secondary-surface tile with a 40px `User` glyph.
+- Camera button — 24px primary icon Button (`data-slot="profile-photo-camera"`), hit area extended to ~44px via `after:-inset-2.5`.
+- Status slot — centred over the bottom edge (`data-slot="profile-photo-status"`); pass a `Badge`.
+
+## API
+
+### ProfilePhoto
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `src` | `string` | — | Photo URL; omit for the placeholder glyph. |
+| `alt` | `string` | `""` | Ignored when there is no `src`. |
+| `progress` | `number` | `0` | Verification progress 0–100, clamped; drives the ring arc. |
+| `onPhotoChange` | `() => void` | — | Shows the camera button; omit to hide it entirely (read-only contexts). |
+| `photoChangeLabel` | `string` | `"Change photo"` | aria-label for the camera button. |
+| `status` | `ReactNode` | — | Rendered overlapping the bottom edge; positioned, not styled — pass a `Badge`. |
+
+`children` is excluded; other `div` props pass through.
+
+## Variants & sizes
+
+No variants; fixed geometry — 112px box, 96px photo, 5px ring, 3px gap.
+
+```tsx
+import { ProfilePhoto, Badge } from "@trading-game/design-intelligence-layer"
+
+<ProfilePhoto
+  src="/players/fahad.jpg"
+  alt="Fahad"
+  progress={60}
+  onPhotoChange={openUploader}
+  status={<Badge variant="warning">Verifying</Badge>}
+/>
+
+// Read-only, unverified placeholder:
+<ProfilePhoto progress={0} />
+```
+
+## Tokens
+
+**Colour (semantic):**
+- ring track: `var(--border-default-default)` (SVG stroke)
+- progress arc: `var(--background-brand-default)`; at 100%: `var(--text-success-default)`
+- placeholder tile: `bg-background-secondary-surface` + `text-icon-subtle-default` glyph
+- camera chip: primary Button recipe with a 2px `border-prominent` ring against the photo
+
+**Type (private):** none — no text of its own.
+
+## Behaviour
+
+- `progress` is clamped to 0–100; `data-complete` appears at ≥100 and swaps the arc stroke to the win colour.
+- The arc starts and ends at 6 o'clock (SVG rotated 90°) so its seam hides behind the status badge, and animates between values (`transition-[stroke-dashoffset,stroke] duration-open ease-enter`, disabled under `motion-reduce`).
+- The stroke path radius is inset by half the stroke (r = 53.5) so the 5px ring stays inside the 112px box.
+- The camera button renders only when `onPhotoChange` is provided; at 24px it stays subordinate to the photo while the `::after` hit area meets the ~44px touch minimum.
+- The status node is positioned (`-bottom-1`, centred) but never styled — content is the consumer's Badge.
+
+## Do / Don't
+
+**Do**
+- Pass a system `Badge` into `status`; the component only owns its position.
+- Omit `onPhotoChange` for viewers who cannot change the photo — hiding the button is the API, not CSS.
+- Provide `alt` whenever `src` is set.
+
+**Don't**
+- Don't resize the composite; 112/96/5/3 is fixed geometry, and Avatar covers the small sizes.
+- Don't recolour the ring track or arc — border-default track, brand arc, win at 100% is the verification vocabulary.
+- Don't put arbitrary content in `status`; a long node will collide with the ring seam it is meant to cover.

package/docs/components/progress.md

@@ -0,0 +1,60 @@
+# Progress
+
+Determinate progress bar — a brand wash track with a solid brand indicator.
+
+## When to use
+
+- Showing completion of a known-length process: upload progress, profile completeness, step progress.
+
+**When not:** For unknown-length waits use Spinner or Skeleton. For circular verification progress on a profile use [Profile Photo](./profile-photo.md).
+
+## Anatomy
+
+- `Progress` — Radix `Progress.Root` track: `h-2` (8px), `rounded-2xs`, overflow hidden. `data-slot="progress"`.
+- Indicator — full-size bar translated left by the remaining percentage. `data-slot="progress-indicator"`.
+
+## API
+
+### Progress
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `number \| null` | — | 0–100. `null`/`undefined` renders as 0 (indicator fully translated out). |
+
+Other Radix `Progress.Root` props (`max`, `getValueLabel`, …) pass through; note the fill math reads `value` directly against 100.
+
+## Variants & sizes
+
+No variants; one 8px bar. Width is fluid (`w-full`).
+
+```tsx
+import { Progress } from "@trading-game/design-intelligence-layer"
+
+<Progress value={66} />
+<Progress value={verifiedSteps * 25} className="max-w-xs" />
+```
+
+## Tokens
+
+**Colour (semantic):**
+- track: `bg-background-secondary-surface` — the shared track spec (h-2, rounded-full), same as Slider
+- indicator: `bg-background-brand-default`, solid
+
+**Type (private):** none.
+
+## Behaviour
+
+- The indicator is always full-width and is moved with `translateX(-(100 - value)%)`, so value changes animate smoothly via `transition-all`.
+- `value || 0` means null/undefined/0 all show an empty bar — there is no indeterminate animation in this component.
+- Radix provides the `progressbar` role and aria value attributes.
+
+## Do / Don't
+
+**Do**
+- Keep the track as the 20% brand wash — track and fill are the same hue by design, separated by alpha.
+- Constrain width with layout (`max-w-*`) rather than restyling the bar.
+
+**Don't**
+- Don't repaint the pair with grey tracks or gradient fills; brand wash + solid brand is the recipe.
+- Don't fake indeterminate state by animating `value`; use Spinner for unknown durations.
+- Don't change the 8px height or `rounded-2xs` radius per screen; it is a fixed primitive.

package/docs/components/radio-group.md

@@ -0,0 +1,82 @@
+# Radio Group
+
+Pick-one control set — 16px hairline circles that take a brand border and dot when checked.
+
+## When to use
+
+- Mutually exclusive choices, 2–6 options, all visible at once (trade type, duration unit).
+- As the control inside [Field](./field.md) choice cards.
+
+**When not:** For many options use [Native Select](./native-select.md) or Select. For independent on/off choices use Checkbox; for a single toggle use Switch.
+
+## Anatomy
+
+- `RadioGroup` — Radix root, `grid gap-3`; owns value and roving focus. `data-slot="radio-group"`.
+- `RadioGroupItem` — one radio: 16px (`size-4`) circle, hairline border on primary surface. `data-slot="radio-group-item"`.
+- Indicator — centred 8px (`size-2`) brand dot, rendered only when checked. `data-slot="radio-group-indicator"`.
+
+## API
+
+### RadioGroup
+
+Radix `RadioGroup.Root` props: `value`, `defaultValue`, `onValueChange`, `disabled`, `orientation`, `name`, `required`, `loop`.
+
+### RadioGroupItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `value` | `string` | required | The option's value. |
+| …rest | Radix `Item` props | — | `disabled`, `id`, `aria-invalid`, etc. |
+
+## Variants & sizes
+
+No variants; one 16px size.
+
+```tsx
+import {
+  RadioGroup,
+  RadioGroupItem,
+  Label,
+} from "@trading-game/design-intelligence-layer"
+
+<RadioGroup defaultValue="rise" onValueChange={setSide}>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="rise" id="rise" />
+    <Label htmlFor="rise">Rise</Label>
+  </div>
+  <div className="flex items-center gap-2">
+    <RadioGroupItem value="fall" id="fall" />
+    <Label htmlFor="fall">Fall</Label>
+  </div>
+</RadioGroup>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- rest: `border-border-default-default` hairline on `bg-background-primary-surface`
+- checked: `border-background-brand-default` ring + `fill-background-brand-default` dot (surface stays primary — no filled disc)
+- focus: `border-ring-focus-default` + 3px `ring-ring-focus-strong` (control ring)
+- error (`aria-invalid`): `border-border-error-default` + `ring-ring-error-soft`
+
+**Type (private):** none — pair with [Label](./label.md) (14/medium/20).
+
+## Behaviour
+
+- Single-select with roving tabindex: Tab reaches the group once, arrows move and select within it (Radix).
+- Controlled (`value` + `onValueChange`) or uncontrolled (`defaultValue`).
+- Checked state swaps only border and dot — the background never fills; there is no shadow in any state.
+- Disabled items get `cursor-not-allowed` + 50% opacity.
+- Inside a Field choice card, the item's `data-state=checked` is what flips the surrounding `FieldLabel` to the brand-selected card treatment.
+
+## Do / Don't
+
+**Do**
+- Give every item an `id` and a `Label htmlFor` — the label is the touch target that makes 16px circles usable.
+- Put `aria-invalid` on the items and `data-invalid` on the enclosing Field so ring and label ink agree.
+- Use `gap-3` stacking as rendered; wrap each item + label row in a flex row.
+
+**Don't**
+- Don't fill the checked circle's background; brand border + brand dot on primary surface is the checked recipe.
+- Don't add shadows or inner glows to states — hairline, ring, and dot carry everything.
+- Don't manage checked state per-item; the group owns the single value.

package/docs/components/resizable.md

@@ -0,0 +1,79 @@
+# Resizable
+
+Draggable panel groups (wrapping `react-resizable-panels`) for splitting a region into user-adjustable panes.
+
+## When to use
+
+- Side-by-side work areas the user should be able to re-proportion — chart vs. order panel, list vs. detail.
+- Nested horizontal/vertical splits in dense desktop layouts.
+
+**When not:** For a fixed navigation column use [Sidebar](./sidebar.md). For a static divider with no drag affordance use [Separator](./separator.md).
+
+## Anatomy
+
+- `ResizablePanelGroup` — flex container, flips to `flex-col` when `aria-orientation="vertical"`; `data-slot="resizable-panel-group"`.
+- `ResizablePanel` — pass-through panel from `react-resizable-panels`; `data-slot="resizable-panel"`.
+- `ResizableHandle` — 1px drag separator (`w-px` / `h-px` horizontal) with an invisible 4px hit area (`after:w-1`); optional grip pill; `data-slot="resizable-handle"`.
+
+## API
+
+### ResizablePanelGroup
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `direction` | `"horizontal" \| "vertical"` | — | Required by `react-resizable-panels`. |
+| ...props | `GroupProps` | — | All library props pass through. |
+
+### ResizablePanel
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `defaultSize` / `minSize` / `maxSize` | `number` | — | Percentages, from the library. |
+| ...props | `PanelProps` | — | Pass-through. |
+
+### ResizableHandle
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `withHandle` | `boolean` | `false` | Renders the grip pill (`h-4 w-3 rounded-xs`, `GripVerticalIcon` at `size-2.5`, rotated 90° when horizontal). |
+
+## Variants & sizes
+
+No cva variants and no size prop — one hairline handle, with or without the grip.
+
+```tsx
+import {
+  ResizablePanelGroup,
+  ResizablePanel,
+  ResizableHandle,
+} from "@trading-game/design-intelligence-layer"
+
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={70}>Chart</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={30}>Positions</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-border-default-default` (handle line and grip fill), `border-border-default-default` (grip border), `text-icon-subtle-default` (grip icon), `ring-ring-focus-default` (keyboard focus, `ring-1` + `ring-offset-1`).
+**Type (private):** none — the component renders no text.
+
+## Behaviour
+
+- Orientation is driven by the library's `aria-orientation` attribute, not a prop on the handle: horizontal groups get a `h-px w-full` handle and the grip rotates 90°.
+- The visible line is 1px; the `after:` pseudo-element widens the pointer target to 4px on the drag axis.
+- Keyboard resize focus uses `ring-1 ring-ring-focus-default ring-offset-1` — a thinner ring than the standard 3px control ring, because the handle itself is only 1px.
+
+## Do / Don't
+
+**Do**
+- Keep the handle at the default 1px hairline — it matches every other divider in the system.
+- Use `withHandle` when the split is a primary interaction; the bare hairline alone is easy to miss.
+- Set `minSize` on panels holding controls so they cannot collapse below usability.
+
+**Don't**
+- Don't thicken or recolour the handle to make it "visible" — the 4px hit area already handles discoverability.
+- Don't add shadows to panels — surfaces are solid and flat everywhere in the system.
+- Don't use Resizable for mobile layouts; drag-resize is a desktop pattern.