@trading-game/design-intelligence-layer 1.0.7 → 1.2.0

package/guides/rules/design-system-consuming-project.mdc

@@ -1,366 +0,0 @@
----
-description: Enforce correct usage of the @trading-game/design-intelligence-layer npm package. Apply whenever building UI in a project that has the package installed — before writing any component, layout, or styled element.
-globs: ["**/*.tsx", "**/*.jsx", "**/*.ts", "**/*.css"]
-alwaysApply: true
----
-
-# @trading-game/design-intelligence-layer — AI Agent Usage Rules
-
-## Rule 1 — Check the package before writing any custom UI
-
-**BEFORE** writing any `<div>`, `<button>`, `<span>`, or other element styled with Tailwind classes, you MUST check if a component already exists in `@trading-game/design-intelligence-layer`.
-
-### Available components (check this list first)
-
-Accordion, Alert, AlertDialog, AspectRatio, Avatar, AvatarGroup, Badge, **Banner**, Breadcrumb, Button, Calendar, Card, Carousel, Chart, Checkbox, **Chip**, Collapsible, Combobox, Command, ContextMenu, Dialog, Direction, Drawer, DropdownMenu, Empty, Field, Form, HoverCard, Input, InputGroup, InputOTP, Item, Kbd, Label, **Link**, Menubar, NativeSelect, NavigationButton, NavigationMenu, Pagination, Popover, Progress, RadioGroup, Resizable, ScrollArea, Select, Separator, Sheet, Sidebar, Skeleton, Slider, Spinner, **Stepper**, Switch, Table, Tabs, Textarea, **TicketCard / CreditTicketCard**, Toast/Toaster, **ResultSnackbar**, Toggle, ToggleGroup, Tooltip
-
-### Decision flow
-
-```
-Does a component exist in the list above?
-  YES → Import it from @trading-game/design-intelligence-layer. Do NOT re-implement it.
-  NO  → STOP. Tell the user:
-        "The [ComponentName] component does not exist in @trading-game/design-intelligence-layer.
-         Options:
-         (a) Build a custom one using design system tokens only
-         (b) Use a different existing component
-         (c) Skip this component"
-        Wait for user to choose. Do NOT proceed without confirmation.
-```
-
-### Correct import pattern
-
-```tsx
-import { Button, Card, Badge } from "@trading-game/design-intelligence-layer"
-```
-
----
-
-## Rule 2 — Token-only rule (applies to ALL code, including approved custom builds)
-
-### Never use
-
-```
-❌ Hardcoded hex:         #2323FF, #000000, rgba(0,0,0,0.5)
-❌ Raw Tailwind palette:  bg-gray-100, text-zinc-500, text-slate-400, bg-black, bg-white
-❌ Arbitrary color:       bg-[#EEEEEE], text-[rgba(35,35,255,0.1)]
-❌ Raw CSS var:           bg-[var(--border-subtle)]  ← NEVER do this
-❌ hsl(var()) syntax:     hsl(var(--primary))  ← this is Tailwind v3, not v4
-❌ Raw opacity on non-tokens: bg-black/50
-```
-
-### Always use semantic token classes
-
-#### Background tokens
-```
-✅ bg-prominent           — page background (white #FFFFFF)
-✅ bg-card                — card/panel surface (white #FFFFFF)
-✅ bg-popover             — popover/dropdown surface (white #FFFFFF)
-✅ bg-subtle              — subtle tinted surface (#F5F5F5)
-✅ bg-overlay             — modal/dialog backdrop (black 50%) — ONLY for overlays
-✅ bg-primary             — brand blue #2323FF — CTAs and primary actions
-✅ bg-primary-hover       — darker blue #0B0BD2 — primary button hover
-✅ bg-primary-inverse     — white surface for use on dark/coloured areas
-✅ bg-prominent-inverse   — dark surface for use on light pages (toasts, etc.)
-✅ bg-secondary-hover     — light grey #EEEEEE — outline/secondary button hover
-✅ bg-semantic-win        — green — profit/positive
-✅ bg-semantic-loss       — red — loss/negative
-✅ bg-semantic-warning    — orange — warning/caution
-✅ bg-semantic-boost      — amber-orange #F9840F — boost/bonus badge (tinted: bg-semantic-boost/16)
-```
-
-#### Text tokens — paired with a surface
-
-> Convention: `bg-<surface>` always has a paired `text-on-<surface>` foreground. Use them together for guaranteed legibility.
-
-```
-✅ text-on-prominent          — paired with bg-prominent (black #000000) — default body text
-✅ text-on-prominent-inverse  — paired with bg-prominent-inverse (white) — toast text, etc.
-✅ text-on-primary            — paired with bg-primary (white) — primary button label, tooltip text
-✅ text-on-primary-inverse    — paired with bg-primary-inverse (blue) — primary-inverse button label
-✅ text-on-semantic-win       — paired with bg-semantic-win (white)
-✅ text-on-semantic-loss      — paired with bg-semantic-loss (white)
-✅ text-on-semantic-warning   — paired with bg-semantic-warning (white)
-✅ text-on-semantic-boost     — paired with bg-semantic-boost (dark amber #713813)
-✅ text-on-subtle             — secondary text (aliases text-subtle-default: mono-800 #717171 light / mono-600 #AAAAAA dark)
-✅ text-on-disabled           — disabled / inactive text (aliases text-disabled-default: mono-400 #C6C6C6 light / mono-900 #555555 dark)
-
-✅ text-primary               — brand blue #2323FF — inline brand text over neutral surfaces
-✅ text-semantic-win          — green — profit/positive inline text
-✅ text-semantic-loss         — red — loss/negative inline text
-```
-
-> ⚠️ **Deprecated:** `text-on-prominent-static-inverse` still works (aliased to `--on-prominent-inverse`) but new code should pick the explicit `text-on-<surface>` for whatever background sits behind the text.
-
-#### Border tokens
-```
-✅ border-border-subtle    — light grey #EEEEEE — default UI borders, dividers, cards
-✅ border-border-prominent — pure black #000000 — outline variant components
-✅ border-border           — @deprecated alias for border-subtle (still works, prefer border-border-subtle)
-✅ border-input            — input field borders (same value as border-subtle)
-✅ ring-ring               — focus ring (blue #2323FF)
-```
-
-#### Opacity on a token is fine
-```
-✅ bg-primary/20, border-border-subtle/50, ring-ring/10
-```
-
----
-
-## Rule 3 — Layout utilities are exempt
-
-Structural Tailwind utilities are freely usable without token rules:
-
-```
-✅ flex, grid, gap-4, p-6, m-2, w-full, h-screen, max-w-lg
-✅ z-50, overflow-hidden, opacity-50, transition-all
-✅ col-span-2, items-center, justify-between
-```
-
-Token rules apply **only** to: color (bg, text, border, ring, shadow color), border radius, and font family.
-
----
-
-## Rule 3.5 — Typography: use the type scale, never hand-written sizes
-
-**MANDATORY decision procedure for ANY text you render.** Do not choose font sizes. Every piece of text gets its size, line-height, and weight from one of the 13 scale classes below — this is what keeps every screen's hierarchy identical.
-
-### Step 1 — Is there a component for it?
-
-If the text lives in a component slot, USE THE COMPONENT — every component carries its own typography internally (via private component tokens or a built-in scale class):
-`DialogTitle` / `AlertDialogTitle` / `SheetTitle` / `DrawerTitle` / `EmptyTitle`, `CardTitle`, every `*Description` slot, `Label` / `FieldLabel` / `FieldTitle` / `ItemTitle`, `AccordionTrigger` / `AccordionContent`, `Button` — never hand-style any component's text.
-
-### Step 2 — Freeform text: pick from the scale
-
-| Class        | Size / line | Weight        | Use for                                                |
-| ------------ | ----------- | ------------- | ------------------------------------------------------ |
-| `display`    | 36→56 fluid | ExtraBold 800 | Hero statement on a landing/marketing page             |
-| `h1`         | 30→40 fluid | Bold 700      | The single main title of a page/screen (ONE per page)  |
-| `h2`         | 26→32 fluid | Bold 700      | A major section heading                                |
-| `h3`         | 22→24 fluid | SemiBold 600  | A sub-group heading inside a section                   |
-| `h4`         | 20 / 28     | SemiBold 600  | A dashboard panel / large feature-card header          |
-| `h5`         | 18 / 24     | SemiBold 600  | Dialog, sheet, and drawer titles (freeform)            |
-| `h6`         | 16 / 24     | SemiBold 600  | A card / compact panel title (freeform)                |
-| `body-lg`    | 18 / 28     | Regular 400   | Intro / lead paragraph                                 |
-| `body-md`    | 16 / 24     | Regular 400   | Default body text                                      |
-| `body-sm`    | 14 / 20     | Regular 400   | Description under a title, helper copy                 |
-| `label-text` | 14 / 20     | Medium 500    | Form label, list-item title, table header (freeform)   |
-| `caption`    | 12 / 16     | Medium 500    | Metadata, timestamps, fine print                       |
-| `overline`   | 12 / 16     | SemiBold 600  | Eyebrow above a heading, tag (uppercases itself)       |
-
-**`h1`–`h6` are STYLE names, not HTML tags.** Put the class on whatever element the document outline needs — `<h2 className="h4">` is correct and normal when heading level and visual size legitimately differ. Never let the class name pick the tag for you.
-
-```tsx
-✅ <h1 className="h1 text-on-prominent">Account settings</h1>
-✅ <h2 className="h2 text-on-prominent">Security</h2>
-✅ <p className="body-sm text-on-subtle">Manage your sign-in methods.</p>
-✅ <span className="overline text-primary">New</span>   {/* uppercases itself */}
-```
-
-### Hard rules
-```
-❌ NEVER hand-build titles/body from utilities (text-2xl font-bold tracking-tight, text-[13px]…)
-❌ NEVER uppercase a heading — the system is sentence-case; only `overline` uppercases (automatically)
-❌ NEVER add responsive size overrides (md:text-*, sm:text-*) to a scale class — display and
-   h1–h3 already scale desktop→mobile via their tokens. A class NEVER changes between
-   breakpoints: h2 on desktop is h2 on mobile.
-❌ NEVER use more than one h1 per page; never skip more than one hierarchy level
-❌ NEVER tweak a scale class with utilities (h5 font-medium does nothing — scale classes are
-   unlayered CSS and beat utilities). Need something different? Use a different class.
-✅ Emphasis inside body text: <b>/<span> + font-semibold on that span — never a bigger size
-✅ Numeric data displays (P&L, balances) are the accepted exception: bespoke size + tabular-nums
-✅ A SMALLER class passed via className overrides a component's built-in one (stylesheet is
-   ordered largest→smallest), e.g. <EmptyTitle className="h6"> for compact contexts
-```
-
-> Naming notes: `overline` is also a Tailwind text-decoration utility — the package's class wins and clears the line. The label class is `label-text` (not `label`) to avoid confusion with the `Label` component.
-
----
-
-## Rule 3.6 — Result Snackbar is for a settled game result, and nothing else
-
-`ResultSnackbar` exists for exactly one thing: reporting a **settled contract the player was not watching** — a win or a loss, with its figure.
-
-```
-Did a contract just settle, win or loss, off-screen?
-  YES → ResultSnackbar
-  NO  → toast(...)          // everything else
-```
-
-Use `toast(...)` — never `ResultSnackbar` — for:
-
-- **Refunds.** Nothing was won or lost, so there is no figure to report. A refund is a non-event.
-- **Trade rejections, live payout warnings, connection problems**, and every other notification.
-- Anything that needs an **action** from the player. `ResultSnackbar` is pointer-transparent by design: it is a report, not a control.
-
-And do not use it for the contract the player **was** watching as it ended — that gets the full-screen result moment. `ResultSnackbar` deliberately does not take the board.
-
-It is never the surface of record either. Every result also lands in positions and history, which is where a player goes to study terms.
-
-**Why the two look nothing alike:** that difference is intentional, not drift. `toast` is transient system messaging on the inverse surface. `ResultSnackbar` reports money: floating-chrome glass, an illustration, a signed figure in outcome ink, and a visible dwell timer. Do not "unify" them.
-
-```tsx
-import { ResultSnackbar } from "@trading-game/design-intelligence-layer"
-
-<ResultSnackbar
-  outcome="win"                 // "win" | "loss" — the only two states
-  amount="+8.40"                // pre-signed; use a true Unicode minus for losses
-  amountValue={8.4}             // optional count-up target
-  currency="USDT"
-  contractLabel="Rise"
-  duration="15 seconds"
-  icon={<img src="/thumbs-up.webp" alt="" aria-hidden className="size-8" />}
-  onDismiss={advanceQueue}      // fires once, after the exit finishes
-  className="absolute top-3 right-3"   // placement is yours; anchor it to something meaningful
-/>
-```
-
-Placement and queueing are the consumer's: the meaningful anchor differs per game, and deciding what waits, what is stale, and what replays after an interruption is product logic. The component shows one settlement and reports when it is done.
-
----
-
-## Rule 4 — Do NOT install or configure these separately
-
-```
-❌ Do NOT install lucide-react — it is already bundled in the package
-❌ Do NOT install tailwindcss separately — the package ships its own Tailwind v4 setup
-❌ Do NOT add a tailwind.config.js — configuration is handled by the package
-❌ Do NOT use @apply with hsl(var(--token)) — Tailwind v4 uses CSS variables directly
-❌ Do NOT override font-family manually in CSS — use font-display and font-body utility classes
-```
-
-### Correct CSS setup in the consuming project
-
-```css
-@import "@trading-game/design-intelligence-layer/styles";
-@import "tailwindcss";
-@source "../node_modules/@trading-game/design-intelligence-layer/dist";
-```
-
-### Vite projects — required plugin
-
-If the project uses Vite, `@tailwindcss/vite` MUST be in `vite.config.js`:
-
-```js
-import tailwindcss from '@tailwindcss/vite'
-// plugins: [react(), tailwindcss()]
-```
-
-Without this, Tailwind CSS will not process any styles. Next.js projects do NOT need this.
-
----
-
-## Rule 5 — Button and Badge variants
-
-### Button variants
-```tsx
-// Light surfaces
-<Button variant="primary" />           // Blue filled — main CTA
-<Button variant="secondary" />         // Black outline — secondary actions
-<Button variant="tertiary" />          // Text only — minimal
-
-// Dark / coloured surfaces
-<Button variant="primary-inverse" />   // White filled + blue text — main CTA on dark bg
-<Button variant="secondary-inverse" /> // White outline + white text — secondary on dark bg
-```
-
-All variants support icon sizes — use `size="icon-lg|icon-md|icon-sm|icon-xs"` for icon-only buttons on any variant:
-```tsx
-<Button variant="primary-inverse" size="icon-md"><Bell /></Button>
-<Button variant="secondary-inverse" size="icon-sm"><X /></Button>
-```
-
-### Badge variants
-```tsx
-// Solid
-<Badge variant="default" />         // Blue solid
-<Badge variant="standard" />        // Subtle grey solid
-<Badge variant="default-success" /> // Green solid
-<Badge variant="default-fail" />    // Red solid
-<Badge variant="default-warning" /> // Orange solid
-
-// Tint
-<Badge variant="fill" />            // Blue tint bg
-<Badge variant="fill-success" />    // Green tint bg
-<Badge variant="fill-fail" />       // Red tint bg
-<Badge variant="fill-warning" />    // Orange tint bg
-<Badge variant="fill-credit" />     // Deep peach (#FDCA8A) + bold amber text — credit/boost (Welcome credit, bonus)
-<Badge variant="fill-demo" />       // Peach + red-orange text — demo / test-mode indicator
-
-// Outline (black border, hover grey)
-<Badge variant="outline" />
-
-// Ghost (transparent bg)
-<Badge variant="ghost" />
-<Badge variant="ghost-success" />
-<Badge variant="ghost-fail" />
-<Badge variant="ghost-warning" />
-```
-
----
-
-## Rule 6 — If in doubt, stop and ask
-
-If you cannot find a token for a value you need, do NOT fall back to a hardcoded value.
-
-Stop and tell the user:
-```
-"I need [value] for [element]. No design token exists for this.
-Should I: (a) use a hardcoded value, or (b) skip this styling?"
-```
-
-Wait for confirmation before proceeding.
-
----
-
-## Rule 8 — Blocks are first-class exports (import them by name)
-
-**Blocks** are opinionated, composed UI sections — exported from `@trading-game/design-intelligence-layer` the same as primitives. Import by name and pass data via props. Variants live as a `layout` / `mode` / `status` prop on a single block, not as separate components.
-
-```
-✅ Import blocks directly from the package — same pattern as primitives
-✅ Pass data via props; variants are configured via a single variant prop
-✅ Block names ARE valid component names (treat them like Rule 1 components)
-❌ Do NOT re-implement a block by hand if a block export already covers it
-❌ Do NOT split variants into separate blocks — use the variant prop
-```
-
-| Block | Variants | Importable? |
-|-------|----------|-------------|
-| `HeroBlock` | `layout: "centered" \| "split"` | Yes — `import { HeroBlock }` |
-| `AuthBlock` | `mode: "sign-in" \| "sign-up"` | Yes — `import { AuthBlock }` |
-| `FAQBlock` | `layout: "desktop" \| "mobile"` | Yes — `import { FAQBlock }` |
-| `NavBarBlock` | — (internal mobile-menu state) | Yes — `import { NavBarBlock }` |
-| `HeaderNavigationBlock` | — (optional `history.count` badge) | Yes — `import { HeaderNavigationBlock }` |
-| `OpenPositionsBlock` | `Position` discriminated union | Yes — `import { OpenPositionsBlock, type Position }` |
-| `ResultBlock` | `status` + `ctaMode` | Yes — `import { ResultBlock }` |
-| `ResultDialog` | — | Yes — `import { ResultDialog }` |
-
-See `guides/design-system-guide/trading-game-ds-guide.md` § 8.5 for full per-block API, used components, and used tokens.
-
----
-
-## Rule 7 — Package version upgrades (stay aligned with the published design system)
-
-When the user asks to **update**, **upgrade**, or **install the latest** `@trading-game/design-intelligence-layer`, or after the dependency version changes in `package.json`:
-
-### How updates actually apply
-
-- If the project **imports components only** from `@trading-game/design-intelligence-layer`, new styles and behavior come from **`node_modules/.../dist`** after **`npm install` / `npm ci` and a dev or production build**. The package is the source of truth — no AI step is required for those imports to change.
-- If the repo **contains copied or forked** files that mirror package components (e.g. a local `components/ui/button.tsx` with full implementation), **`npm install` does not update those files.** They stay stale until someone reconciles them.
-
-### What you MUST do after a design-system version bump
-
-1. **Search for local duplication** — Look for UI files that re-implement package exports (`components/ui/`, `@/components/ui`, etc.). Flag any file that is not a **thin re-export** or **documented wrapper** around the package.
-2. **Reconcile** — Prefer **removing** duplicate implementations and **importing from the package**. If a fork must stay, align it with the **exact** current implementation in the installed package (or tag on GitHub) and document why it diverges (file name + reason).
-3. **Notify on replace** — If you **delete, replace, or substantially overwrite** local component code to match the package, **stop and tell the user clearly**, e.g.  
-   `Aligned [ComponentName] with @trading-game/design-intelligence-layer@[version]. Previous local behavior or classes: [short summary]. Re-apply needs via package variants/props, tokens, or a thin wrapper only if product requires it.`
-4. **Review `className` overrides** — Parent apps often pass `className` on DS components. Old overrides (radius, colors, shadows) can **hide** new defaults (e.g. pill buttons). After upgrade, scan for overrides on DS components and trim or adjust them when they conflict with the new design.
-5. **Refresh Cursor rules** — The package ships `guides/rules/design-system-consuming-project.mdc`. Cursor does **not** read it from `node_modules` automatically. Tell the user to re-copy it (see README **AI Agent Setup → Cursor**) so agent instructions match the release.
-6. **Tailwind** — Confirm `@source` still points at `node_modules/@trading-game/design-intelligence-layer/dist` so Tailwind v4 emits classes from the updated bundle.
-
-### Do not assume
-
-- Do **not** assume `npm update` alone fixed forked files in the app repo.
-- Do **not** silently delete user customizations — always report what was removed or replaced and offer a token-safe way to re-apply if needed.