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

package/docs/components/badge.md

@@ -21,7 +21,7 @@ Non-interactive status pill — emphasis (solid or tint) crossed with meaning (b
 | Prop | Type | Default | Notes |
 | --- | --- | --- | --- |
 | `variant` | `"solid" \| "solid-demo" \| "solid-neutral" \| "solid-success" \| "solid-fail" \| "solid-warning" \| "tint" \| "tint-demo" \| "tint-neutral" \| "tint-success" \| "tint-fail" \| "tint-warning"` | `"solid"` | Emphasis + meaning grid; brand is the unsuffixed default. |
-| `size` | `"xs" \| "sm" \| "md" \| "lg"` | `"md"` | Heights 20 / 24 / 32 / 40. |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "count"` | `"md"` | Heights 20 / 24 / 32 / 40. |
 | `asChild` | `boolean` | `false` | Render onto a caller element. Badges are read-only markers — no hover states exist (interactive pills are Chips). |
 
 The `glass` variant was removed (breaking change); there is no replacement — use `tint` on imagery-free surfaces.
@@ -46,11 +46,29 @@ import { Badge } from "@trading-game/design-intelligence-layer"
 | `md` | 32px | `px-3 py-1` | 14/20 |
 | `lg` | 40px | `px-4 py-1.5` | 16/24 |
 
+### `count`
+
+`size="count"` is a shape, not a step on the xs/sm/md/lg rail: an 18px disc whose minimum
+width equals its height, so one digit is a circle and more digits grow it into a pill at the
+same height. `tabular-nums` fixes the digit width, so a ticking count only resizes when the
+number of digits changes, not on every update.
+
+Conventions the caller owns, not the component: hide the badge at zero, and cap above 99 as
+`99+`. Pinning it over other chrome needs a knockout ring in the colour of whatever is
+behind it — Badge cannot know that, so the caller adds it:
+
+```tsx
+<Badge aria-hidden size="count"
+  className="absolute -top-0.5 -right-0.5 ring-2 ring-background-primary-canvas">
+  {count > 99 ? "99+" : count}
+</Badge>
+```
+
 ## Tokens
 
 **Colour (semantic):**
 - Solid: `background-brand-default` + `text-on-brand-static`; `background-demo-solid`; `background-inverse-surface` + `text-prominent-inverse`; `background-success-solid` / `background-error-solid` / `background-warning-solid`, all with `text-on-status-static`.
-- Tint: `--background-brand-container` (layered static recipe, painted via `[background:…]`) + `text-brand-container-static`; `background-demo-default` + `text-demo-default`; `background-secondary-surface` + `text-prominent-default`; `background-success/error/warning-default` + matching `text-*` status tokens. All tints are borderless — the tinted fill alone carries the meaning.
+- Tint: `background-brand-selected` + `text-brand-selected` (the theme-aware selection family, same recipe as Calendar's range band); `background-demo-default` + `text-demo-default`; `background-secondary-surface` + `text-prominent-default`; `background-success/error/warning-default` + matching `text-*` status tokens. All tints are borderless — the tinted fill alone carries the meaning.
 - The `tint-demo` / `tint-success` / `tint-fail` / `tint-warning` fills are one family by construction: a light `-50` step in light, and the hue's base step at **24% over the canvas** in dark. `tint-demo` gained its dark override so it stops reading as a light chip beside Won/Lost/Pending; note ember's base step is 500, not 600, because it is a game accent rather than a status colour.
 - Focus: `ring-focus-strong`.
 
@@ -59,8 +77,7 @@ import { Badge } from "@trading-game/design-intelligence-layer"
 ## Behaviour
 
 - Status solids use the bright 600 fills with shared static white ink (`text-on-status-static`) — deliberately below AA on green and amber; a style call, not an oversight.
-- `tint` (brand) paints the layered `--background-brand-container` value via arbitrary `background`, so a `bg-*` utility cannot override it — replace the whole `[background:…]` if you must.
-- `tint` (brand) is the one tint that stays light in dark, because `--background-brand-container` is a deliberately static icy panel shared with Calendar's selection. It sits outside the status/demo tint family on purpose.
+- `tint` (brand) flips with the theme like every other tint: `blue-600 @ 10%` over white in light, `blue-400 @ 24%` over the canvas in dark, with `blue-200` ink. It was the last variant on the static `--background-brand-container`; that token now has no consumers.
 - No hover states — badges are read-only markers; if it needs to be clickable, it's a [Chip](./chip.md).
 - `rounded-full`, `border-transparent` on every variant — no outlines, no shadow.
 

package/docs/components/item.md

@@ -13,7 +13,7 @@ Generic list row — media, title/description, and actions in one flex shell, wi
 
 - `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`.
+- `Item` — the row (`rounded-2xl`, 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"`.
@@ -27,13 +27,13 @@ Generic list row — media, title/description, and actions in one flex shell, wi
 
 | 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`. |
+| `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`/`fill`/`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`. |
+| `variant` | `"default" \| "outline" \| "fill" \| "muted"` | `"default"` | default transparent; outline = hairline `border-border-default-default` + hover glaze, no fill; **fill** = solid `bg-background-primary-surface` + the same hairline, hover steps to `background-secondary-surface`; muted = `bg-background-secondary-surface`, no border. |
 | `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`. |
 
@@ -73,11 +73,29 @@ import { BellIcon } from "lucide-react"
 </ItemGroup>
 ```
 
+### Picking between `outline` and `fill`
+
+Both draw the same hairline. They differ only on a **non-white** background:
+
+- On a Card, Sheet or Popover they are identical at rest — pick either.
+- On `background-primary-canvas` (a game screen, a ledger page), `outline` lets the canvas
+  show through and the row reads as part of the page. `fill` gives the row its own solid
+  plane — the wallet-ledger pattern, and the right default for trade lists.
+
+Every variant sits on `rounded-2xl` (18px) — the card radius Card, Dialog and Popover use.
+An Item is a content shell, not a menu row, so it takes the card corner rather than the
+tighter `rounded-md` it used previously.
+
+`fill` hover steps `primary-surface` -> `secondary-surface` rather than using the shared
+`background-hover-default` glaze, which is translucent and would let the canvas through a
+filled row instead of darkening it. The same override is repeated for `[a]:` because the
+base link hover uses that glaze and outranks a plain `hover:` on an anchor.
+
 ## Tokens
 
 **Colour (semantic):**
 - title `text-text-prominent-default`; description `text-text-subtle-default` (links underline, hover `text-text-brand-selected`)
-- outline: `border-border-default-default`, hover `bg-background-hover-default`; muted: `bg-background-secondary-surface`
+- outline: `border-border-default-default`, hover `bg-background-hover-default`; fill: `bg-background-primary-surface` + `border-border-default-default`, hover `bg-background-secondary-surface`; 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`
@@ -96,10 +114,10 @@ import { BellIcon } from "lucide-react"
 
 **Do**
 - Let `ItemGroup` draw dividers; only reach for `ItemSeparator` with `divider={false}`.
-- Use `rounded-md` rows as-is — 8px is the row radius tier.
+- Leave the radius alone — Item is `rounded-2xl` (18px), the card tier, not the 8px row 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 mix `variant="outline"` or `variant="fill"` 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.
+- Don't add shadows to muted/outline/fill rows; state is shown by fill and hairline only.

package/docs/foundations/colors.md

@@ -53,7 +53,7 @@ All scales run 50→1000 (mono 50→1200; blue adds 25 and 1000 as the two canva
 | `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-brand-container` | white 92% glaze over blue-600 (layered) | static — same | The icy brand panel. **No current consumers** — Calendar's range band and Badge `tint` both moved to `background-brand-selected` because a static value cannot carry dark. Retained for the v1.0 sweep. **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) |
@@ -80,7 +80,7 @@ All scales run 50→1000 (mono 50→1200; blue adds 25 and 1000 as the two canva
 | `text-on-brand-static` | mono-50 | static | White text on brand fills — never flips |
 | `text-on-brand-subtle-static` | white-alpha-64 | static | Secondary copy on a brand fill. On brand the ladder **inverts** — it descends from white through the alpha rungs instead of climbing the mono ramp (3.8:1 on blue-600, 2.7:1 on blue-400) |
 | `text-on-brand-disabled-default` | white-alpha-32 | white-alpha-24 | Disabled ink on a brand fill — 1.8:1 over blue-600, 1.5:1 over blue-400. **Not static**, unlike the rest of the on-brand family: the fill itself flips blue-600 → blue-400, and blue-400 caps white at 4.3:1, so the rung comes down with it. Replaces the `opacity-24` wash on on-brand variants |
-| `text-brand-container-static` | blue-600 | static | Ink on `background-brand-container` |
+| `text-brand-container-static` | blue-600 | static | Brand ink on a **static white** surface — Button `on-brand`, Toast's action button, Input selection. Still in use; do not retire with `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) |
@@ -109,7 +109,7 @@ Several values are **recipes, not scale steps** — a solid base with a fixed la
 - **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)`.
+- **Brand container**: a real two-layer paint (white 92% glaze over blue-600) — consume via `background: var(--background-brand-container)`. Nothing consumes it today: it is static by construction, so anything needing a brand tint that survives dark takes `background-brand-selected` instead.
 - **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.
 

package/docs/foundations/shape-layout.md

@@ -24,9 +24,9 @@ Radius encodes the element's *class*, not taste:
 |---|---|---|
 | 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`) |
+| Cards & panels | `rounded-2xl` = **18px** | Card, Dialog, Alert Dialog, Popover, Hover Card, Empty shell, **Item** (every variant — a content shell, not a menu row), 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 |
+| Rows inside menus/lists | `rounded-md` = **8px** | Menu items, 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 |
 

package/guides/brand-voice/trading-game-brand-voice.md

@@ -1,6 +1,6 @@
 # trading.game — Brand voice
 
-**Version:** 2.0 · April 2026
+**Version:** 2.1 · September 2026
 **Adds:** Channel-specific voice application per persona mode; anti-AI writing rules for all copy
 
 ---
@@ -106,7 +106,7 @@ The tone is not the same for all three modes. Edge Seekers respond to validation
 Give them something to be early on. Frame the product as a read, not a game.
 
 > "Vol 100 has been oscillating inside a 12-point range for three sessions.
-> Rise & Fall is pricing that in. If you've been watching it, now's the time."
+> Rise-Fall is pricing that in. If you've been watching it, now's the time."
 
 > "The fastest feedback loop on a market read.
 > Five ticks. Real price data. No waiting for a daily close."
@@ -163,7 +163,7 @@ Subject lines that work are different by mode:
 
 **Edge Seeker:**
 - "Your read on V_100 paid out."
-- "Rise & Fall is running on Vol 200. Your call."
+- "Rise-Fall is running on Vol 200. Your call."
 - "The chart moved where you said it would."
 
 **System Runner:**
@@ -228,7 +228,7 @@ State the thing. Then the implication for the player. Don't lead with your feeli
 
 | ✅ | ❌ |
 |---|---|
-| "Rise & Fall now runs on V_200. Higher vol, wider payout range. Check the multiplier before you trade." | "We're excited to announce an exciting new instrument! Amazing opportunity for all traders!" |
+| "Rise-Fall now runs on V_200. Higher vol, wider payout range. Check the multiplier before you trade." | "We're excited to announce an exciting new instrument! Amazing opportunity for all traders!" |
 | "Digits is live. Tick-based prediction on the last digit of a price feed. 1–10 ticks, six contract types." | "Introducing Digits, our innovative new game that revolutionises the prediction experience!" |
 | "Withdrawal processing is now instant. Not 'faster.' Instant." | "We've made some improvements to our withdrawal process for a more seamless experience." |
 
@@ -266,9 +266,9 @@ The other difference: HyperSwap assumes DeFi fluency. We can't. Some players hav
 
 | HyperSwap register | trading.game register |
 |---|---|
-| "SWAP Genesis is live. Early believers get rewarded 🔥" | "Rise & Fall is live on V_100. Edge is 2%. The rest is skill." |
+| "SWAP Genesis is live. Early believers get rewarded 🔥" | "Rise-Fall is live on V_100. Edge is 2%. The rest is skill." |
 | "Swappies, the airdrop is coming 🚀" | "Your win rate this week: 54%. Baseline is 50%. You're ahead." |
-| "Earn boosted rewards for LPs 💰" | "Transferred 20 USDT to GridRush. Your capital, your call." |
+| "Earn boosted rewards for LPs 💰" | "Transferred 20 USDT to Box-O. Your capital, your call." |
 
 ---
 
@@ -292,11 +292,10 @@ The other difference: HyperSwap assumes DeFi fluency. We can't. Some players hav
 
 | Correct | Not |
 |---|---|
-| Rise & Fall | Rise and Fall / Rise/Fall |
-| GridRush | Grid Rush / Grid rush |
-| Swipe Cards | Swipe-Cards / SwipeCards |
+| Rise-Fall | Rise & Fall / Rise and Fall / Rise/Fall |
+| Box-O | BoxO / Box O / GridRush |
+| Swipe | Swipe Cards / Swipe-Cards / SwipeCards |
 | Digits | The Digits game |
-| Dice | The Dice game |
 
 ### Formatting
 
@@ -322,4 +321,4 @@ Before publishing anything:
 
 ---
 
-*trading.game Brand Voice — v2.0*
+*trading.game Brand Voice — v2.1*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",

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.