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

package/docs/components/tooltip.md

@@ -0,0 +1,83 @@
+# Tooltip
+
+Hover/focus hint on desktop that automatically becomes a bottom Drawer with a title and close button on mobile.
+
+## When to use
+
+- Short clarifications for icons, abbreviations, and truncated values — fee breakdowns, badge meanings, collapsed sidebar labels.
+
+**When not:** For rich interactive content on hover use Hover Card or Popover. For persistent inline help use helper text under the field.
+
+## Anatomy
+
+- `TooltipProvider` — Radix provider, `delayDuration` preset to `0`; `data-slot="tooltip-provider"`.
+- `Tooltip` — root that picks the surface per viewport via the internal `TooltipModeContext`: Radix Tooltip on desktop, vaul `Drawer` on mobile; `data-slot="tooltip"` (desktop).
+- `TooltipTrigger` — renders a Radix `Trigger` or a `DrawerTrigger` depending on mode; `data-slot="tooltip-trigger"`.
+- `TooltipContent` — desktop: portalled bubble with arrow; mobile: `DrawerContent` with `DrawerHeader`/`DrawerTitle`, body, and a primary close `Button` in the `DrawerFooter`; `data-slot="tooltip-content"`, `data-variant`.
+
+## API
+
+### TooltipContent
+
+| Prop | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "inverse"` | `"default"` | default: inverse surface (dark-on-light / light-on-dark). inverse: bordered white/primary-surface card for use over saturated surfaces. Desktop only — mobile always uses the neutral drawer. |
+| `sideOffset` | `number` | `6` | Desktop offset from the trigger. |
+| `title` | `string` | `"Title"` | Mobile drawer heading. The default is a placeholder — always pass real text. Ignored on desktop. |
+| `closeLabel` | `string` | `"Label"` | Mobile drawer dismiss-button text. Placeholder default — always pass real text. Ignored on desktop. |
+
+`Tooltip` takes Radix root props (`open`, `onOpenChange`, `delayDuration`); `TooltipProvider` presets `delayDuration={0}`.
+
+## Variants & sizes
+
+```tsx
+import {
+  TooltipProvider, Tooltip, TooltipTrigger, TooltipContent,
+} from "@trading-game/design-intelligence-layer"
+
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild><button>Fees</button></TooltipTrigger>
+    <TooltipContent title="Fees" closeLabel="Got it">
+      0.1% maker / 0.2% taker.
+    </TooltipContent>
+  </Tooltip>
+
+  {/* over a saturated surface */}
+  <Tooltip>
+    <TooltipTrigger asChild><span>2x boost</span></TooltipTrigger>
+    <TooltipContent variant="inverse" title="Boost" closeLabel="Close">
+      Doubles points on winning trades.
+    </TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## Tokens
+
+**Colour (semantic):** `bg-background-inverse-surface` + `text-text-prominent-inverse` (default desktop bubble, arrow fill matches), `bg-background-primary-surface` + `text-text-prominent-default` + `border-border-default-default` (inverse variant); mobile drawer body uses `text-text-subtle-default` on the Drawer's own surface.
+**Type (private):**
+
+| Token | Value |
+| --- | --- |
+| `--tooltip-*` (via `.type-tooltip`, desktop) | 14 / medium (500) / 20 |
+| Mobile body (via `.type-drawer-description`) | 14 / regular (400) / 20; drawer title 18 / semibold (600) / 24 |
+
+## Behaviour
+
+- The mobile/desktop decision is centralized in `Tooltip` through `TooltipModeContext`, so trigger and content always agree within a render — avoiding SSR-hydration mismatches ("TooltipTrigger must be used within Tooltip").
+- Mobile (`useIsMobile`): tap opens a bottom Drawer that persists until scrim tap, swipe-down, or the footer's primary md close Button — hover tooltips do not exist on touch.
+- Desktop: portalled bubble, `rounded-md`, max width `max-w-xs`, `sideOffset` 6, zoom/fade/slide animations, no shadow; `variant` only affects desktop.
+- `SidebarProvider` wraps its tree in a `TooltipProvider` already; elsewhere you must provide one.
+
+## Do / Don't
+
+**Do**
+- Always pass real `title` and `closeLabel` — the source defaults are the literal placeholder strings "Title" and "Label", and they render on mobile.
+- Use `variant="inverse"` over saturated coloured surfaces where the inverse bubble would feel heavy.
+- Keep content to a sentence or two; the desktop bubble caps at `max-w-xs`.
+
+**Don't**
+- Don't put links or buttons inside tooltip content — on desktop it is hover-only; use Popover instead.
+- Don't wrap tooltip text past medium 500 weight on desktop; `.type-tooltip` is fixed at 14/medium/20.
+- Don't build a separate mobile fallback — the drawer behaviour is automatic.

package/docs/foundations/colors.md

@@ -0,0 +1,109 @@
+# Colour
+
+Champion Trade's colour system is three layers. Components consume **semantic tokens only** — never primitives, never hex values. The semantic layer is what makes the dark theme work: every semantic token re-resolves in dark, and dark values are chosen for dark, not mirrored from light.
+
+```
+Layer 1  Primitives   --primitive-blue-600: #2323FF        raw scales, never used in components
+Layer 2  Semantics    --background-brand-default            the only layer components reference
+Layer 3  Components   (typography tokens only — colour has NO component layer)
+```
+
+Token grammar (Quill style): `{element}-{role}-{variant}` — e.g. `background-brand-selected`, `text-error-default`, `border-default-default`. In Tailwind classes the element prefix repeats: `bg-background-brand-default`, `text-text-error-default`, `border-border-default-default`.
+
+## Hard rules
+
+1. **Semantic tokens only in components.** A raw primitive is allowed only for alpha glazes (hovers, glass, scrims) — e.g. `bg-(--primitive-white-alpha-24)` for glass.
+2. **Surfaces are always solid.** Alpha values are for *state layers on top of* a solid base (hover glazes, pressed glazes, glass, scrims, washes) — never for a resting surface. Dark surfaces are built as `color-mix()` of white over the canvas, producing a solid colour.
+3. **Dark is not a mirror.** When a light construction fails on near-black (a 10% wash disappears, mid-blue ink loses contrast), the dark value diverges — that's what the `.dark` block is for. Never hardcode a light construction and assume it flips.
+4. **Selection states use the `*-brand-selected` family** — never `brand-default/10` washes or `text-brand-default` ink for a selected/active element.
+5. **No shadows anywhere.** Elevation is hairline borders and surface steps.
+
+## Primitive scales
+
+All scales run 50→1000 (mono 50→1200; blue adds 25 and 1000 as the two canvases). Bases: brand blue at **600**, status colours (green/red/amber/azure) at **600**, game accents (ember/violet/jade) at **500**.
+
+| Scale | Base | Notes |
+|---|---|---|
+| `blue` | 600 `#2323FF` | Brand. 25 `#F7F8FC` = light canvas · 1000 `#00001F` = dark canvas · 400 `#4D6BFF` = dark-theme brand |
+| `mono` | — | 50 `#FFFFFF` → 1200 `#000000`; 1100 `#1C1C1C` is prominent ink |
+| `green` | 600 `#00BD46` | Status: success / win |
+| `red` | 600 `#FE2925` | Status: error / loss |
+| `amber` | 600 `#F49E00` | Status: warning |
+| `azure` | 600 `#2A90E0` | Status: information + game accent (sky ≈ 500) |
+| `ember` | 500 `#E85C1A` | Game accent + demo-account marker |
+| `violet` | 500 `#9A3CF0` | Game accent (lilac ≈ 200) |
+| `jade` | 500 `#0AA060` | Game accent |
+| `white-alpha` | — | 4/6/8/12/16/20/24/32/40/50/64/80 — lifts and glazes on dark or coloured surfaces |
+| `black-alpha` | — | same steps — glazes and scrims on light surfaces |
+| `blue-alpha` | — | 4→80 — frosted brand washes |
+
+## Semantic tokens — Background
+
+| Token | Light | Dark | Job |
+|---|---|---|---|
+| `background-primary-canvas` | blue-25 `#F7F8FC` | blue-1000 `#00001F` | The app page behind everything |
+| `background-primary-surface` | mono-50 `#FFFFFF` | white 6% over canvas ≈ `#0F0F2C` | Cards, panels, menus, inputs, sheets — the default solid surface |
+| `background-secondary-surface` | mono-100 `#F1F1F1` | white 12% over canvas ≈ `#1F1F3A` | One step up: muted fills, tracks, icon tiles, read-only fields |
+| `background-hover-default` | black-alpha-4 | white-alpha-12 | The hover glaze — laid over any solid surface |
+| `background-pressed-default` | black-alpha-8 | white-alpha-20 | The pressed glaze |
+| `background-brand-default` | blue-600 `#2323FF` | blue-400 `#4D6BFF` | Primary CTAs, checked controls, solid selection chips |
+| `background-brand-hover` | black 16% over brand | (same recipe, re-derives) | Primary button hover — a state layer, not a scale step |
+| `background-brand-pressed` | black 32% over brand | (same recipe) | Primary button pressed |
+| `background-brand-selected` | blue-600 10% over white ≈ `#E9E9FF` | blue-400 24% over canvas ≈ `#121A55` | Selected/active fills: active nav row, current page, checked choice card |
+| `background-brand-container` | white 92% glaze over blue-600 (layered) | static — same | The icy brand panel (calendar selection). **Layered value — paint with `background:`, never `bg-*`** |
+| `background-inverse-surface` | mono-1100 `#1C1C1C` | mono-50 `#FFFFFF` | The flipped surface (tooltips, toasts) |
+| `background-overlay-default` | black-alpha-50 | black-alpha-64 | Modal scrims |
+| `background-success-default` | green-50 | green-600 24% over canvas | Status tint surface (Section Message) |
+| `background-error-default` | red-50 | red-600 24% over canvas | ditto |
+| `background-warning-default` | amber-50 | amber-600 24% over canvas | ditto |
+| `background-information-default` | azure-50 | azure-600 24% over canvas | ditto |
+| `background-success-solid` / `-error-solid` / `-warning-solid` | status 600 | static — same | Solid status fills (badges) |
+| `background-demo-solid` / `background-demo-default` | ember-500 / ember-50 | static | Demo-account badge fills |
+| `background-static-white` | mono-50 | static — never flips | White elements on fixed-colour art panels (on-brand buttons) |
+
+## Semantic tokens — Text & Icon
+
+| Token | Light | Dark | Job |
+|---|---|---|---|
+| `text-prominent-default` | mono-1100 `#1C1C1C` | mono-50 `#FFFFFF` | Titles, values, primary content |
+| `text-subtle-default` | mono-900 `#555555` | mono-600 `#AAAAAA` | Descriptions, labels, placeholders, secondary content |
+| `text-disabled-default` | mono-500 | mono-800 | Disabled labels |
+| `text-prominent-inverse` | mono-50 | mono-1100 | Ink on `background-inverse-surface` |
+| `text-brand-default` | blue-600 | blue-400 `#4D6BFF` | Links, brand-coloured text on the canvas |
+| `text-brand-hover` | blue-700 `#0606C7` | blue-300 `#7392FF` | Hover step for brand text (links, menu hover ink) |
+| `text-brand-selected` | blue-600 | blue-200 `#99B7FF` | Ink on selected/active elements — two stops lighter in dark for contrast |
+| `text-on-brand-static` | mono-50 | static | White text on brand fills — never flips |
+| `text-brand-container-static` | blue-600 | static | Ink on `background-brand-container` |
+| `text-static-black` | mono-1100 | static | Ink on `background-static-white` |
+| `text-success-default` / `-error-` / `-warning-` / `-information-` | status 600 | **static — same in both themes** (deliberate call) | Status text |
+| `text-on-status-static` | mono-50 | static | White on solid status fills (below AA on green/amber — deliberate style call) |
+| `text-demo-default` | ember-500 | static | Demo badge ink |
+| `icon-prominent-default` … `icon-information-default` | aliases of the matching text tokens | — | Separate namespace so icons (3:1 requirement) can diverge later |
+
+## Semantic tokens — Border & Ring
+
+| Token | Light | Dark | Job |
+|---|---|---|---|
+| `border-default-default` | mono-200 `#E3E3E3` | white-alpha-12 | The hairline — every card, input, menu, divider |
+| `border-prominent-default` | mono-1100 | mono-50 | Heavy outline (outline toggles) |
+| `border-brand-selected` | blue-600 | blue-300 `#7392FF` | Border on selected elements (outline chip, active page) |
+| `border-neutral-default` | mono-500 | white-alpha-12 | Soft hairline for neutral tint chips |
+| `border-success-default` / `-error-` / `-warning-` / `-information-` | status 600 | static — same | Status outlines |
+| `ring-focus-default` | blue-600 | blue-400 | Base focus ink; `ring-focus-strong` (50% mix) is the 3px control ring, `ring-focus-soft` (8%) the text-field ring |
+| `ring-error-default` / `ring-error-soft` | red-600 / 20% mix | same | Invalid-field ring |
+| `ring-brand-soft` | brand 40% mix | flips with brand | Sidebar icon-rail hover/active ring |
+
+## Construction recipes (the Figma fill-stack model)
+
+Several values are **recipes, not scale steps** — a solid base with a fixed layer on top:
+
+- **State layers**: hover = black 16% / pressed = black 32% mixed over the brand fill (`color-mix`), so any brand colour derives its own states.
+- **Dark surfaces**: white 6% / 12% mixed over the dark canvas — solid results, no translucency.
+- **Dark status tints**: status-600 at 24% mixed over the canvas — solid.
+- **Brand container**: a real two-layer paint (white 92% glaze over blue-600) — consume via `background: var(--background-brand-container)`.
+- **On-brand sunken fields** (Input/InputGroup `variant="on-brand"`): `black-alpha-32` glaze fill + `white-alpha-24` border over whatever brand colour the consumer painted.
+- **Glass** (Button/NavigationButton `glass`, Card `glass`): `white-alpha-24` fill + border + `backdrop-blur-md`; hover 32, press 16. Theme-independent.
+
+## Deprecated aliases
+
+A block of old names (`--prominent`, `--on-subtle`, `--primary`, `--border-subtle`, `--ring`, `--tabs`, mono-alpha primitives, …) still resolves to the new tokens for external consumers. **Never use them in new code.** The entire block is deleted at v1.0.

package/docs/foundations/motion.md

@@ -0,0 +1,63 @@
+# Motion
+
+Motion mirrors the colour architecture: **primitives → semantic roles → components**. Components write `duration-fast ease-standard` etc.; the `duration-*` utilities resolve through the semantic roles, so retuning a role retunes every consumer. Components never name a motion primitive directly. Roles never flip in dark.
+
+## Layer 1 — Primitives
+
+### Durations
+
+| Primitive | Value | Notes |
+|---|---|---|
+| `instant` | 50ms | Focus rings; press-release fades |
+| `fast` | 100ms | Backs `--motion-hover` |
+| `base` | 200ms | Backs `--motion-surface` / `--motion-structural` |
+| `slow` | 300ms | Backs `--motion-progress` |
+| `open` | 500ms | Ceremony only (ProfilePhoto ring) — overlays no longer use it |
+| `blink` | 1000ms | OTP caret blink only |
+
+### Easing
+
+| Primitive | Curve | Character |
+|---|---|---|
+| `standard` | `cubic-bezier(0.2, 0, 0, 1)` | The house move — quick start, soft landing |
+| `enter` | `cubic-bezier(0, 0, 0.2, 1)` | Decelerates — things arriving |
+| `exit` | `cubic-bezier(0.4, 0, 1, 1)` | Accelerates — things leaving |
+| `linear` | `linear` | Constant speed — progress, sidebar width |
+| `spring` | `cubic-bezier(0.3, 1.25, 0.4, 1)` | Liquid travel — slight overshoot, settles |
+| `overshoot` | `cubic-bezier(0.2, 1.8, 0.4, 1)` | Pops & ticks — springs past, snaps back |
+
+## Layer 2 — Semantic roles
+
+| Role | Resolves to | Consumers |
+|---|---|---|
+| `--motion-hover` | fast · standard | Every hover glaze & fill (backs the `duration-fast` utility) |
+| `--motion-press` | **0ms in, fast out** | Pressed glazes — a pattern, not a utility: `active:duration-0` lands press the frame it happens; it fades on release |
+| `--motion-surface` | base · enter/exit | Menus, popovers, tooltips (backs `duration-base`) |
+| `--motion-overlay-open` | 320ms · enter | Sheet, Drawer, Dialog entering |
+| `--motion-overlay-close` | 250ms · exit | …and leaving — exits are quicker |
+| `--motion-structural` | base · linear | Sidebar collapse, accordion, layout changes |
+| `--motion-progress` | slow · linear | Progress fill, timers (backs `duration-slow`) |
+
+Sheet consumes the overlay role via arbitrary properties (`[animation-duration:var(--motion-overlay-open)]`) because tw-animate's `duration-*` coupling doesn't reach custom utility names.
+
+## Layer 3 — Signature moves
+
+The liquid selection language, named:
+
+| Token | Value | Consumers |
+|---|---|---|
+| `--motion-travel-lead` | 200ms · spring | Liquid indicator leading edge (Bottom Navigation; Tabs planned) |
+| `--motion-travel-trail` | 380ms · spring | Trailing edge, dragged behind — the water-drop absorb |
+| `--motion-pop` | 450ms · overshoot | Arriving icon pop; chip tick / success check (planned) |
+| `--animate-button-shimmer` | 4s · linear · infinite | Button `shimmer` modifier |
+| `--animate-skeleton-sweep` | 1.6s · standard · infinite | Skeleton directional loading sweep |
+
+Bottom Navigation reads `--motion-travel-lead/trail` and `--primitive-ease-spring` at runtime via `getComputedStyle` (TS fallbacks mirror the token values).
+
+## Rules
+
+- Exits are faster than entries (250ms close vs 320ms open) — getting out of the way beats ceremony.
+- Press feedback lands at 0ms (`active:duration-0`) and fades on release; a press that fades *in* reads as lag.
+- Never write a raw duration (`duration-200`) or generic easing (`ease-in-out`) — always a named utility.
+- Decorative loops (shimmer, skeleton sweep) are the only infinite animations; the Spinner is exempt from any future reduced-motion guard because it conveys state.
+- To retune the system: edit the role in `src/styles.css` **and** `app/globals.css` (both files, always).

package/docs/foundations/shape-layout.md

@@ -0,0 +1,56 @@
+# Shape & Layout
+
+## The control size rail — 32 / 40 / 48
+
+Every interactive control sits on one three-step height rail. A field and its action button always line up flush when they share a size.
+
+| Size | Height | Text step | Used by |
+|---|---|---|---|
+| `sm` | 32px (`h-8`) | 12 or 14 | Button sm, Input sm, Select sm, Native Select sm, Chip sm, Toggle sm, Switch sm (20px track), Input Group sm |
+| `md` | 40px (`h-10`) — **default everywhere** | 14 or 16 | Button md, Input md, Select md, Chip md, Stepper md … |
+| `lg` | 48px (`h-12`) | 16 or 18 | Button lg, Input lg, Select lg, Numpad keys, Bottom Navigation (60px pill with 48px touch rows) |
+
+Icon buttons are squares of the same rail: `icon-sm` 32 · `icon-md` 40 · `icon-lg`/`icon` 48 (+ `icon-xs` 24 where density demands it). Icons track the height: 14px→sm, 16px→md, 20px→lg.
+
+### Button padding rule
+
+Horizontal padding = **height/2 − 4** (lg 20px · md 16px · sm 12px); content gap fixed at **8px**. Padding never changes when icons are hidden — the label column stays put.
+
+## Radius system
+
+Radius encodes the element's *class*, not taste:
+
+| Element class | Radius | Examples |
+|---|---|---|
+| Actions — buttons, chips, pills, toggle pills | `rounded-full` | Button, Chip, Pagination cells, Bottom Navigation, badges, glass circles |
+| Icon buttons | circles (`rounded-full` on a square) | Navigation Button, Button icon sizes, Input Group icon buttons |
+| Cards & panels | `rounded-2xl` = **18px** | Card, Dialog, Alert Dialog, Popover, Hover Card, Empty shell, Drawer's attached edge (`rounded-t-2xl`) |
+| Menus & floating lists | `rounded-lg` = **10px** | Dropdown/Context/Menubar/Select panels, Menubar bar, Navigation Menu viewport |
+| Rows inside menus/lists | `rounded-md` = **8px** | Menu items, Item rows, Tabs triggers, Sidebar rows, Numpad keys |
+| Form fields | `rounded-xs` = **4px** — deliberate, unchanged | Input, Textarea, Native Select, Input Group frame, OTP slot end caps — the whole text-entry family |
+| Checkboxes | `rounded-2xs` | Checkbox |
+
+Side drawers and sheets stay square on their full-height edges; top/bottom drawers round only the detached edge.
+
+## Spacing
+
+- Base unit 4px (Tailwind scale). Component-internal gaps: 8px (button content), 12px (Field md/lg), 8px (Field sm), 4px (menu padding `p-1`, Numpad grid `gap-1`).
+- Card/panel slots: 16px padding (`p-4`, was deliberately reduced from 24).
+- Overlay panels: 24px padding (`p-6` on Dialog/Alert Dialog).
+
+## Responsive layout grid
+
+Semantic grid tokens flip at breakpoints (gutter/margin primitives: 16px sm, 36px md):
+
+| Viewport | Columns | Gutter | Margin |
+|---|---|---|---|
+| < 320px | 1 | 0 | 16px |
+| ≥ 320px | 4 | 16px | 16px |
+| ≥ 600px | 8 | 36px | 16px |
+| ≥ 1136px | 12 | 36px | 16px |
+
+Tokens: `--semantic-layout-grid-columns`, `--semantic-layout-gutter`, `--semantic-layout-margin-inline`.
+
+## Elevation
+
+Inline components carry none — **no shadows** — every component's `shadow-*` has been removed. The one sanctioned exception is **floating mobile chrome** (Bottom Navigation): a soft ambient lift (`shadow-chrome-default`, `0 12px 30px`) separates chrome from the content scrolling beneath it, per the Refined Mobile file. Elevation reads through the hairline (`border-default-default`) and surface steps (canvas → primary surface → secondary surface). On dark this is why surfaces are solid white-mixes: the step between `#00001F`, `#0F0F2C`, `#1F1F3A` is the elevation.

package/docs/foundations/typography.md

@@ -0,0 +1,83 @@
+# Typography
+
+One family — **Plus Jakarta Sans** (`--font-plus-jakarta-sans`, falls back to system sans). Utilities: `font-display` (headings/buttons), `font-body` (content), `font-sans`.
+
+Typography is the **only** place the component token layer exists: every component's text is sized by **private `--<component>-*` tokens** that point at the primitive scales. Colour has no component tokens; type has nothing else.
+
+```
+Layer 1  Primitives   --primitive-font-size-14, --primitive-line-height-20, --primitive-font-weight-medium
+Layer 2  Foundation   --type-h1-*, --type-body-md-*  (the page-content scale, used via .h1/.body-md classes)
+Layer 3  Component    --button-font-size-md, --dialog-title-font-size  (private per component, applied via .type-* classes)
+```
+
+## Hard rules
+
+1. **No bold (700) in components.** Semibold **600 is the maximum component weight** — Button, Chip, Badge, active states, everything. The 700/800 primitives exist only for the foundation heading scale (H1/H2, display).
+2. **Every size traces to a primitive step.** No raw `text-[13px]`; no Tailwind `text-sm` in component code — components use their `.type-<component>-*` class.
+3. **`.type-*` classes are plain CSS, not Tailwind utilities.** Two consequences:
+   - They **cannot be gated by variants** — `data-[state=active]:type-foo` silently does nothing. Pick the class in JSX, or write a CSS rule keyed on the data attribute.
+   - They **beat layered utilities** — `font-medium` next to a `.type-*` class loses. Weight changes need their own token + CSS rule (see Tabs/Sidebar active-semibold rules in `styles.css`).
+
+## Primitive scales
+
+- **Sizes (px)**: 10 · 12 · 14 · 16 · 18 · 20 · 22 · 24 · 26 · 30 · 32 · 36 · 40 · 56
+- **Line heights (px)**: 16 · 20 · 24 · 28 · 32 · 36 · 40 · 48 · 64 — standard pairings: 12→16, 14→20, 16→24, 18→24, 20→28
+- **Weights**: 400 regular · 500 medium · 600 semibold · 700 bold (foundation headings only) · 800 extrabold (display only)
+- **Tracking**: tightest −0.03em (display) → normal 0 (h5/body) → widest +0.12em (overline)
+
+## Foundation scale (page content — classes `.display`, `.h1` … `.h6`, `.body-lg/md/sm`, `.label-text`, `.caption`, `.overline`)
+
+| Style | Desktop | Mobile | Weight | Tracking |
+|---|---|---|---|---|
+| display | 56/64 | 36/40 | 800 | −0.03em |
+| h1 | 40/48 | 30/36 | 700 | −0.025em |
+| h2 | 32/40 | 26/32 | 700 | −0.02em |
+| h3 | 24/32 | 22/28 | 600 | −0.015em |
+| h4 | 20/28 | — | 600 | −0.01em |
+| h5 | 18/24 | — | 600 | 0 |
+| h6 | 16/24 | — | 600 | 0 |
+| body-lg | 18/28 | — | 400 | — |
+| body-md | 16/24 | — | 400 | — |
+| body-sm | 14/20 | — | 400 | — |
+| label | 14/20 | — | 500 | 0 |
+| caption | 12/16 | — | 500 | +0.005em |
+| overline | 12/16 | — | 600 | +0.12em |
+
+Display/h1/h2/h3 are fluid — desktop and mobile values clamp responsively.
+
+## The component token pattern
+
+Each component declares its own type tokens in `src/styles.css` (mirrored in `app/globals.css`) and a `.type-<component>[-part][-size]` class per text role. Example (Dialog):
+
+```css
+--dialog-title-font-size: var(--primitive-font-size-18);
+--dialog-title-font-weight: var(--primitive-font-weight-semibold);
+--dialog-title-line-height: var(--primitive-line-height-24);
+
+.type-dialog-title {
+  font-size: var(--dialog-title-font-size);
+  line-height: var(--dialog-title-line-height);
+  font-weight: var(--dialog-title-font-weight);
+}
+```
+
+Recurring ladders:
+
+- **Control sizes** ride one primitive step per size: sm 12/16 · md 14/20 · lg 16/24 (Input, Select trigger, Native Select, Field labels, Tabs triggers, Link).
+- **Buttons**: lg 18/24 · md 16/24 · sm 14/20, all **semibold**. Chips: md 14/20 · sm 12/16, semibold.
+- **Overlay titles** (Dialog, Alert Dialog, Drawer, Sheet, Empty): 18/semibold/24; their descriptions 14/regular/20.
+- **Small labels** (Badge sm, Kbd-like chips, Sidebar labels, Bottom Navigation, menu headings): 12/16, medium.
+- **Helper text** (Field description/error): fixed **12/16 at every field size** — help text never scales with the control.
+
+## The one shared family: `--menu-*`
+
+Menu-like components deliberately share one type family instead of private ones (user-approved exception), so all menus stay in lockstep:
+
+| Token | Value | Used for |
+|---|---|---|
+| `--menu-item-*` | 14/regular/20 | Rows in Command, Context Menu, Dropdown Menu, Menubar, Select, Navigation Menu links |
+| `--menu-heading-*` | 12/medium/16 | Group labels in all of the above |
+| `--menu-trigger-*` | 14/medium/20 | Menubar and Navigation Menu triggers |
+| `--menu-shortcut-*` | 12/regular/16 | Shortcut hints in menu rows |
+
+Classes: `.type-menu-item`, `.type-menu-heading`, `.type-menu-trigger`, `.type-menu-shortcut`.

package/docs/patterns/forms.md

@@ -0,0 +1,70 @@
+# Pattern — Forms
+
+How form controls compose in Champion Trade: one wrapper (Field) drives sizing, labelling, and validation for every control inside it.
+
+## The Field cascade
+
+`Field` carries a `size` (`sm | md | lg`) and provides it through context. **Input, Input Group, and Native Select default their own size to the surrounding Field's** — one prop sizes the whole frame. An explicit size on the control always wins.
+
+```tsx
+import { Field, FieldLabel, FieldContent, FieldDescription, Input } from "@trading-game/design-intelligence-layer"
+
+<Field size="sm">
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <FieldContent>
+    <Input id="email" placeholder="you@example.com" />  {/* renders 32px automatically */}
+    <FieldDescription>Work email preferred.</FieldDescription>
+  </FieldContent>
+</Field>
+```
+
+The full ladder:
+
+| Field size | Label | Control height | Helper text | Gap |
+|---|---|---|---|---|
+| `sm` | 12/16 medium | 32px | **12/16** | 8px |
+| `md` (default) | 14/20 medium | 40px | **12/16** | 12px |
+| `lg` | 16/24 medium | 48px | **12/16** | 12px |
+
+Helper text (description, error, separator chip) is fixed at 12/16 at every size — help text never scales with the control.
+
+## Validation & error ink
+
+Mark the Field invalid and set `aria-invalid` on the control:
+
+```tsx
+<Field data-invalid="true">
+  <FieldLabel htmlFor="e">Email</FieldLabel>
+  <FieldContent>
+    <Input id="e" aria-invalid />
+    <FieldError>Please enter a valid email address.</FieldError>
+  </FieldContent>
+</Field>
+```
+
+- `data-invalid="true"` on Field sets `text-text-error-default` on the root; **the label turns red through inheritance** (Label deliberately sets no colour of its own).
+- `aria-invalid` on the control swaps its border/ring to `border-error-default` / `ring-error-soft`.
+- `FieldError` renders in error ink at the helper ladder (12/16). Error red is red-600 `#FE2925`, static in both themes.
+
+## The input family conventions
+
+All text-entry controls share one construction: **hairline border (`border-default-default`) + solid `background-primary-surface` + prominent ink + subtle placeholder + brand selection + soft focus ring** (`focus-visible:border-ring-focus-default ring-[3px] ring-ring-focus-soft`), no shadow, radius `rounded-xs` (4px — deliberate).
+
+| Control | Notes |
+|---|---|
+| [Input](../components/input.md) | sm/md/lg; `variant="on-brand"` for brand surfaces |
+| [Textarea](../components/textarea.md) | md type (14/20), auto-sizing content |
+| [Input Group](../components/input-group.md) | buttons/prefixes *inside* the field; addons inherit the group's type ladder |
+| [Native Select](../components/native-select.md) | OS-native option list, same rail |
+| [Select](../components/select.md) | custom popup (opens below the trigger) |
+| [Input OTP](../components/input-otp.md) | segmented code entry |
+| [Stepper](../components/stepper.md) | numeric +/− built on Input Group |
+| [Numpad](../components/numpad.md) | mobile amount entry — pairs with a display figure, not an input |
+
+## Choice cards
+
+A `FieldLabel` wrapping a nested `Field` becomes a selectable card. Checked state uses the selection tokens: `border-border-brand-selected` + `bg-background-brand-selected` (10% tint light / solid `#121A55` dark).
+
+## Buttons in forms
+
+A Button and a field of the same size align flush (32/40/48 rail). Button text is one primitive step larger than the field's text at every size (14/16/18 vs 12/14/16) — the action stays the loudest element in the row.

package/docs/patterns/menus.md

@@ -0,0 +1,50 @@
+# Pattern — Menus
+
+Five components render menu rows, and they share **one deliberate type family** (`--menu-*`) plus one visual recipe, so every menu in the product looks identical: [Command](../components/command.md), [Context Menu](../components/context-menu.md), [Dropdown Menu](../components/dropdown-menu.md), [Menubar](../components/menubar.md), and [Select](../components/select.md)'s rows ([Navigation Menu](../components/navigation-menu.md) links ride the same family).
+
+## The panel shell
+
+```
+rounded-lg (10px) · border-border-default-default · bg-background-primary-surface
+p-1 · text-text-prominent-default · NO shadow
+```
+
+Panels are one radius step below cards (10px vs 18px) — that difference is what visually separates "menu" from "card".
+
+## The row recipe
+
+```
+type-menu-item (14/regular/20) · rounded-md (8px) · px-2 py-1.5
+focus/hover → bg-background-hover-default + text-text-prominent-default
+icons → text-icon-subtle-default, size-4
+disabled → opacity-24
+destructive rows → text-text-error-default + focus:bg-background-error-default
+checked/selected ink → text-text-brand-selected
+```
+
+## The shared type family
+
+| Token | Value | Role |
+|---|---|---|
+| `--menu-item-*` | 14/regular/20 | Rows (items, checkbox/radio items, sub-triggers, nav links) |
+| `--menu-heading-*` | 12/medium/16 | Group labels (`SelectLabel`, `DropdownMenuLabel`, …) |
+| `--menu-trigger-*` | 14/medium/20 | Bar triggers (Menubar, Navigation Menu) |
+| `--menu-shortcut-*` | 12/regular/16 | Shortcut hints, right-aligned, subtle ink |
+
+Classes: `.type-menu-item`, `.type-menu-heading`, `.type-menu-trigger`, `.type-menu-shortcut`. This is the **only** shared component type family in the system — everywhere else, type tokens are private per component. Extending the family (a new slot) is allowed; pointing non-menu components at it is not.
+
+## Positioning conventions
+
+- Everything opens **below/beside its trigger** and stays put. Select's Radix "item-aligned" mode (list slides to overlap the trigger) was deliberately replaced with `position="popper"` as the default.
+- Open-state triggers: hover glaze background; Menubar's open trigger ink goes `text-text-brand-selected`.
+
+## Which menu component when
+
+| Need | Use |
+|---|---|
+| Pick one value into a form | Select (or Native Select for OS-native) |
+| Actions on click of a button | Dropdown Menu |
+| Actions on right-click | Context Menu |
+| Searchable command palette | Command |
+| App-window menu bar | Menubar |
+| Site navigation with panels | Navigation Menu |

package/docs/patterns/on-brand.md

@@ -0,0 +1,43 @@
+# Pattern — On-brand surfaces & glass
+
+Components standing on a **brand-coloured or art surface** (hero gradients, banners, game panels) can't use theme tokens — the surface is the same in both themes, so they use the **on-brand family** (static whites and glazes) or the **glass recipe**. "On-brand" replaced the misleading old name "inverse": these are not theme inverses, they are styles for fixed-colour panels.
+
+## The on-brand variant family
+
+| Component | Variant | Recipe |
+|---|---|---|
+| [Button](../components/button.md) | `primary-on-brand` | `background-static-white` pill + `text-brand-default` ink |
+| Button | `secondary-on-brand` | transparent + `border-background-static-white` + `text-on-brand-static`; hover `white-alpha-8` |
+| Button | `tertiary-on-brand` | transparent + `text-on-brand-static`; hover `white-alpha-8` |
+| [Input](../components/input.md) / [Input Group](../components/input-group.md) | `variant="on-brand"` | sunken field: `black-alpha-32` glaze fill + `white-alpha-24` border + static white ink; placeholder `white-alpha-50`; focus = white border + `white-alpha-40` ring |
+| [Link](../components/link.md) | `tone="on-brand"` | `text-on-brand-static`; hover `white-alpha-80` |
+
+All values are **static** — the brand panel doesn't flip with the theme, so neither do the elements on it. The old `*-inverse` names remain as deprecated aliases until v1.0.
+
+## The glass recipe
+
+Frosted elements for art/hero surfaces — theme-independent by nature:
+
+```
+bg-(--primitive-white-alpha-24) + border-(--primitive-white-alpha-24) + backdrop-blur-md
+text-text-on-brand-static
+hover → white-alpha-32 (frost thickens) · press → white-alpha-16 (frost thins)
+```
+
+| Component | Usage |
+|---|---|
+| Button `variant="frosted-on-brand"` | Frosted pill CTA on art; composes with icon sizes for frosted icon circles. Its page-surface counterpart is `variant="frosted"` (brand-selected tint) |
+| [Navigation Button](../components/navigation-button.md) `variant="frosted-on-brand"` | The floating back/close circles over hero gradients |
+| [Card](../components/card.md) `variant="frosted-on-brand"` | Frosted panel: `white-alpha-80` fill + `white-alpha-64` border + `backdrop-blur-xl` + static black ink |
+
+Glass lives **only on coloured/art surfaces** — never on the plain page canvas.
+
+## The Banner fade (the fill-stack construction)
+
+[Banner](../components/banner.md) takes any CSS colour and darkens it with a **fixed** black fade layered on top — `linear-gradient(120deg, rgb(0 0 0 / 0%), rgb(0 0 0 / 50%))` over the solid base. The fade never depends on the colour, so any custom panel colour works with zero tuning. This "solid base + fixed alpha layer" stack is the system's standard construction (same idea as dark surfaces, state layers, and the on-brand sunken field).
+
+## Rules
+
+- Never put theme tokens (`text-text-prominent-default`, `bg-background-primary-surface`, …) on a fixed-colour panel — they flip in dark and break.
+- Never use glass on the page canvas or inside plain cards.
+- The white CTA on a brand panel is `background-static-white` + `text-static-black`/`text-brand-default` — not `bg-white`.