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

package/docs/components/input-otp.md

@@ -0,0 +1,87 @@
+# Input OTP
+
+Segmented one-time-code entry — one visual slot per character over a single hidden input.
+
+## When to use
+
+- Verification codes: SMS/email OTPs, 2FA codes, withdrawal confirmation codes.
+
+**When not:** For ordinary short text use [Input](./input.md). OTP slots are for fixed-length codes only.
+
+## Anatomy
+
+- `InputOTP` — wrapper around the `input-otp` library's `OTPInput`; owns `maxLength`, value, and the hidden real input. `data-slot="input-otp"`.
+- `InputOTPGroup` — visually joins consecutive slots (first slot `rounded-l-sm`, last `rounded-r-sm`). `data-slot="input-otp-group"`.
+- `InputOTPSlot` — one character cell, 40px (`size-10`, the md rail); renders the char and a fake blinking caret. `data-slot="input-otp-slot"`, `data-active`.
+- `InputOTPSeparator` — `role="separator"` dash (`MinusIcon`) between groups. `data-slot="input-otp-separator"`.
+
+## API
+
+### InputOTP
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `containerClassName` | `string` | — | Class for the flex container (`gap-2`, 50% opacity when disabled). |
+| …rest | `OTPInput` props | — | `maxLength`, `value`, `onChange`, `pattern`, etc. from the `input-otp` package. |
+
+### InputOTPSlot
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `index` | `number` | required | Which character of the code this cell shows. |
+
+## Variants & sizes
+
+No variants; one 40px slot size.
+
+```tsx
+import {
+  InputOTP,
+  InputOTPGroup,
+  InputOTPSlot,
+  InputOTPSeparator,
+} from "@trading-game/design-intelligence-layer"
+
+<InputOTP maxLength={6}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSlot index={2} />
+  </InputOTPGroup>
+  <InputOTPSeparator />
+  <InputOTPGroup>
+    <InputOTPSlot index={3} />
+    <InputOTPSlot index={4} />
+    <InputOTPSlot index={5} />
+  </InputOTPGroup>
+</InputOTP>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- slot: `bg-background-primary-surface` + `border-border-default-default` (hairline), ink `text-text-prominent-default`
+- active slot: `border-ring-focus-default` + 3px `ring-ring-focus-soft` (the soft text-field ring), lifted with `z-10`
+- caret: `bg-text-prominent-default` (`animate-caret-blink`, 1s)
+- invalid (`aria-invalid`): `border-border-error-default` + `ring-ring-error-soft`, active or not
+
+**Type (private):** `--input-otp-*`: 14 / regular / 20 (`type-input-otp`).
+
+## Behaviour
+
+- State lives in the library's single hidden input; slots read `char`, `isActive`, and `hasFakeCaret` from `OTPInputContext` by `index`.
+- The active slot shows the focus treatment via `data-active=true` — same border/ring pair as Input's focus.
+- Slots inside a group share hairline borders; only the group's outer corners are rounded (`rounded-l-sm`/`rounded-r-sm`).
+- Disabled state dims the whole container to 50% via `has-disabled`.
+
+## Do / Don't
+
+**Do**
+- Match slot count to `maxLength` — indexes 0..maxLength-1, no gaps.
+- Use `InputOTPSeparator` to chunk long codes (3+3 for six digits).
+- Put `aria-invalid` on the OTP input when the code is rejected; error tokens flow to every slot.
+
+**Don't**
+- Don't restyle the caret; the 1px `text-prominent-default` blink is the affordance that the slot is live.
+- Don't give slots the 50% control focus ring — OTP slots are text entry and use the 8% soft ring.
+- Don't add per-slot shadows or fills; hairline on primary surface, solid only.

package/docs/components/input.md

@@ -0,0 +1,71 @@
+# Input
+
+Single-line text control on the 32/40/48 size rail, with a dark-glaze variant for brand surfaces.
+
+## When to use
+
+- Free text, numbers, emails, passwords, file pickers — any single-line `<input>`.
+
+**When not:** For text with leading/trailing addons or inline buttons use [Input Group](./input-group.md). For fixed-length codes use [Input OTP](./input-otp.md). For pick-one dropdowns use [Native Select](./native-select.md).
+
+## Anatomy
+
+- `Input` — the styled `<input>`. `data-slot="input"`, plus `data-variant` and `data-size` reflecting the resolved values.
+- `inputVariants` — exported cva for building lookalike controls.
+
+## API
+
+### Input
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "on-brand" \| "inverse"` | `"default"` | `on-brand` is the sunken treatment for brand-coloured surfaces: `--primitive-black-alpha-32` glaze fill + `--primitive-white-alpha-24` border over whatever brand colour sits underneath. `inverse` @deprecated — alias of `on-brand`, removed at v1.0. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` (or the enclosing Field's size) | sm = `h-8` (32px) px-3, md = `h-10` (40px) px-3, lg = `h-12` (48px) px-4. The native `size` attribute is omitted from the type. |
+
+All other native `<input>` props pass through (`type`, `disabled`, `readOnly`, `aria-invalid`, …).
+
+## Variants & sizes
+
+```tsx
+import { Input } from "@trading-game/design-intelligence-layer"
+
+// Size rail: 32 / 40 / 48.
+<Input size="sm" placeholder="Search" />
+<Input placeholder="Amount" />            {/* md, 40px */}
+<Input size="lg" placeholder="Email" />
+
+// On a brand-coloured hero/panel:
+<Input variant="on-brand" placeholder="Enter amount" />
+```
+
+## Tokens
+
+**Colour (semantic):**
+- default: `border-border-default-default`, `bg-background-primary-surface`, `text-text-prominent-default`, placeholder `text-text-subtle-default`
+- selection: `bg-background-brand-default` + `text-text-on-brand-static`
+- focus: `border-ring-focus-default` + `ring-ring-focus-soft` (the soft text-field ring)
+- read-only: `bg-background-secondary-surface`, border transparent — still focusable, selectable, and copyable
+- invalid (`aria-invalid`): `border-border-error-default` + `ring-ring-error-soft`
+- on-brand (alpha primitives — the sanctioned glaze use): fill `--primitive-black-alpha-32`, border `--primitive-white-alpha-24`, placeholder `--primitive-white-alpha-50`, focus ring `--primitive-white-alpha-40`, ink `text-text-on-brand-static`
+
+**Type (private):** `--input-*` ladder, all regular weight — sm 12/16, md 14/20, lg 16/24 (`type-input-sm|md|lg`).
+
+## Behaviour
+
+- Inside a [Field](./field.md), `useFieldSize()` supplies the default size; an explicit `size` prop on the Input wins.
+- `readOnly` removes the border and switches to the secondary surface — visibly "not editable" while staying focusable and copyable (readonly is reachable, unlike disabled).
+- `disabled` = pointer-events none, `cursor-not-allowed`, 50% opacity.
+- Focus ring is `focus-visible` only — 3px at 8% alpha, the soft variant reserved for text fields.
+- `inverse` renders identically to `on-brand`; it exists only for migration and is deleted at v1.0.
+
+## Do / Don't
+
+**Do**
+- Stay on the rail: 32/40/48 only, default md.
+- Use `variant="on-brand"` on brand-coloured surfaces — the black-alpha glaze works over any brand fill.
+- Let the Field cascade size the input; only set `size` explicitly to override.
+
+**Don't**
+- Don't "fix" the `rounded-xs` (4px) corner — inputs are deliberately the squarest thing in the system.
+- Don't swap the 8% soft focus ring for the 50% control ring; text fields use the soft one.
+- Don't write new code with `variant="inverse"`; it is a deprecated alias.

package/docs/components/item.md

@@ -0,0 +1,105 @@
+# Item
+
+Generic list row — media, title/description, and actions in one flex shell, with auto-divided groups.
+
+## When to use
+
+- Settings rows, notification lists, asset lists, any media + text + action row.
+- Stacks of rows: wrap in `ItemGroup` for automatic hairline dividers.
+
+**When not:** For interactive menus use [Menubar](./menubar.md) or a dropdown. For empty containers use [Empty](./empty.md). For form rows use [Field](./field.md).
+
+## Anatomy
+
+- `ItemGroup` — `role="list"` column; auto-divider mode on by default. `data-slot="item-group"`, `data-divider`.
+- `ItemSeparator` — manual hairline (`Separator`). `data-slot="item-separator"`.
+- `Item` — the row (`rounded-md`, transparent hairline border for state changes). `data-slot="item"`, `data-variant`, `data-size`.
+- `ItemMedia` — leading icon/image slot; top-aligns itself when a description is present. `data-slot="item-media"`, `data-variant`.
+- `ItemContent` — flex-1 column for title + description. `data-slot="item-content"`.
+- `ItemTitle` — 14/medium/20 prominent ink. `data-slot="item-title"`.
+- `ItemDescription` — 14/regular/20 subtle ink, clamped to 2 lines. `data-slot="item-description"`.
+- `ItemActions` — trailing controls. `data-slot="item-actions"`.
+- `ItemHeader` / `ItemFooter` — full-width rows above/below the main line. `data-slot="item-header"` / `"item-footer"`.
+
+## API
+
+### ItemGroup
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `divider` | `boolean` | `true` | Draws a 1px `border-default-default` line (inset `inset-x-4`) after each non-last **default-variant** Item, in a 4px gap. `outline`/`muted` items are skipped so borders don't double. Pass `false` for flush stacks or manual `ItemSeparator`. |
+
+### Item
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "outline" \| "muted"` | `"default"` | default transparent; outline = hairline `border-border-default-default` + hover fill; muted = `bg-background-secondary-surface`. |
+| `size` | `"default" \| "sm"` | `"default"` | default `gap-4 p-4`; sm `gap-2.5 px-4 py-3`. |
+| `asChild` | `boolean` | `false` | Render as link/button via Radix Slot; anchors get `hover:bg-background-hover-default`. |
+
+### ItemMedia
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "icon" \| "image"` | `"default"` | icon = 32px circle, `border-border-default-default` + `bg-background-secondary-surface`, 16px svg, `text-icon-prominent-default`; image = 40px circular crop. |
+
+## Variants & sizes
+
+```tsx
+import {
+  Item,
+  ItemGroup,
+  ItemMedia,
+  ItemContent,
+  ItemTitle,
+  ItemDescription,
+  ItemActions,
+  Button,
+} from "@trading-game/design-intelligence-layer"
+import { BellIcon } from "lucide-react"
+
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="icon"><BellIcon /></ItemMedia>
+    <ItemContent>
+      <ItemTitle>Price alerts</ItemTitle>
+      <ItemDescription>Notify me when Volatility 75 moves 2% in an hour.</ItemDescription>
+    </ItemContent>
+    <ItemActions>
+      <Button variant="secondary" size="sm">Edit</Button>
+    </ItemActions>
+  </Item>
+  <Item variant="outline" size="sm">…</Item>
+</ItemGroup>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- title `text-text-prominent-default`; description `text-text-subtle-default` (links underline, hover `text-text-brand-default`)
+- outline: `border-border-default-default`, hover `bg-background-hover-default`; muted: `bg-background-secondary-surface`
+- group divider: `bg-border-default-default`
+- focus: `border-ring-focus-default` + 3px `ring-ring-focus-strong` (control ring)
+- icon media: `bg-background-secondary-surface` + `text-icon-prominent-default`
+
+**Type (private):** `--item-title-*`: 14 / medium / 20; `--item-description-*`: 14 / regular / 20 (the Item shell itself defaults to the description type).
+
+## Behaviour
+
+- Group dividers are drawn as `::after` elements in the 4px gap — the Item keeps no border of its own, so hover/focus borders don't fight the divider.
+- The last item and any non-default-variant item never get an auto divider.
+- `ItemMedia` shifts down 2px and self-starts when the row contains a description, keeping the icon optically aligned with the title.
+- Descriptions clamp at 2 lines (`line-clamp-2`).
+- `asChild` rows are fully interactive: instant-duration colour transition, hover fill on anchors, 3px/50% focus ring.
+
+## Do / Don't
+
+**Do**
+- Let `ItemGroup` draw dividers; only reach for `ItemSeparator` with `divider={false}`.
+- Use `rounded-md` rows as-is — 8px is the row radius tier.
+- Use `asChild` with a real `<a>`/`<button>` when the whole row navigates.
+
+**Don't**
+- Don't mix `variant="outline"` items into a dividered group expecting dividers — they are deliberately skipped.
+- Don't push the title past medium 500; row titles never reach semibold, and bold does not exist in components.
+- Don't add shadows to muted/outline rows; state is shown by fill and hairline only.

package/docs/components/label.md

@@ -0,0 +1,56 @@
+# Label
+
+Form control label at 14/medium/20 that deliberately inherits its colour.
+
+## When to use
+
+- Labelling any form control by `htmlFor`/nesting — checkboxes, radios, inputs, switches.
+
+**When not:** Inside a [Field](./field.md), use `FieldLabel` — it adds the size ladder and choice-card behaviour on top of Label. For non-label row titles use `FieldTitle` or `ItemTitle`.
+
+## Anatomy
+
+- `Label` — Radix `LabelPrimitive.Root` with system type and disabled handling. `data-slot="label"`. Single part.
+
+## API
+
+### Label
+
+No custom props — all Radix `Label.Root` / native `<label>` props pass through (`htmlFor`, etc.).
+
+## Variants & sizes
+
+No variants; one size, 14/medium/20.
+
+```tsx
+import { Label, Checkbox } from "@trading-game/design-intelligence-layer"
+
+<div className="flex items-center gap-2">
+  <Checkbox id="tnc" />
+  <Label htmlFor="tnc">I accept the terms and conditions</Label>
+</div>
+```
+
+## Tokens
+
+**Colour (semantic):** none set — colour is inherited on purpose, so a parent [Field](./field.md) with `data-invalid` (`text-text-error-default`) paints the label red through inheritance.
+
+**Type (private):** `--label-*`: 14 / medium / 20 (`type-label`).
+
+## Behaviour
+
+- Colour inheritance is the contract: Field's `data-[invalid=true]:text-text-error-default` reaches the label with zero wiring.
+- Disabled affordances: `group-data-[disabled=true]` (pointer-events none + 50% opacity) and `peer-disabled` (`cursor-not-allowed` + 50% opacity) — pair Label with `peer` controls or a `group` wrapper.
+- `select-none`: label text is not selectable, so double-clicks hit the control.
+- Layout is `flex items-center gap-2`, ready to hold a leading control or icon.
+
+## Do / Don't
+
+**Do**
+- Wire `htmlFor` to the control id, or nest the control inside the label.
+- Let disabled state come from the `peer`/`group` mechanics rather than manual opacity.
+
+**Don't**
+- Never force an ink on Label (`text-*` classes) — you would sever the Field error cascade.
+- Don't override the type: 14/medium/20 is fixed, and `.type-label` is plain CSS that beats `font-*` utilities anyway.
+- Don't use Label for non-form headings; it carries `<label>` semantics.

package/docs/components/link.md

@@ -0,0 +1,66 @@
+# Link
+
+Semibold inline navigation — quiet at rest, underline and darker ink arrive on hover.
+
+## When to use
+
+- Navigational text: "View all trades", "Learn more", footer links, links with a trailing arrow icon.
+
+**When not:** For actions that change state use Button. For circular icon-only navigation use [Navigation Button](./navigation-button.md). For links inside menus use [Navigation Menu](./navigation-menu.md)'s `NavigationMenuLink`.
+
+## Anatomy
+
+- `Link` — a styled `<a>` (or Slot via `asChild`); inline-flex with a 6px gap for icons, `font-display normal-case`. `data-slot="link"`, `data-size`, `data-tone`.
+- `linkVariants` — exported cva for composing.
+
+## API
+
+### Link
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"lg" \| "md" \| "sm"` | `"lg"` | lg 16/24, md 14/20, sm 12/16 — all semibold. Icons `size-4` (lg/md) or `size-3.5` (sm). |
+| `tone` | `"brand" \| "on-brand"` | `"brand"` | brand = brand ink darkening one step on hover; on-brand = static white for brand-coloured surfaces, hover `--primitive-white-alpha-80`. |
+| `asChild` | `boolean` | `false` | Compose with a router `<Link>` via Radix Slot. |
+
+## Variants & sizes
+
+```tsx
+import { Link } from "@trading-game/design-intelligence-layer"
+import { ArrowRightIcon } from "lucide-react"
+
+<Link href="/markets">Explore markets <ArrowRightIcon /></Link>   {/* lg 16/24 */}
+<Link size="md" href="/reports">View report</Link>                 {/* 14/20 */}
+<Link size="sm" href="/terms">Terms</Link>                          {/* 12/16 */}
+
+// On a brand-coloured hero:
+<Link tone="on-brand" href="/promo">See offer</Link>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- brand: `text-text-brand-default`, hover `text-text-brand-hover` (ink darkens one step)
+- on-brand: `text-text-on-brand-static`, hover `--primitive-white-alpha-80` (alpha primitive, sanctioned for on-brand surfaces)
+- focus: 3px `ring-ring-focus-strong`
+
+**Type (private):** `--link-*` ladder, all semibold (`--link-font-weight`) — lg 16/24, md 14/20, sm 12/16.
+
+## Behaviour
+
+- Rest state has NO underline — hover adds `underline` (`decoration-2`, `underline-offset-4`) plus the one-step ink darken. Semibold weight is the rest-state affordance.
+- Trailing icon nudge: the last `svg` child slides right 2px (`translate-x-0.5`) on hover.
+- Press feedback is `active:opacity-60`. Anchors have no disabled state — remove the link instead of disabling it.
+- Renders in `font-display` with `normal-case`.
+
+## Do / Don't
+
+**Do**
+- Keep the default lg (16/24) for standalone links; drop to md/sm only to match surrounding body/caption text.
+- Put the arrow icon last so the 2px hover nudge fires.
+- Use `tone="on-brand"` on brand fills instead of overriding inks by hand.
+
+**Don't**
+- Don't underline at rest — the underline is hover feedback in this system.
+- Don't lighten the weight; links are semibold at every size (and 600 is the system max — no bold).
+- Don't use Link for onClick-only actions with no href; that is a Button in link's clothing.

package/docs/components/menubar.md

@@ -0,0 +1,102 @@
+# Menubar
+
+Horizontal desktop-style menu bar — File/Edit/View triggers opening dropdown panels.
+
+## When to use
+
+- Application-chrome command surfaces on desktop layouts: editors, dashboards with many commands.
+
+**When not:** For a single contextual menu on one trigger use Dropdown Menu. For site navigation with panels use [Navigation Menu](./navigation-menu.md).
+
+## Anatomy
+
+- `Menubar` — the bar: `h-10`, `rounded-lg`, hairline border, `p-1 gap-1`. `data-slot="menubar"`.
+- `MenubarMenu` — one menu (trigger + content pair). `data-slot="menubar-menu"`.
+- `MenubarTrigger` — bar button, `rounded-md px-2 py-1`. `data-slot="menubar-trigger"`.
+- `MenubarContent` / `MenubarSubContent` — dropdown panels, `rounded-lg`, `min-w-[12rem]` / `min-w-[8rem]`, `p-1`. `data-slot="menubar-content"` / `"menubar-sub-content"`.
+- `MenubarItem` — command row, `rounded-md px-2 py-1.5`. `data-slot="menubar-item"`.
+- `MenubarCheckboxItem` / `MenubarRadioItem` (+ `MenubarRadioGroup`) — checkable rows with a left indicator (check / 8px filled circle). `data-slot="menubar-checkbox-item"` / `"menubar-radio-item"`.
+- `MenubarLabel` — section heading. `data-slot="menubar-label"`.
+- `MenubarSeparator` — 1px rule, `-mx-1 my-1`. `data-slot="menubar-separator"`.
+- `MenubarShortcut` — right-aligned key hint. `data-slot="menubar-shortcut"`.
+- `MenubarSub` / `MenubarSubTrigger` — nested submenu; trigger appends a `ChevronRightIcon`. `data-slot="menubar-sub"` / `"menubar-sub-trigger"`.
+- `MenubarGroup`, `MenubarPortal` — grouping/portal passthroughs.
+
+## API
+
+### MenubarItem
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "destructive"` | `"default"` | destructive = `text-text-error-default` ink, focus fill `bg-background-error-default`, icons forced error ink. |
+| `inset` | `boolean` | — | `pl-8` to align with checkable rows. |
+
+### MenubarContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `align` | Radix align | `"start"` | |
+| `alignOffset` | `number` | `-4` | |
+| `sideOffset` | `number` | `8` | |
+
+`MenubarTrigger`, `MenubarCheckboxItem` (`checked`), `MenubarRadioItem` (`value`), `MenubarLabel` (`inset`), and `MenubarSubTrigger` (`inset`) otherwise pass Radix props through.
+
+## Variants & sizes
+
+No size rail — menus are fixed density (trigger 14/medium/20, items 14/regular/20).
+
+```tsx
+import {
+  Menubar,
+  MenubarMenu,
+  MenubarTrigger,
+  MenubarContent,
+  MenubarItem,
+  MenubarSeparator,
+  MenubarShortcut,
+} from "@trading-game/design-intelligence-layer"
+
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>
+        New chart <MenubarShortcut>⌘N</MenubarShortcut>
+      </MenubarItem>
+      <MenubarSeparator />
+      <MenubarItem variant="destructive">Delete workspace</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- bar and panels: `bg-background-primary-surface` + `border-border-default-default`, ink `text-text-prominent-default`
+- hover/focus rows and triggers: `bg-background-hover-default` + `text-text-prominent-default`
+- open trigger: `bg-background-hover-default` + `text-text-brand-selected` (selection-ink family)
+- destructive: `text-text-error-default`, focus `bg-background-error-default`
+- headings `text-text-prominent-default`; shortcuts `text-text-subtle-default`; row icons `text-icon-subtle-default`
+- separator `bg-border-default-default`
+
+**Type (private):** shared `--menu-*` family — item 14/regular/20, heading 12/medium/16, trigger 14/medium/20, shortcut 12/regular/16.
+
+## Behaviour
+
+- Radix Menubar semantics: arrow keys move across triggers, open menus follow pointer, submenus open from `MenubarSub`.
+- The open trigger takes selected ink (`text-text-brand-selected`) on the hover fill — the bar shows which menu is down.
+- Panels are portalled, animated (fade/zoom/side slide), and solid — no shadow.
+- Row icons default to 16px `text-icon-subtle-default` unless the icon sets its own size/colour class; destructive rows force error ink on icons.
+
+## Do / Don't
+
+**Do**
+- Use `inset` on plain items sharing a panel with checkbox/radio rows so text columns align at `pl-8`.
+- Keep panels `rounded-lg` (10px) with `rounded-md` (8px) rows — the menu radius tiers.
+- Reserve `variant="destructive"` for irreversible commands.
+
+**Don't**
+- Don't restyle the open-trigger ink; `text-text-brand-selected` is the selection contract (dark theme has its own values — it is not a mirror of light).
+- Don't put shortcuts in their own component — `MenubarShortcut` right-aligns and mutes them for you.
+- Don't add elevation/shadows to `MenubarContent`; hairline on solid surface only.

package/docs/components/native-select.md

@@ -0,0 +1,71 @@
+# Native Select
+
+Styled native `<select>` on the 32/40/48 rail — the platform picker with system paint.
+
+## When to use
+
+- Pick-one dropdowns where the native OS sheet/menu is acceptable or preferred (mobile forms, simple settings).
+
+**When not:** For styled option rows, search, or rich option content use the custom Select. For free text use [Input](./input.md).
+
+## Anatomy
+
+- `NativeSelect` — wrapper `div` (`data-slot="native-select-wrapper"`, `w-fit`) containing the styled `<select>` (`data-slot="native-select"`, `data-size`) and an absolutely positioned `ChevronDownIcon` (`data-slot="native-select-icon"`, 16px, right 14px).
+- `NativeSelectOption` — `<option>` passthrough. `data-slot="native-select-option"`.
+- `NativeSelectOptGroup` — `<optgroup>` passthrough. `data-slot="native-select-optgroup"`.
+
+## API
+
+### NativeSelect
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md" \| "lg" \| "default"` | `"md"` (or the enclosing Field's size) | sm `h-8` (32), md `h-10` (40), lg `h-12` (48, `px-4 pr-10`). `"default"` @deprecated — alias resolving to `md`, removed at v1.0. The native numeric `size` attribute is not available. |
+
+All other native `<select>` props pass through.
+
+## Variants & sizes
+
+```tsx
+import {
+  NativeSelect,
+  NativeSelectOption,
+} from "@trading-game/design-intelligence-layer"
+
+<NativeSelect size="sm" defaultValue="1m">
+  <NativeSelectOption value="1m">1 minute</NativeSelectOption>
+  <NativeSelectOption value="5m">5 minutes</NativeSelectOption>
+</NativeSelect>
+
+<NativeSelect>…</NativeSelect>            {/* md, 40px */}
+<NativeSelect size="lg">…</NativeSelect>  {/* 48px */}
+```
+
+## Tokens
+
+**Colour (semantic):**
+- `border-border-default-default`, `bg-background-primary-surface`, `text-text-prominent-default`
+- chevron `text-icon-subtle-default`
+- selection: `bg-background-brand-default` + `text-text-on-brand-static`
+- focus: `border-ring-focus-default` + 3px `ring-ring-focus-soft` (soft text-field ring)
+
+**Type (private):** `--native-select-*` ladder, regular weight — sm 12/16, md 14/20, lg 16/24 (`type-native-select-sm|md|lg`).
+
+## Behaviour
+
+- Joins the [Field](./field.md) cascade: with no `size` prop it takes the Field's size; an explicit prop wins. `size="default"` always resolves to `md` regardless of context.
+- `appearance-none` + the injected chevron replace the platform arrow; right padding (`pr-9`, lg `pr-10`) reserves its space.
+- Disabled dims the wrapper (`has-[select:disabled]:opacity-24`) and kills pointer events on the select.
+- The wrapper is `w-fit` and `className` lands on the inner `<select>` — for full-width layouts you must widen the wrapper (e.g. a `w-full` parent with `[&>[data-slot=native-select-wrapper]]:w-full`), not just the select.
+
+## Do / Don't
+
+**Do**
+- Stay on the 32/40/48 rail and let Field size it in forms.
+- Use `NativeSelectOptGroup` for long lists; the native control handles it best.
+- Keep the chevron as rendered — 16px subtle-icon ink at right 14px.
+
+**Don't**
+- Don't write `size="default"` in new code; it is a deprecated alias for `md`.
+- Don't swap the soft 8% focus ring for the 50% control ring; selects follow the text-field focus recipe here.
+- Don't try to restyle `<option>` rows — that is native UI; use the custom Select when options need system paint.

package/docs/components/navigation-button.md

@@ -0,0 +1,68 @@
+# Navigation Button
+
+Circular icon-only control for moving through UI — back arrows, carousel steppers, close chevrons.
+
+## When to use
+
+- Icon-only navigation affordances: back/forward, next/previous, header chrome.
+- Over imagery or brand fills, with the `frosted-on-brand` variant.
+
+**When not:** For icon actions that submit or mutate use an icon-size Button. For paged number lists use [Pagination](./pagination.md).
+
+## Anatomy
+
+- `NavigationButton` — a circular `<button>` (or Slot via `asChild`) holding one icon. `data-slot="navigation-button"`, `data-variant`, `data-size`.
+- `navigationButtonVariants` — exported cva.
+
+## API
+
+### NavigationButton
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "frosted-on-brand"` | `"default"` | default = transparent circle, hover fill; glass = frosted circle for art/hero/brand surfaces. |
+| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"lg"` | xs 24px (16px icon), sm 32px (20px icon), md 40px (20px icon), lg 48px (24px icon). |
+| `asChild` | `boolean` | `false` | Render as `<a>` etc. via Radix Slot. |
+
+## Variants & sizes
+
+```tsx
+import { NavigationButton } from "@trading-game/design-intelligence-layer"
+import { ChevronLeftIcon } from "lucide-react"
+
+<NavigationButton aria-label="Back"><ChevronLeftIcon /></NavigationButton>      {/* lg, 48px */}
+<NavigationButton size="sm" aria-label="Back"><ChevronLeftIcon /></NavigationButton>
+
+// Over a hero image or brand fill:
+<NavigationButton variant="frosted-on-brand" size="md" aria-label="Previous slide">
+  <ChevronLeftIcon />
+</NavigationButton>
+```
+
+## Tokens
+
+**Colour (semantic):**
+- default: transparent, `text-icon-prominent-default`, hover `bg-background-hover-default`
+- focus: 3px `ring-ring-focus-strong`
+- glass (alpha primitives — the sanctioned glass use): fill + border `--primitive-white-alpha-24` with `backdrop-blur-md`, ink `text-text-on-brand-static`; hover thickens to `--primitive-white-alpha-32`, press thins to `--primitive-white-alpha-16`
+
+**Type (private):** none — icon-only, no text.
+
+## Behaviour
+
+- Always a circle (`rounded-full`), per the icon-button law.
+- Press feedback: default variant uses `active:opacity-60`; glass replaces it (`active:opacity-100`) with the thinner alpha-16 frost so the blur never flickers.
+- Disabled is `opacity-24` (a deliberate deep dim, not the usual 50) with pointer-events none.
+- Transitions run `duration-fast ease-standard`.
+
+## Do / Don't
+
+**Do**
+- Always pass `aria-label`; there is no text child.
+- Use `frosted-on-brand` only on top of imagery or brand colour — its white-alpha recipe assumes a non-neutral ground.
+- Pick from the 24/32/40/48 circle sizes; note the default is `lg` (48px), sized for touch chrome.
+
+**Don't**
+- Don't square the corners or turn it into a pill; icon buttons are circles, always.
+- Don't use glass on plain light surfaces — the alpha-primitive frost is reserved for glazes/glass over art or brand.
+- Don't add labels next to the icon inside the button; pair with a `Link` or Button instead.