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

package/docs/components/button.md

@@ -0,0 +1,94 @@
+# Button
+
+The system's action pill — brand-filled by default, with surface, ghost, on-brand, and glass families plus loading and shimmer modifiers.
+
+## When to use
+
+- Any tap-to-act control: submit, trade, confirm, navigate-as-action.
+
+**When not:** For selectable amount/filter pills use [Chip](./chip.md). For read-only status use [Badge](./badge.md). For menu triggers prefer [Dropdown Menu](./dropdown-menu.md)'s trigger wrapping a Button.
+
+## Anatomy
+
+- `Button` — single element (`button`, or `Slot` with `asChild`); `data-slot="button"`, plus `data-variant`, `data-size`, `data-loading`, `data-shimmer`.
+- Shimmer layer — an absolutely positioned gradient sweep span, rendered under the label.
+- Loading layer — children go invisible (width preserved), a centred `Spinner` overlays.
+- `buttonVariants` — exported cva for composing button classes onto other elements (Calendar does this).
+
+## API
+
+### Button
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"primary" \| "secondary" \| "tertiary" \| "primary-on-brand" \| "secondary-on-brand" \| "tertiary-on-brand" \| "frosted" \| "frosted-on-brand"` | `"primary"` | See variants below. |
+| `size` | `"sm" \| "md" \| "lg" \| "icon" \| "icon-xs" \| "icon-sm" \| "icon-md" \| "icon-lg"` | `"md"` | Text rail 32/40/48; icon circles 24/32/40/48 (`icon` = 48, same as `icon-lg`). |
+| `loading` | `boolean` | `false` | Spinner overlay, `aria-busy`, pointer-events off, opacity 24%. |
+| `shimmer` | `boolean` | `false` | Attention sweep; primary family only (`primary`, `primary-on-brand`) — ignored elsewhere with a dev warning. |
+| `asChild` | `boolean` | `false` | Merge styling onto one child element. Shimmer and loading are unavailable in this mode (Slot takes exactly one child). |
+| `variant` (deprecated) | `"primary-inverse" \| "primary-shimmer" \| "primary-on-brand-shimmer" \| "primary-inverse-shimmer" \| "secondary-inverse" \| "tertiary-inverse"` | — | @deprecated — removed at v1.0. `*-inverse` → the `*-on-brand` family; `*-shimmer` → the `shimmer` boolean. |
+
+## Variants & sizes
+
+```tsx
+import { Button } from "@trading-game/design-intelligence-layer"
+
+<Button>Trade now</Button>
+<Button variant="secondary">Cancel</Button>
+<Button variant="tertiary" size="sm">Details</Button>
+<Button shimmer>Claim bonus</Button>
+<Button loading>Placing order</Button>
+<Button variant="frosted">On page surfaces</Button>
+<Button variant="frosted-on-brand">On artwork</Button>
+<Button variant="primary-on-brand">On a brand panel</Button>
+<Button size="icon-md" aria-label="Settings"><SettingsIcon /></Button>
+```
+
+| Variant | Surface | Ink |
+| --- | --- | --- |
+| `primary` | `background-brand-default`, hover `-hover`, press `-pressed` | `text-on-brand-static` |
+| `secondary` | `background-primary-surface` + hairline border, hover `background-secondary-surface` | `text-prominent-default` |
+| `tertiary` | transparent, hover `background-hover-default` | `text-prominent-default` |
+| `primary-on-brand` | `background-static-white`, hover white/80 | `text-brand-default` |
+| `secondary-on-brand` | transparent + white border, hover white-alpha-8 | `text-on-brand-static` |
+| `tertiary-on-brand` | transparent, hover white-alpha-8 | `text-on-brand-static` |
+| `frosted` | `background-brand-selected` tint; hover/pressed = the state-layer glazes over the solid fill | `text-brand-selected` |
+| `frosted-on-brand` | white-alpha-24 frost + blur, hover 32, press 16 | `text-on-brand-static` |
+
+Use `frosted` for quiet brand-tinted actions on page surfaces — stepper −/+ circles, quick utility buttons that shouldn't shout like `primary`. Use `frosted-on-brand` for the same job on art/hero/brand surfaces. One family, surface picks the name (`glass` is its @deprecated alias, deleted at v1.0).
+
+| Size | Height | Padding-x | Type | Icon |
+| --- | --- | --- | --- | --- |
+| `sm` | 32px | 12px | 14/semibold/20 | 14px |
+| `md` | 40px | 16px | 16/semibold/24 | 16px |
+| `lg` | 48px | 20px | 18/semibold/24 | 20px |
+
+Padding-x = height/2 − 4; gap fixed at 8px and padding does not change when icons are absent. Icon buttons are true circles: `icon-xs` 24, `icon-sm` 32, `icon-md` 40, `icon`/`icon-lg` 48.
+
+## Tokens
+
+**Colour (semantic):** `background-brand-default/-hover/-pressed`, `text-on-brand-static`, `background-primary-surface`, `background-secondary-surface`, `border-border-default-default`, `text-prominent-default`, `background-hover-default`, `background-static-white`, `text-brand-default`, `border-error-default` + `ring-error-soft` (aria-invalid), `ring-focus-strong`; alpha primitives `--primitive-white-alpha-8/16/24/32` for on-brand/glass glazes only.
+**Type (private):** `--button-font-size/line-height-{lg,md,sm}` = 18/24, 16/24, 14/20; `--button-font-weight` = semibold (600).
+
+## Behaviour
+
+- All shapes are `rounded-full`; icon sizes are perfect circles.
+- Focus: `focus-visible:ring-[3px] ring-ring-focus-strong` + focus border. Disabled: `opacity-24`, pointer-events off.
+- Shimmer is a 4s looping gradient sweep — white over `primary`, brand-blue over `primary-on-brand` (white would vanish on white). It is suppressed while `loading` or `disabled` so the button reads as inert.
+- `loading` keeps the button's width: children render invisible, the spinner centres on top, sized per button size.
+- `asChild` passes children straight into Slot — the shimmer/loading layers physically cannot render there.
+- Deprecated `*-shimmer` variants imply `shimmer` for back-compat; `*-inverse` names alias the on-brand styles. All deleted at v1.0.
+- The `.type-button-*` classes are plain CSS and beat `font-*` utilities; the `active:opacity-60` press dim is replaced by the pressed fill on `primary` and by thinner frost on `glass`.
+
+## Do / Don't
+
+**Do**
+- Default to `md` (40px); reserve `lg` for the screen's single headline CTA.
+- Use the on-brand family on brand/coloured panels — never the theme-dependent variants there.
+- Give icon-only buttons an `aria-label`.
+
+**Don't**
+- Don't use the deprecated `*-inverse` / `*-shimmer` variants in new code — they are deleted at v1.0.
+- Don't apply `shimmer` outside the primary family; it is ignored and warns.
+- Don't override the pill radius or add shadows; buttons are flat, full-round pills.
+- Don't change horizontal padding when hiding icons — the rail keeps 12/16/20 regardless.

package/docs/components/calendar.md

@@ -0,0 +1,74 @@
+# Calendar
+
+Date and date-range picker built on react-day-picker, restyled with circular day cells and the system's themed dropdowns.
+
+## When to use
+
+- Picking expiry dates, statement ranges, or tournament windows — single dates or ranges.
+
+**When not:** For choosing from a short list of preset periods use [Chip](./chip.md) rows or a Select. Embed the calendar in a Popover for input-triggered pickers.
+
+## Anatomy
+
+- `Calendar` — configured `DayPicker`; root gets `data-slot="calendar"`, panel is `w-fit`, `p-3`, cell size `--cell-size` = 32px. Background goes transparent inside `card-content` and `popover-content`.
+- Nav — an absolute strip over the caption using `pointer-events-none`, with the arrow Buttons re-enabling their own hits so clicks pass through to the caption dropdowns beneath.
+- `CalendarDropdown` (internal `components.Dropdown`) — themed Select replacing the native month/year `<select>`; popper-positioned panel, `max-h-64`.
+- `CalendarDayButton` — exported day cell: a tertiary icon Button, circular, with today/selected/range modifiers via data attributes.
+
+## API
+
+### Calendar
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `showOutsideDays` | `boolean` | `true` | Outside days render in disabled ink. |
+| `captionLayout` | DayPicker layout | `"label"` | `"dropdown"` swaps in the themed Selects. |
+| `buttonVariant` | Button variant | `"secondary"` | Variant for the prev/next arrows. |
+| `mode`, `selected`, `onSelect`, … | DayPicker props | — | Full react-day-picker API passes through, as do `classNames`, `components`, `formatters`. |
+
+### CalendarDayButton
+
+Receives react-day-picker's `day` and `modifiers`; exposed for custom `components.DayButton` composition.
+
+## Variants & sizes
+
+One visual variant; caption layout is the axis.
+
+```tsx
+import { Calendar } from "@trading-game/design-intelligence-layer"
+
+<Calendar mode="single" selected={date} onSelect={setDate} />
+<Calendar mode="range" selected={range} onSelect={setRange} captionLayout="dropdown" />
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` (panel), `text-text-prominent-default` (caption, days), `text-text-subtle-default` (weekdays, week numbers), `text-text-disabled-default` (outside/disabled days), `background-hover-default` (day hover glaze), `--background-brand-container` + `text-text-brand-container-static` (selected day and range band — the static icy recipe, painted via `[background:var(…)]`), `text-text-brand-default` + `background-brand-default` (today's number and dot), `icon-subtle-default` (dropdown chevron), `ring-focus-strong` (focus).
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--calendar-caption-*` | 14 / semibold (600) / 20 |
+| `--calendar-weekday-*` | 12 / medium (500) / 16 |
+| `--calendar-day-*` | 14 / regular (400) / 20 |
+
+## Behaviour
+
+- Day cells are circular (tertiary icon Buttons). Selection paints the static icy `--background-brand-container` via arbitrary `background` — a `bg-*` utility cannot override it — with `text-brand-container-static` ink and semibold numerals.
+- Ranges: circular start/end (rounded-l/r-full, semibold), square middles (`rounded-none`), all on the same icy band; first/last cells in a row re-round via row selectors.
+- Today (unselected) keeps the regular cell but takes brand ink, semibold, and a 4px brand dot centred below the numeral.
+- `CalendarDropdown` replaces the native selects with the themed Select: `position="popper"` content so the panel scrolls in place, and fixed trigger widths — `w-20` for months, `w-24` for years — so the `w-fit` panel never resizes between "Jan" and "Sep" or 999 and 2026.
+- The nav strip overlays the caption with `pointer-events-none`; only the arrow buttons (`pointer-events-auto`) catch clicks, so the dropdowns underneath stay clickable.
+- Focused days are programmatically focused (`modifiers.focused` → `ref.focus()`), and RTL flips the nav chevrons.
+
+## Do / Don't
+
+**Do**
+- Use `captionLayout="dropdown"` for far-past/future dates (date of birth, statements).
+- Keep the 32px `--cell-size`; resize via that variable, not per-cell classes.
+- Host in a Popover or Card — the calendar background auto-clears there.
+
+**Don't**
+- Don't restyle selected days with `bg-*` utilities — the icy container is painted via `background` and will win.
+- Don't theme the selection per colour scheme by hand; `--background-brand-container` is the static recipe on purpose.
+- Don't square the day cells; circles (and square range middles) are the system shape.

package/docs/components/card.md

@@ -0,0 +1,79 @@
+# Card
+
+The shared surface shell — card surface, hairline border, 18px radius, flat — with slotted header, content, and footer.
+
+## When to use
+
+- Grouping related content on a page: positions, game tiles, stats, settings sections.
+- `variant="frosted-on-brand"` for cards sitting over hero or game artwork.
+
+**When not:** For modal content use [Dialog](./dialog.md). For a painted promotional panel use [Banner](./banner.md).
+
+## Anatomy
+
+- `Card` — the shell: `rounded-2xl` (18px), `py-4`, `gap-4`, no horizontal padding of its own; `data-slot="card"`, `data-variant`.
+- `CardHeader` — grid with `px-4`; becomes two-column when a `CardAction` is present; `data-slot="card-header"`.
+- `CardTitle` — `.h6` foundation style; `data-slot="card-title"`.
+- `CardDescription` — `.body-sm` in subtle ink; `data-slot="card-description"`.
+- `CardAction` — top-right slot spanning both header rows; `data-slot="card-action"`.
+- `CardContent` — `px-4` body; `data-slot="card-content"`.
+- `CardFooter` — `px-4` flex row; `data-slot="card-footer"`.
+
+## API
+
+### Card
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "frosted-on-brand"` | `"default"` | Glass = white-alpha-80 + blur-xl + white-alpha-64 hairline, static black ink, identical in both themes. |
+| `interactive` | `boolean` | `false` | Desktop-only hover lift: `sm:hover:-translate-y-0.75`, disabled under `motion-reduce`. |
+
+All slots take `div` props plus `className`.
+
+## Variants & sizes
+
+No size prop — cards size to their grid.
+
+```tsx
+import {
+  Card, CardHeader, CardTitle, CardDescription,
+  CardAction, CardContent, CardFooter, Button,
+} from "@trading-game/design-intelligence-layer"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Open positions</CardTitle>
+    <CardDescription>3 active trades</CardDescription>
+    <CardAction><Button variant="tertiary" size="sm">View all</Button></CardAction>
+  </CardHeader>
+  <CardContent>…</CardContent>
+  <CardFooter>…</CardFooter>
+</Card>
+
+<Card variant="frosted-on-brand" interactive>…</Card>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` + `border-border-default-default` + `text-text-prominent-default` (default), `text-text-subtle-default` (description); glass uses alpha primitives `--primitive-white-alpha-80` (fill) and `--primitive-white-alpha-64` (hairline) with `text-static-black` — the sanctioned alpha-for-glass exception.
+**Type (private):** none — the title and description ride the foundation `.h6` and `.body-sm` classes.
+
+## Behaviour
+
+- Cards ship blank: the shell has vertical `py-4` only; every slot brings its own `px-4`. Content placed directly in `Card` without a slot will touch the edges.
+- `CardHeader` switches to `grid-cols-[1fr_auto]` only when it contains a `data-slot="card-action"` child.
+- Adding utility classes `.border-b` on the header / `.border-t` on the footer also adds the matching `pb-4` / `pt-4`.
+- `interactive` lifts 3px on hover at `sm+` only — no lift on touch; `motion-reduce` turns it off entirely.
+- Glass is theme-independent by nature: same frost in light and dark.
+
+## Do / Don't
+
+**Do**
+- Use the slots — they carry the 16px gutters.
+- Reserve `interactive` for cards that are themselves a single click target.
+- Put glass cards only over imagery; on plain surfaces use the default.
+
+**Don't**
+- Don't add shadows — flat surfaces with hairlines are the elevation model.
+- Don't change the 18px (`rounded-2xl`) radius; cards and dialogs share it.
+- Don't use alpha fills on default cards; solids only — alpha is reserved for the glass variant.

package/docs/components/carousel.md

@@ -0,0 +1,82 @@
+# Carousel
+
+Embla-powered slide track with previous/next controls, horizontal or vertical.
+
+## When to use
+
+- Browsing peer content that overflows the viewport: game tiles, promo cards, market highlights.
+
+**When not:** For content the user must compare side by side, use a grid. For sequential steps use Stepper.
+
+## Anatomy
+
+- `Carousel` — context provider + `role="region"` wrapper with arrow-key handling; `data-slot="carousel"`.
+- `CarouselContent` — the overflow-hidden viewport and flex track (`-ml-4` / `-mt-4` gutter offset); `data-slot="carousel-content"`.
+- `CarouselItem` — one slide, `basis-full` with `pl-4` / `pt-4` gutter, `role="group" aria-roledescription="slide"`; `data-slot="carousel-item"`.
+- `CarouselPrevious` / `CarouselNext` — circular icon Buttons positioned outside the track (−48px on the travel axis); `data-slot="carousel-previous"` / `"carousel-next"`.
+- `CarouselApi` — exported Embla API type for `setApi`.
+
+## API
+
+### Carousel
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Sets the Embla axis. |
+| `opts` | `EmblaOptionsType` | — | Passed straight to Embla (`loop`, `align`, …). |
+| `plugins` | Embla plugins | — | e.g. autoplay. |
+| `setApi` | `(api: CarouselApi) => void` | — | Escape hatch to the Embla instance. |
+
+### CarouselPrevious / CarouselNext
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | Button variant | `"secondary"` | Any [Button](./button.md) variant. |
+| `size` | Button size | `"icon-md"` | 40px circle. |
+
+## Variants & sizes
+
+Slide width is set on the item, not by a prop.
+
+```tsx
+import {
+  Carousel, CarouselContent, CarouselItem,
+  CarouselPrevious, CarouselNext,
+} from "@trading-game/design-intelligence-layer"
+
+<Carousel opts={{ align: "start", loop: true }}>
+  <CarouselContent>
+    <CarouselItem className="basis-1/3">…</CarouselItem>
+    <CarouselItem className="basis-1/3">…</CarouselItem>
+    <CarouselItem className="basis-1/3">…</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Tokens
+
+**Colour (semantic):** none of its own — the arrows inherit the secondary Button tokens (`background-primary-surface`, `border-border-default-default`, `text-prominent-default`); the track paints nothing.
+**Type (private):** none.
+
+## Behaviour
+
+- Any part outside `<Carousel>` throws (`useCarousel must be used within a <Carousel />`).
+- Arrow buttons disable themselves at the ends (`canScrollPrev/Next` from Embla `select`/`reInit` events); with `loop: true` they never disable.
+- ArrowLeft/ArrowRight are captured on the wrapper and scroll the track.
+- Vertical orientation rotates the arrows 90° and places them above/below the track.
+- Slide gutter is a fixed 16px built from the `-ml-4`/`pl-4` pair — adjust both together if you must change it.
+- `setApi` exposes the raw Embla instance for dots, autoplay, or scroll-to.
+
+## Do / Don't
+
+**Do**
+- Set slide width with `basis-*` on `CarouselItem` (`basis-1/3`, `md:basis-1/4`).
+- Keep the default `secondary` / `icon-md` arrows — 40px circles on the size rail.
+- Reposition the absolute arrows when the carousel sits flush to a container edge.
+
+**Don't**
+- Don't hide the arrows without providing another affordance (drag alone is not discoverable on desktop).
+- Don't restyle the arrows as squares; icon buttons are circles system-wide.
+- Don't nest a carousel inside another carousel on the same axis.

package/docs/components/checkbox.md

@@ -0,0 +1,66 @@
+# Checkbox
+
+Binary (or indeterminate) form control that fills brand blue when checked.
+
+## When to use
+
+- Multi-select lists, opt-ins, terms acceptance — anywhere several options can be on at once.
+
+**When not:** For a single on/off setting with immediate effect use Switch. For mutually exclusive options use Radio Group. For pill-shaped multi-select filters use [Chip](./chip.md).
+
+## Anatomy
+
+- `Checkbox` — the only export; Radix root, 16px square, `rounded-2xs`; `data-slot="checkbox"`.
+- Indicator — internal `CheckboxPrimitive.Indicator` with a 14px `CheckIcon`; `data-slot="checkbox-indicator"`.
+
+## API
+
+### Checkbox
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `checked` | `boolean \| "indeterminate"` | — | Controlled state. |
+| `defaultChecked` | `boolean` | — | Uncontrolled initial state. |
+| `onCheckedChange` | `(checked) => void` | — | Radix change callback. |
+| `disabled` | `boolean` | `false` | `cursor-not-allowed`, opacity 50%. |
+| `required`, `name`, `value` | form props | — | Radix renders a hidden input inside forms. |
+
+## Variants & sizes
+
+One variant, one size (16px).
+
+```tsx
+import { Checkbox } from "@trading-game/design-intelligence-layer"
+
+<label className="flex items-center gap-2">
+  <Checkbox defaultChecked />
+  Accept the terms
+</label>
+
+<Checkbox checked={all ? true : some ? "indeterminate" : false} onCheckedChange={toggleAll} />
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` + `border-border-default-default` (unchecked), `background-brand-default` + `text-text-on-brand-static` with transparent border (checked), `ring-focus-strong` + `border-ring-focus-default` (focus).
+**Type (private):** none — the control renders no text.
+
+## Behaviour
+
+- Checked swaps the hairline for a solid brand fill (`data-[state=checked]`); the check glyph rides `text-current`, so it is static white ink.
+- Works controlled or uncontrolled via Radix; supports `"indeterminate"`.
+- The root carries `peer`, so labels/siblings can react with `peer-*` selectors.
+- Radius is `rounded-2xs` — one step below the 4px input radius, deliberate at this 16px scale.
+- Focus is the standard control ring: `focus-visible:ring-[3px] ring-ring-focus-strong`.
+
+## Do / Don't
+
+**Do**
+- Wrap in a `<label>` or pair with `htmlFor` — the 16px box alone is too small a target.
+- Use `"indeterminate"` for parent rows over partially selected children.
+- Keep the brand fill; checked state is solid, not tinted.
+
+**Don't**
+- Don't scale the box past 16px with `className` size hacks — layout assumes `size-4`.
+- Don't restyle checked with selection-state tokens; checkbox uses the brand fill, not the brand-selected family.
+- Don't use a checkbox where the change applies instantly — that is Switch.

package/docs/components/chip.md

@@ -0,0 +1,72 @@
+# Chip
+
+Pressable pill for quick amounts and category filters — one shape, four jobs: default, selected, outline (error recovery), disabled.
+
+## When to use
+
+- Quick-amount rows (10.00 / 50.00 / 100.00), category filters, and the "Max 1,240.50" recovery chip after an over-limit entry.
+
+**When not:** Live-status pills belong to [Badge](./badge.md). Actions that submit or navigate belong to [Button](./button.md).
+
+## Anatomy
+
+- `Chip` — a single `<button type="button">`; `data-slot="chip"`, `data-size`, `data-variant`, `data-selected`, `aria-pressed`.
+- `chipVariants` — exported cva (size axis only) for composition.
+
+## API
+
+### Chip
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `selected` | `boolean` | `false` | Solid brand fill + static white ink; the chip becomes inert (`pointer-events-none`). |
+| `variant` | `"default" \| "outline"` | `"default"` | `outline` = the brand-outlined error-recovery chip. |
+| `size` | `"md" \| "sm"` | `"md"` | 40px / 32px heights. |
+| `disabled` | `boolean` | `false` | Hairline border, transparent fill, disabled ink. |
+
+## Variants & sizes
+
+```tsx
+import { Chip } from "@trading-game/design-intelligence-layer"
+
+<Chip onClick={() => setAmount(50)}>50.00</Chip>
+<Chip selected>100.00</Chip>
+<Chip variant="outline" onClick={setMax}>Max 1,240.50</Chip>
+<Chip size="sm">Crypto</Chip>
+<Chip disabled>500.00</Chip>
+```
+
+| Size | Height | Padding-x | Type |
+| --- | --- | --- | --- |
+| `md` | 40px | 16px | 14/semibold/20 |
+| `sm` | 32px | 12px | 12/semibold/16 |
+
+## Tokens
+
+**Colour (semantic):**
+- Default: `background-primary-surface` + `border-border-default-default` + `text-prominent-default`; hover `background-secondary-surface`; active `background-secondary-surface/80` glaze.
+- Selected: `background-brand-default` + `text-on-brand-static`, transparent border.
+- Outline: 1.5px `border-border-brand-selected` + `text-text-brand-selected` on `background-primary-surface`; hover `background-hover-default`.
+- Disabled: `border-border-default-default`, transparent fill, `text-disabled-default`.
+- Focus: `ring-focus-strong`.
+
+**Type (private):** `--chip-font-size/line-height-md` = 14/20, `--chip-font-size/line-height-sm` = 12/16, `--chip-font-weight` = semibold (600).
+
+## Behaviour
+
+- `selected` chips are intentionally inert: `pointer-events-none cursor-default` — re-tapping the chosen amount does nothing; selection changes by pressing a different chip. `aria-pressed` reflects the state.
+- The outline variant is the error-recovery affordance — it uses the brand-selected token family (1.5px `border-brand-selected` + `text-brand-selected`), so in dark theme it takes the family's own values (blue-300 border, blue-200 ink) rather than a mirror of light.
+- Always renders `type="button"`, so it never submits forms accidentally.
+- Shape is `rounded-full`; there is no icon slot in the API.
+
+## Do / Don't
+
+**Do**
+- Use `md` (40px) in amount trays; `sm` (32px) for dense filter rows.
+- Reserve `variant="outline"` for recovery actions like "Max …" after a validation error.
+- Drive selection from state — exactly one selected chip per exclusive group.
+
+**Don't**
+- Don't attach `onClick` behaviour that depends on pressing a selected chip — it cannot receive clicks.
+- Don't use Chip for statuses or counts; that is Badge.
+- Don't exceed semibold 600 or swap the pill radius.

package/docs/components/command.md

@@ -0,0 +1,86 @@
+# Command
+
+Filterable command palette built on cmdk — a searchable list of actions, standalone or inside a dialog.
+
+## When to use
+
+- Keyboard-first action launchers (⌘K palettes) and searchable pickers over many options.
+
+**When not:** For a short static action list anchored to a trigger use [Dropdown Menu](./dropdown-menu.md). For right-click actions use [Context Menu](./context-menu.md).
+
+## Anatomy
+
+- `Command` — cmdk root, `rounded-2xl` surface shell; `data-slot="command"`.
+- `CommandDialog` — the palette wrapped in a [Dialog](./dialog.md) with an sr-only header and `p-0` content; resizes rows/input to 48px.
+- `CommandInput` — search field inside a bordered wrapper row (36px standalone, 48px in the dialog) with a leading 16px search icon; `data-slot="command-input"` / `"command-input-wrapper"`.
+- `CommandList` — scrollable results, `max-h-[300px]`; `data-slot="command-list"`.
+- `CommandEmpty` — centred no-results row; `data-slot="command-empty"`.
+- `CommandGroup` — group with a `cmdk-group-heading`; `data-slot="command-group"`.
+- `CommandItem` — result row, `rounded-md`, 16px icons in subtle ink; `data-slot="command-item"`.
+- `CommandShortcut` — right-aligned shortcut hint; `data-slot="command-shortcut"`.
+- `CommandSeparator` — 1px hairline; `data-slot="command-separator"`.
+
+## API
+
+### CommandDialog
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `title` | `string` | `"Command Palette"` | sr-only dialog title. |
+| `description` | `string` | `"Search for a command to run..."` | sr-only description. |
+| `showCloseButton` | `boolean` | `true` | Dialog's circular close X. |
+| `open`, `onOpenChange` | Dialog props | — | Pass through to Dialog. |
+
+### Others
+
+`Command`, `CommandInput`, `CommandList`, `CommandEmpty`, `CommandGroup`, `CommandItem`, `CommandSeparator` take the cmdk primitive props (`value`, `onSelect`, `disabled`, `filter`, `shouldFilter`, …) plus `className`.
+
+## Variants & sizes
+
+One look; standalone vs dialog is the axis.
+
+```tsx
+import {
+  CommandDialog, CommandInput, CommandList, CommandEmpty,
+  CommandGroup, CommandItem, CommandShortcut, CommandSeparator,
+} from "@trading-game/design-intelligence-layer"
+
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput placeholder="Search markets…" />
+  <CommandList>
+    <CommandEmpty>No results.</CommandEmpty>
+    <CommandGroup heading="Markets">
+      <CommandItem onSelect={() => go("/btc")}>BTC/USD<CommandShortcut>⌘1</CommandShortcut></CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Actions">
+      <CommandItem>New trade</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</CommandDialog>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` (shell), `text-prominent-default` (rows), `text-subtle-default` (placeholder, headings, empty, shortcuts), `border-border-default-default` (input hairline, separator), `background-hover-default` (highlighted row via `data-[selected=true]`), `icon-subtle-default` (search and row icons).
+**Type (private):** shared `--menu-*` family — item 14/regular/20, heading 12/medium/16, trigger 14/medium/20, shortcut 12/regular/16. Input and empty ride `type-menu-item`; headings and shortcuts ride `type-menu-heading`.
+
+## Behaviour
+
+- cmdk filters as you type and moves the highlight (`data-[selected=true]` = the hover glaze); Enter fires `onSelect`.
+- `CommandDialog` hides its title/description for screen readers only, strips content padding, and upsizes input and rows to 48px with 20px icons.
+- Rows are `rounded-md` (8px) per the menu-row radius rule; the shell is `rounded-2xl` standalone (the dialog supplies its own 18px shell).
+- Disabled items: `data-[disabled=true]:pointer-events-none opacity-24`.
+- Note the shell radius difference from anchored menus: Command is a modal/embedded surface (18px), while dropdown/context panels are `rounded-lg` (10px).
+
+## Do / Don't
+
+**Do**
+- Always include `CommandEmpty` so filtering dead-ends read intentionally.
+- Group with headings once the list passes ~7 items.
+- Keep shortcut hints in `CommandShortcut` — 12/regular/16, right-aligned.
+
+**Don't**
+- Don't restyle the highlight with selection-state tokens — palette highlight is the hover glaze, not brand-selected.
+- Don't put form controls inside items; rows are single actions.
+- Don't cap `CommandList` taller than 300px without a reason — it is scrollable by design.

package/docs/components/context-menu.md

@@ -0,0 +1,90 @@
+# Context Menu
+
+Right-click (or long-press) menu with items, checkboxes, radios, labels, and nested submenus.
+
+## When to use
+
+- Contextual actions on an object under the pointer: a watchlist row, a chart, a portfolio position.
+
+**When not:** For a menu opened from a visible trigger use [Dropdown Menu](./dropdown-menu.md). For a searchable action list use [Command](./command.md).
+
+## Anatomy
+
+- `ContextMenu` / `ContextMenuTrigger` / `ContextMenuPortal` / `ContextMenuGroup` / `ContextMenuRadioGroup` / `ContextMenuSub` — Radix plumbing, each stamped with its `data-slot` (`context-menu`, `context-menu-trigger`, …).
+- `ContextMenuContent` / `ContextMenuSubContent` — the panel: `rounded-lg` (10px), hairline border, surface fill, `p-1`, `min-w-[8rem]`; content scrolls within the Radix available height.
+- `ContextMenuItem` — action row, `rounded-md` (8px); `data-slot="context-menu-item"`, `data-inset`, `data-variant`.
+- `ContextMenuCheckboxItem` / `ContextMenuRadioItem` — rows with `pl-8` and a left indicator (16px check / 8px filled circle).
+- `ContextMenuLabel` — non-interactive heading; `data-slot="context-menu-label"`.
+- `ContextMenuSeparator` — 1px hairline; `data-slot="context-menu-separator"`.
+- `ContextMenuShortcut` — right-aligned hint; `data-slot="context-menu-shortcut"`.
+- `ContextMenuSubTrigger` — row with trailing chevron; `data-slot="context-menu-sub-trigger"`.
+
+## API
+
+### ContextMenuItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "destructive"` | `"default"` | Destructive = error ink; focus paints the error tint surface. |
+| `inset` | `boolean` | — | `pl-8` to align with indicator rows. |
+| `onSelect`, `disabled` | Radix props | — | Standard item behaviour. |
+
+### ContextMenuCheckboxItem / ContextMenuRadioItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `checked` | `boolean \| "indeterminate"` | — | Checkbox item only. |
+| `value` | `string` | — | Radio item, within `ContextMenuRadioGroup`. |
+
+`ContextMenuSubTrigger` and `ContextMenuLabel` also take `inset`.
+
+## Variants & sizes
+
+One panel size; rows vary by kind.
+
+```tsx
+import {
+  ContextMenu, ContextMenuTrigger, ContextMenuContent, ContextMenuItem,
+  ContextMenuCheckboxItem, ContextMenuSeparator, ContextMenuShortcut,
+  ContextMenuSub, ContextMenuSubTrigger, ContextMenuSubContent,
+} from "@trading-game/design-intelligence-layer"
+
+<ContextMenu>
+  <ContextMenuTrigger>Right-click a position</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Set alert<ContextMenuShortcut>⌘A</ContextMenuShortcut></ContextMenuItem>
+    <ContextMenuCheckboxItem checked>Pin to top</ContextMenuCheckboxItem>
+    <ContextMenuSub>
+      <ContextMenuSubTrigger>Move to list</ContextMenuSubTrigger>
+      <ContextMenuSubContent><ContextMenuItem>Favourites</ContextMenuItem></ContextMenuSubContent>
+    </ContextMenuSub>
+    <ContextMenuSeparator />
+    <ContextMenuItem variant="destructive">Close position</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Tokens
+
+**Colour (semantic):** `background-primary-surface` + `border-border-default-default` (panel), `text-prominent-default` (rows, labels), `background-hover-default` (focused/open row), `icon-subtle-default` (row icons), `text-subtle-default` (shortcuts), `text-error-default` + `background-error-default` (destructive row and its focus tint), `bg-border-default-default` (separator).
+**Type (private):** shared `--menu-*` family — item 14/regular/20, heading 12/medium/16, trigger 14/medium/20, shortcut 12/regular/16.
+
+## Behaviour
+
+- Open state, positioning, typeahead, and keyboard navigation are Radix-managed; content mounts in a portal with fade/zoom/slide animations per side.
+- Focused rows take the hover glaze (`focus:bg-background-hover-default`) — not a brand-selected fill; an open sub-trigger holds the same glaze.
+- Destructive rows keep error ink even on their icons (`*:[svg]:text-text-error-default!`).
+- Disabled rows: `data-[disabled]:pointer-events-none opacity-24`.
+- Radius contract: panel `rounded-lg` 10px, rows `rounded-md` 8px.
+
+## Do / Don't
+
+**Do**
+- Use `inset` on plain items that sit beside checkbox/radio rows so labels align.
+- Put the destructive action last, after a separator.
+- Keep row icons at the default 16px subtle ink.
+
+**Don't**
+- Don't use a context menu as the only way to reach an action — right-click is undiscoverable on touch.
+- Don't restyle row focus with brand-selected tokens; menus highlight with the hover glaze.
+- Don't nest submenus more than one level deep.