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

package/AGENTS.md

@@ -7,7 +7,7 @@ Rules of engagement for AI agents building with `@trading-game/design-intelligen
 1. **Semantic colour tokens only.** Classes like `bg-background-brand-default`, `text-text-subtle-default`, `border-border-default-default`. Never hex, never `bg-blue-500`, never primitives — except alpha primitives for glazes/glass (`bg-(--primitive-white-alpha-24)`).
 2. **Never use deprecated aliases** (`bg-prominent`, `text-on-subtle`, `border-subtle`, `bg-primary`, `text-primary`, `ring-ring`, `bg-subtle`, `secondary-hover`, `destructive`, mono-alpha). They exist only for un-migrated external consumers and die at v1.0.
 3. **No bold.** Semibold (600) is the maximum weight in any component or component-adjacent UI. 700/800 belong to the foundation heading scale only.
-4. **No shadows** on inline components — elevation = hairline borders + surface steps. One sanctioned exception: **floating mobile chrome** (Bottom Navigation) carries the soft ambient `shadow-chrome-default` lift, per the Refined Mobile spec. Never add any other shadow.
+4. **No shadows** on inline components — elevation = hairline borders + surface steps. Exactly **two** sanctioned exceptions, both named tokens: **floating mobile chrome** (Bottom Navigation) carries the soft ambient `shadow-chrome-default` lift, and the **Slide to Confirm handle** carries `shadow-brand-glow` so a committed money action reads as liftable off its track. Both come from the Refined spec. Never add any other shadow, and never reuse these two tokens elsewhere.
 5. **Surfaces are solid.** Alpha is only for state layers on top of a solid base: hover/pressed glazes, glass, scrims, selection washes (light theme only).
 6. **Selection states use the selected family**: `bg-background-brand-selected` + `text-text-brand-selected` + `border-border-brand-selected`. Never `brand-default/10` washes, never `text-brand-default` as selected ink — those fail in dark.
 7. **Dark is not a mirror.** Never build a light-theme construction and assume it inverts. If a token pair doesn't exist for what you need, stop and ask — don't improvise per-theme values in a component.
@@ -23,6 +23,7 @@ Rules of engagement for AI agents building with `@trading-game/design-intelligen
 - **Menus**: Command, Context Menu, Dropdown Menu, Menubar, and Select rows share one look (`--menu-*` family): `rounded-lg` surface panel + hairline, `type-menu-item` rows with the hover glaze, `type-menu-heading` group labels. See [docs/patterns/menus.md](./docs/patterns/menus.md).
 - **On brand/art surfaces**: use the `on-brand` variants (Button `primary/secondary/tertiary-on-brand`, Input/InputGroup `variant="on-brand"`, Link `tone="on-brand"`) and the frost recipe (`variant="frosted-on-brand"` on Button, NavigationButton, and Card); on page surfaces the tinted counterpart is Button `variant="frosted"`. See [docs/patterns/on-brand.md](./docs/patterns/on-brand.md).
 - **State layers**: hover = `bg-background-hover-default` glaze; pressed = `bg-background-pressed-default`; brand fills derive hover/press via the built-in `brand-hover`/`brand-pressed` recipes.
+- **Page canvas**: the app shell paints the page background once — plain `bg-background-primary-canvas`, or the tinted screen background via `background: var(--background-tinted-canvas)` (a layered gradient token; not a `bg-*` utility). Components never set the page background. See the demo's Canvas foundation page.
 
 ## Anti-patterns (seen in the wild — don't repeat)
 
@@ -48,7 +49,7 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Breadcrumb | Hierarchical location trail |
 | Button | All actions; variants primary / secondary / tertiary / on-brand family / frosted + frosted-on-brand; `shimmer` modifier for headline CTAs |
 | Calendar | Date and range picking with themed dropdown month/year navigation |
-| Card | Content shells (`default`, `frosted-on-brand`, `interactive` hover-lift); blank by design, slots supply content |
+| Card | Content shells (`default`, `frosted` tint for page surfaces, `frosted-on-brand` for art/brand, `interactive` hover-lift); blank by design, slots supply content |
 | Carousel | Horizontally scrolling content (mobile catalogue) |
 | Chip | Compact choice pills: quick amounts, single-select filters, outline error-recovery |
 | Checkbox | Boolean form input |
@@ -68,7 +69,7 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Link | Inline/standalone links — quiet at rest, underline + darker ink on hover; `tone="on-brand"` |
 | Menubar | Horizontal app menu bar (menu family) |
 | Native Select | Styled native `<select>` for OS-native picking; same rail as Input |
-| Navigation Button | Circular icon-only nav control; `frosted-on-brand` variant for art surfaces |
+| Navigation Button | Circular icon-only nav control — tinted at rest, one step darker on hover; `frosted-on-brand` variant for art surfaces. Dialog and Sheet close buttons compose it rather than hand-rolling a circle |
 | Navigation Menu | Marketing-style nav with dropdown panels (menu family type) |
 | Numpad | Mobile amount-entry tray: bare 3×4 grid, emits keys, long-press backspace clears |
 | Pagination | Page navigation; circular cells, brand-selected active page |
@@ -86,13 +87,15 @@ Docs: `docs/components/<kebab-name>.md` for every entry.
 | Skeleton | Loading placeholders (solid secondary surface, pulse) |
 | Slider | Value selection on a track; circular brand thumb |
 | Spinner | Loading indicator (currentColor, 8-blade fade) |
-| Stepper | Numeric +/− input built on Input Group |
+| Slide to Confirm | Swipe-to-commit for irreversible money actions (withdraw, transfer) |
+| Stepper | The mobile amount tray — frosted −/+ circles around a centred editable amount |
+| Steps | Progress rail: numbered / onboarding / status timelines; circle or square, horizontal or vertical |
 | Switch | On/off toggle; brand track when checked, static white thumb |
 | Table | Data tables; 14px cells, medium heads, hover glaze rows |
 | Tabs | Segmented control (`default` pill-on-track) or underline (`line`) |
 | Textarea | Multi-line text (mirrors Input md) |
 | Toast | Transient notifications (sonner, inverse surface) |
-| Toggle / Toggle Group | Pressed-state buttons and grouped segmented toggles |
+| Toggle / Toggle Group | Chip-treatment pressed buttons; the group joins them into segmented sets — one docs page (`toggle.md`) |
 | Tooltip | Hover hints; inverse surface default, bordered-white `inverse` variant; renders as a Drawer on mobile |
 
 **Blocks** (`components/blocks/`: NavBar, Hero, Auth, FAQ, Header Navigation, Open Positions, Result, Game Loading) are pre-composed sections — currently awaiting their token-migration pass; prefer components until then.

package/README.md

@@ -1,8 +1,8 @@
 # Champion Trade Design System
 
-The component library and token architecture for **Champion Trade** (formerly Trading Game) — a Tailwind CSS v4 + React design system with a strict semantic token layer, per-component typography tokens, light and dark themes, and 57 production components.
+The component library and token architecture for **Champion Trade** (formerly Trading Game) — a Tailwind CSS v4 + React design system with a strict semantic token layer, per-component typography tokens, light and dark themes, and 59 production components.
 
-> **Package name:** still published as `@trading-game/design-intelligence-layer`. The npm scope renames to Champion Trade at v1.0 — until then, install and import under the current name below.
+> **Package name:** published as `@trading-game/design-intelligence-layer`. The Champion Trade npm scope rename is parked for a future major — install and import under the current name below.
 
 ## Install
 
@@ -74,11 +74,15 @@ React 18+, ReactDOM, Tailwind CSS v4+.
 
 ## What's inside
 
-- **57 components** — forms, overlays, menus, navigation, data display, plus trading-specific pieces (Numpad, Bottom Navigation, Profile Photo)
-- **Three-layer token architecture** — primitives → semantics → component type tokens; components consume semantic colour tokens only
-- **Light + dark themes** — dark is designed, not mirrored: its own surface mixes, selection fills, and ink steps
-- **No shadows** — elevation is hairlines and surface steps
-- **Pill shape system** — buttons and chips are pills, icon buttons are circles, cards 18px, menus 10px
+- **59 components** — forms, overlays, menus, navigation, data display, plus trading-specific pieces (Numpad, the Stepper amount tray, Slide to Confirm, Steps timelines, Bottom Navigation with its liquid selection bubble + AI circle, Profile Photo)
+- **Three-layer token architecture** — primitives → semantics → component type tokens; components consume semantic colour tokens only, and `npm run check:tokens` fails the build on any drift (undocumented tokens, primitives in components, alpha-modified colour constructions)
+- **Three-layer motion system** — duration/easing primitives → semantic roles (hover, press, surface, overlay) → named signature moves (the liquid travel spring, the arrival pop); overlay animations ship with the package
+- **Light + dark themes** — dark is designed, not mirrored: its own surface mixes, selection fills, and ink steps; every selected/current-state marker (calendar today, breadcrumb page, links, radio, nav bubble) speaks the brand-selected ink family in dark
+- **Tinted canvas** — the signature screen background (`--background-tinted-canvas`): a blue aurora melting into the canvas, pure token math, applied once on the page root
+- **The frosted family** — `variant="frosted"` (brand-tinted glass on page surfaces) and `variant="frosted-on-brand"` (white frost on art) across Button, NavigationButton, and Card
+- **No shadows** — elevation is hairlines and surface steps, with two sanctioned exceptions: the Bottom Navigation's floating-chrome lift and the Slide to Confirm handle's brand glow
+- **Pill shape system** — buttons and chips are pills, icon buttons are circles, cards 18px, menus 10px, form fields 4px; every control on the 32/40/48 rail
+- **AI-readable in `node_modules`** — AGENTS.md, all 58 component pages (Toggle and Toggle Group share one), foundations, and patterns ship inside the npm tarball
 - **TypeScript, ESM + CJS**
 
 ## Documentation
@@ -91,7 +95,7 @@ React 18+, ReactDOM, Tailwind CSS v4+.
 | [docs/foundations/shape-layout.md](./docs/foundations/shape-layout.md) | The 32/40/48 size rail, radius system, spacing, grid |
 | [docs/foundations/motion.md](./docs/foundations/motion.md) | The three-layer motion system: primitives → semantic roles → signature moves |
 | [docs/components/](./docs/components/) | One page per component: API, variants, tokens consumed, behaviour, do/don't |
-| [docs/patterns/](./docs/patterns/) | Forms (Field cascade), menus (shared family), on-brand surfaces & glass |
+| [docs/patterns/](./docs/patterns/) | Forms (Field cascade), menus (shared family), on-brand surfaces & the frosted recipe |
 
 ## Demo app
 
@@ -105,4 +109,4 @@ npm run dev   # Next.js demo at http://localhost:4000 — every component, light
 npm install @trading-game/design-intelligence-layer@latest --safe-chain-skip-minimum-package-age
 ```
 
-Deprecated token aliases and component aliases (e.g. Input `variant="inverse"`, NativeSelect `size="default"`) keep working until **v1.0**, when they are removed in one breaking sweep alongside the Champion Trade package rename.
+Deprecated token aliases and component aliases (e.g. Button `variant="glass"` → `frosted-on-brand`, Input `variant="inverse"`, NativeSelect `size="default"`) keep working throughout 1.x; they are removed in one breaking sweep at the **next major**, alongside the Champion Trade package rename.