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

package/AGENTS.md

@@ -1,231 +1,104 @@
-# AI Agent Instructions — @trading-game/design-intelligence-layer
-
-This file is read automatically by AI coding agents (Cursor, Windsurf, Claude Code, Copilot, and others) to understand how to build with this design system correctly.
-
----
-
-## Step 1 — Read all design intelligence files first
-
-Before building any landing page, product screen, game view, or feature UI, you MUST read all four files:
-
-**Design principles** — the decision framework for every layout, hierarchy, motion, copy, and component choice:
-```
-node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md
-```
-
-**Accessibility standards** — the inclusion standard every screen must meet (WCAG 2.1 AA):
-```
-node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md
-```
-
-**Personas** — the three player modes (Edge Seeker, System Runner, Public Predictor) that shape all copy and UX decisions:
-```
-node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md
-```
-
-**Brand voice** — channel-specific voice application, banned phrases, vocabulary reference, and formatting rules for all player-facing copy:
-```
-node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md
-```
-
-All four files apply to all projects built with this package — landing pages, product screens, and games.
-
-Run the checklists at the end of the design principles and accessibility standards files before considering any screen complete. Use the personas and brand voice to guide all player-facing copy.
-
----
-
-## Step 2 — Read the component and token rules
-
-You MUST also follow the full agent rules file:
-
-```
-node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc
-```
-
-**Cursor users:** Copy this file into `.cursor/rules/` after every package upgrade:
-
-```bash
-cp node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc .cursor/rules/
-```
-
----
-
-## Step 3 — Core rules summary
-
-1. **Check before building** — if a component exists in `@trading-game/design-intelligence-layer`, import it. Never re-implement it.
-2. **Tokens only** — use semantic token classes (`bg-prominent`, `text-on-prominent`, `border-border`, etc.). Never hardcode hex values, raw Tailwind palette colors, or CSS variables.
-3. **Design principles and accessibility first** — every screen must reflect the 8 design principles and meet the accessibility standards (WCAG 2.1 AA). Run both checklists before shipping.
-4. **No separate installs** — do not install `lucide-react`, `tailwindcss`, or other bundled dependencies separately.
-5. **After a version bump** — re-copy the rules file into `.cursor/rules/`, check for stale local component copies, and align them with the package.
-6. **Blocks are first-class exports** — Blocks (Hero, Auth, FAQ, NavBar, HeaderNavigation, OpenPositions, Result) are exported from the package the same as primitives. Import them by name and pass data via props. See the `## Blocks` section below for the full catalog.
-
----
-
-## Step 4 — New-component release checklist (MANDATORY)
-
-Every time you add a new component (UI primitive or Block) to this package, **all** of the following must land in the same PR. Skipping any one of these has shipped broken releases before — npm consumers got a version where the component existed in the demo but couldn't be imported. Do not skip a step.
-
-1. **Source file** — `components/ui/<name>.tsx` (or `components/blocks/<name>-block.tsx`)
-2. **Public export** — add the matching `export * from "../components/<…>/<name>"` line to `src/index.ts`. **This is what gates whether npm consumers receive the component at all.** The demo at `app/page.tsx` imports via the `@/components/...` alias and will work without this — but the published package will not ship the component until this line exists.
-3. **Auto-generated registry** — run `npm run generate:registry` so `app/component-registry.generated.ts` picks the new file up.
-4. **Demo entry** — add a sidebar entry in the `componentNames` list in `app/page.tsx`, and a `case "<Name>":` block in the `SectionContent` switch that renders representative variants.
-5. **README** — add a row in the "Available components" table and a per-component section explaining variants / slots / behaviour.
-6. **Design system guide** (`guides/design-system-guide/trading-game-ds-guide.md`) — add a row in the §8 component list table and a styling-notes entry covering tokens used, edge cases, and `aria` posture.
-7. **Build verification** — run `npm run build` and confirm the component name appears in `dist/index.js` and `dist/index.d.ts` before tagging a release:
-   ```bash
-   npm run build
-   grep -c "<ComponentName>" dist/index.js dist/index.d.ts   # both > 0
-   ```
-8. **Version + publish** — only after every step above is checked in, bump `package.json`, commit, push, tag `v<version>`, and let the workflow publish.
-
-If any of these are missing at the time of release, the published package is broken — fix and re-release before moving on.
-
----
-
-## Reference
-
-- Full token + component reference: `node_modules/@trading-game/design-intelligence-layer/README.md`
-- Design principles: `node_modules/@trading-game/design-intelligence-layer/guides/design-principles/trading-game-design-principles.md`
-- Accessibility standards: `node_modules/@trading-game/design-intelligence-layer/guides/accessibility-standards/trading-game-accessibility-standards.md`
-- Personas: `node_modules/@trading-game/design-intelligence-layer/guides/personas/trading-game-player-field-guide.md`
-- Brand voice: `node_modules/@trading-game/design-intelligence-layer/guides/brand-voice/trading-game-brand-voice.md`
-- Full agent rules: `node_modules/@trading-game/design-intelligence-layer/guides/rules/design-system-consuming-project.mdc`
-
----
-
-## Blocks
-
-The package ships eight opinionated, composed blocks alongside the UI primitives. Each block is a single `import` away and accepts data via props. Variants are modeled as a `variant` / `layout` / `mode` prop on one block, not as separate components.
-
-### `HeroBlock`
-
-Marketing hero section with centred or split-column layout.
-
-```tsx
-import { HeroBlock } from "@trading-game/design-intelligence-layer"
-
-<HeroBlock
-  layout="centered"                                        // "centered" | "split"
-  tagline={{ label: "What's new", suffix: "v2.0" }}
-  heading="Solve your customer's main problem"
-  body="One or two sentences expanding on the value prop."
-  primaryCta={{ label: "Get started", onClick: ... }}
-  secondaryCta={{ label: "Learn more", onClick: ... }}    // split layout only
-/>
-```
-
-### `AuthBlock`
-
-Sign-in / sign-up form with OAuth providers, divider, email input, terms, and cross-link.
-
-```tsx
-import { AuthBlock } from "@trading-game/design-intelligence-layer"
-
-<AuthBlock
-  mode="sign-in"                                          // "sign-in" | "sign-up"
-  logoSrc="/path/to/brand-icon.svg"
-  providers={["google", "telegram", "x"]}                 // default: all three
-  onSubmit={({ email }) => { ... }}
-  crossLinkHref="/auth/signup"
-/>
-```
-
-### `FAQBlock`
-
-Eyebrow + heading + intro + accordion + optional "Need more help" card.
-
-```tsx
-import { FAQBlock } from "@trading-game/design-intelligence-layer"
-
-<FAQBlock
-  layout="desktop"                                        // "desktop" | "mobile"
-  items={[{ value: "q1", question: "...", answer: "..." }, ...]}
-  intro={<>Optional intro paragraph with a <Link>link</Link>.</>}
-  helpCard={{ title: "Need more help?", body: "...", ctaLabel: "Contact us" }}
-/>
-```
-
-### `NavBarBlock`
-
-Responsive marketing nav with brand mark, link buttons, sign-in/up CTAs, and an internal mobile drawer.
-
-```tsx
-import { NavBarBlock } from "@trading-game/design-intelligence-layer"
-
-<NavBarBlock
-  brand={{ fullLogoSrc: "...", iconLogoSrc: "...", alt: "Brand" }}
-  links={[{ label: "Products" }, { label: "Docs" }, ...]}
-  signIn={{ onClick: ... }}
-  signUp={{ onClick: ... }}
-/>
-```
-
-### `HeaderNavigationBlock`
-
-In-app trading header (back · badge · balance · history · action slot). History icon supports an overlaid count badge in `bg-primary`.
-
-```tsx
-import { HeaderNavigationBlock } from "@trading-game/design-intelligence-layer"
-
-<HeaderNavigationBlock
-  onBack={() => router.back()}
-  badge={{ label: "Demo", variant: "fill-warning" }}
-  balance={{ amount: "1000.00", currency: "USDT" }}
-  history={{ count: 5, onClick: openHistorySheet }}        // count 0 hides badge; >99 shows "99+"
-  actions={<SoundToggleButton />}
-/>
-```
-
-### `OpenPositionsBlock`
-
-Responsive Sheet (desktop) / Drawer (mobile) containing a list of game positions. Positions are a discriminated union by `kind`: `"rise-fall" | "swipe" | "box-o" | "digits"`.
-
-```tsx
-import { OpenPositionsBlock, Position } from "@trading-game/design-intelligence-layer"
-
-const positions: Position[] = [
-  { kind: "rise-fall", direction: "Rise", market: "Vol 100", duration: "30 minutes",
-    stake: "1.00 USDT", pnl: "+0.96 USDT", win: true },
-  ...
-]
-
-<OpenPositionsBlock
-  trigger={<Button variant="secondary">Active trades</Button>}
-  positions={positions}
-  sheetTitle="Positions"
-  onViewHistory={openHistoryPage}
-/>
-```
-
-### `ResultBlock`
-
-Universal win/loss result card with animated halo + thumb illustration + contract badge + duration badge + CTA. Thumb icons are bundled inside the package.
-
-```tsx
-import { ResultBlock } from "@trading-game/design-intelligence-layer"
-
-<ResultBlock
-  status="win"                                             // "win" | "loss"
-  amount="10,000.00"
-  currency="USDT"
-  contractLabel="Rise"
-  duration="2 hours"
-  pickedDigit={7}                                          // optional, for Digits contracts
-  ctaMode="next-round"                                     // "next-round" | "go-again" | "conversion"
-/>
-```
-
-### `ResultDialog`
-
-Fixed-width system dialog (title + body + two CTAs). Used for messages like "out of balance".
-
-```tsx
-import { ResultDialog } from "@trading-game/design-intelligence-layer"
-
-<ResultDialog
-  title="You're out of balance."
-  body="Deposit to keep playing or stay in demo mode."
-  primaryLabel="Deposit now"
-  secondaryLabel="Stay in demo"
-/>
-```
+# AGENTS.md — Champion Trade Design System
+
+Rules of engagement for AI agents building with `@trading-game/design-intelligence-layer` (the package renames to Champion Trade at v1.0). Read this first; deep detail lives in [docs/](./docs/).
+
+## Hard rules — never break these
+
+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.
+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.
+8. **Typography via type classes.** Component text uses its `.type-<component>-*` class (backed by private `--<component>-*` tokens). No `text-sm`, no `text-[13px]`, no `font-bold`.
+9. **`.type-*` classes are plain CSS, not utilities**: variants can't gate them (`data-[x]:type-foo` does nothing — pick the class in JSX or write a CSS data-attribute rule), and they beat layered `font-*` utilities.
+10. **Radius encodes element class** — buttons/chips `rounded-full`, icon buttons circles, cards/dialogs `rounded-2xl`, menus `rounded-lg`, menu rows `rounded-md`, inputs `rounded-xs` (deliberate, don't "fix" it).
+11. **Sizes sit on the 32/40/48 rail**, default `md` (40px). Button padding-x = height/2 − 4, gap 8, and padding never changes when icons are hidden.
+12. **Focus** = `focus-visible:ring-[3px] focus-visible:ring-ring-focus-strong` (controls) or `ring-ring-focus-soft` (text fields). Error ring = `ring-ring-error-soft`. Every colour must be a plain named token — no alpha-modified constructions, no colour primitives outside the sanctioned glass-ladder set; `npm run check:tokens` enforces both and diffs the Colors page against styles.css.
+
+## Composition patterns
+
+- **Forms**: wrap controls in `Field` — `<Field size="sm">` cascades its size into Input / Select / Native Select / Input Group automatically (explicit size on the control wins). Field's `data-invalid` paints label + error red through inheritance. Helper text is 12/16 at every size. See [docs/patterns/forms.md](./docs/patterns/forms.md).
+- **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.
+
+## Anti-patterns (seen in the wild — don't repeat)
+
+- `data-[state=active]:font-semibold` next to a `.type-*` class → silently loses; use the CSS data-attribute weight rule pattern.
+- `bg-white/5` or any translucent resting surface → use the solid surface tokens.
+- A new component colour token (`--mycomponent-bg`) → forbidden; colour stops at the semantic layer.
+- `position="item-aligned"` on Select → the default is `popper` (list drops below the trigger); don't switch back without a reason.
+- Re-adding `xs` button sizes, Kbd, Collapsible, Ticket Card, Chart, Combobox, Form, or the Badge `glass` variant — all removed by design decisions.
+
+## Component index — when to use what
+
+Docs: `docs/components/<kebab-name>.md` for every entry.
+
+| Component | Use it for |
+|---|---|
+| Accordion | Collapsible FAQ-style content sections |
+| Alert Dialog | Blocking confirm/cancel decisions (destructive actions) |
+| Aspect Ratio | Fixed-ratio media containers |
+| Avatar | User images with fallback initials, groups, count overflow |
+| Badge | Small status/category markers (solid, tint, outline; status = 600 fills) |
+| Banner | Editorial gradient promo panel with art, copy, white pill CTA |
+| Bottom Navigation | Mobile bottom nav, max 4 destinations (3 is the norm) — chrome frost bar, liquid selection bubble; the phone counterpart of Sidebar |
+| 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 |
+| Carousel | Horizontally scrolling content (mobile catalogue) |
+| Chip | Compact choice pills: quick amounts, single-select filters, outline error-recovery |
+| Checkbox | Boolean form input |
+| Command | Searchable command palette (menu family) |
+| Context Menu | Right-click menus (menu family) |
+| Dialog | Centred modal panels for tasks/forms |
+| Drawer | Bottom/top/side sheets on mobile (vaul); grab handle on bottom |
+| Dropdown Menu | Click-triggered action menus (menu family) |
+| Empty | Zero-state placeholder with icon tile, title, action |
+| Field | Form field wrapper: label + control + helper/error, size cascade |
+| Hover Card | Rich hover preview panel (a floating card) |
+| Input | Single-line text field; sizes sm/md/lg; `on-brand` variant |
+| Input Group | Things inside a field: prefix/suffix text, icons, pill buttons |
+| Input OTP | Segmented one-time-code entry |
+| Item | List rows with media/title/description/actions (default, outline, muted) |
+| Label | Form label (14/medium); colour inherits so Field error ink flows through |
+| 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 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 |
+| Popover | Click-triggered floating card for small forms/details |
+| Profile Photo | Avatar with verification ring, camera slot, status badge |
+| Progress | Determinate progress bar (brand fill on 20% wash track) |
+| Radio Group | Single choice among few options |
+| Resizable | Split-pane layouts with drag handles |
+| Scroll Area | Custom scrollbars on constrained regions |
+| Section Message | Inline status messaging (info/success/warning/danger; sm/md; row/stack) |
+| Select | Custom dropdown picking (menu family rows; opens below trigger) |
+| Separator | Hairline dividers |
+| Sheet | Side/top/bottom panels (Radix Dialog based, desktop-oriented) |
+| Sidebar | Desktop app navigation rail; selected rows use the selected family |
+| 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 |
+| 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 |
+| 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.
+
+## Demo & source of truth
+
+- `npm run dev` → localhost:4000 — every component in light/dark.
+- Token definitions: `src/styles.css` (mirrored in `app/globals.css` — **edit both**).
+- Turbopack gotcha: token/class changes need a full `.next/` wipe + restart, not just HMR.