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

package/guides/audits/design-system-audit-2026-07.md

@@ -0,0 +1,135 @@
+# Design System Audit — July 2026
+
+> **Who this is for:** the design owner of `@trading-game/design-intelligence-layer`.
+> **How to read it:** written in design language. Think of **tokens as Figma variables**, **semantic tokens as variable aliases**, and **components as your published library**. Code references appear in small print for whoever implements the fixes.
+> **How it was done:** three deep scans — the token files line-by-line, all 61 UI components, all 7 blocks — plus cross-checks of heights, corner radii, focus rings, icon sizes, and spacing.
+
+---
+
+## 1 — Scorecard
+
+| Category | Grade | Verdict |
+|---|---|---|
+| Token architecture | 🟡 B− | Right 3-layer structure (primitives → semantics → components), but several variables skip the chain and hold raw values. |
+| Semantic naming | 🟡 C+ | Two naming languages coexist: your custom `on-*` system and leftover shadcn `*-foreground` names. |
+| Color usage in components | 🔴 C− | ~13 components point at color variables that **don't exist** — error states and some separators render with no color. |
+| Sizing (control heights) | 🟢 A− | Core family (Button, Input, Select…) perfectly consistent at 24/32/40/48px. Three strays (Toggle, native select, Combobox) sit at an orphan 36px. |
+| Spacing & gaps | 🟢 B+ | Mostly on the 4/8-pt grid; a handful of odd one-off values (14px paddings, 18px badges). |
+| Typography | 🟡 B− | New scale is well-designed and documented — but it has **no variables underneath** (numbers are baked into the styles) and none of the 7 blocks use it yet. |
+| Theming | 🟡 B | Light-only by decision (no dark mode planned). Inverse tokens cover coloured surfaces. Fine as a policy — documented here so it's deliberate. |
+| Motion | 🟢 A | Fully tokenized durations and easings, primitive → semantic chain. The strongest category. |
+| Single source of truth | 🔴 D | Two copies of the token file exist (demo vs npm) and they have **drifted apart** — the demo doesn't show what consumers get. |
+| Docs & AI-readiness | 🟢 B+ | Guide, agent rules, and typography docs are current; missing a machine-readable token export. |
+
+**Overall: B−.** Strong bones, excellent consistency where migration was finished, undermined by leftover shadcn wiring and the two-file drift.
+
+---
+
+## 2 — The Good 🟢
+
+Things that already meet universal design-system standards:
+
+1. **Real 3-layer token architecture.** Raw palette → semantic meaning → component use, exactly how mature systems (Material, Polaris) structure variables. Primitives are in modern OKLCH color space.
+2. **The migrated control family is genuinely consistent.** Button, Input, Select, InputGroup, Chip, NavigationButton all share the same height ladder (24/32/40/48px), the same 4px corners, and the same 3px focus ring. This is the hardest thing to get right and it's right.
+3. **Motion is fully tokenized.** Durations and easings exist as primitives, get semantic names (`interactive`, `surface`, `overlay`), and components consume them. Rare even in professional systems.
+4. **31 of 61 components are completely clean.** No hardcoded colors, no off-token values.
+5. **Blocks use color tokens well.** Hero, FAQ, NavBar etc. consistently use `bg-prominent`, `text-on-subtle`, layout gutter tokens — no rogue hex colors (except deliberate third-party brand marks, see §6).
+6. **Dead shadcn tokens were deleted from the theme.** `muted`, `accent`, `destructive`, `chart-*` were correctly removed as theme variables. (The bug is that components still *reference* some of them — see The Worst.)
+7. **The new typography scale is well-designed** — sentence case, weight-led hierarchy, tightening tracking, fluid scaling — and it's documented for humans *and* AI agents.
+
+---
+
+## 3 — The Worst 🔴 (fix these first)
+
+### 3.1 — Invisible error states: components point at variables that don't exist
+
+**What it is.** When the system was customized from shadcn, the `destructive` (error red) and bare `border` color variables were deleted from the theme — but **~13 components still reference each**. In Figma terms: the variable was deleted from the library, but layers still point at the dead reference.
+
+**What this means for your design.** When a form field is invalid, the red border/ring **silently doesn't render**. Form error text, menu "delete" items, some separators, scrollbars, and keyboard-key chips can draw with no color. Users can miss errors entirely — this is a real usability bug, not a cosmetic one.
+
+**Affected:** error styling in Button, Input, Textarea, Select, InputGroup, InputOTP, RadioGroup, Toggle, Combobox, Form, Field, Menubar, DropdownMenu, ContextMenu; separator color in Separator, ScrollArea, Resizable, Kbd, Command, Chart, and menus. Also stragglers: `muted`/`accent` in Chart & Dialog & ContextMenu, bare `secondary` in Sheet, `foreground` in InputOTP.
+
+**The fix (safe, one-day).** Re-point the dead names at your existing variables: error red → your **Loss Red** (`--semantic-loss`), border → your **Border Subtle**. One change in the token file makes every error state visible again — no component edits needed. Then optionally sweep components later to use the proper names directly.
+<sub>`button.tsx:9`, `form.tsx:100,150`, `separator.tsx:20`, `kbd.tsx:10`, `scroll-area.tsx:52`, `command.tsx:136`, `sheet.tsx:78`, `input-otp.tsx:62`, `dialog.tsx:73`, `context-menu.tsx:69,129,147,172`, `chart.tsx:58` + ~10 more files.</sub>
+
+### 3.2 — Two drifted copies of your library
+
+**What it is.** Your tokens live in two files: one the demo site uses (`app/globals.css`), one that ships to npm (`src/styles.css`). They were meant to be identical mirrors. They aren't anymore — like two copies of the same Figma library where different edits landed in each.
+
+**What this means for your design.** The demo — your visual source of truth — **does not show what consumers actually get**. Concretely: the ticket-card shimmer animation is *defined differently* in each file (demo has the richer version); the shipped version sets base font smoothing the demo doesn't; a pulse animation exists only in the demo; the result-card motion exists only in the shipped file (so the demo never tests it); a few tokens (`avatar-size-xl`, `tracking-wide`) exist only in the demo, so consumers can't use them at all.
+
+**The fix (small build change).** Make the demo import the exact shipped file, keeping only demo-specific extras separate. One library, drift becomes impossible. Reconcile the current differences deliberately (keep the richer shimmer, adopt the shipped body rule, move demo-only tokens into the shipped file).
+<sub>`stub-shimmer`: globals:430-448 vs styles:429-432 · `body`: globals:483 vs styles:424 · `cta-pulse`: globals-only 417-427 · `results-motion`: styles-only 570-590 · `--avatar-size-xl` globals:111 · `--tracking-wide` globals:109.</sub>
+
+### 3.3 — Brand blue hardcoded inside the Button shimmer
+
+**What it is.** The `primary-inverse-shimmer` button variant paints its gleam with a literal `rgba(35,35,255,…)` — your brand blue **written out as a raw number** instead of referencing the primary token.
+
+**What this means for your design.** If you ever adjust your primary blue, every button follows the token — except this shimmer, which stays the old blue. Classic AI-hardcoding artifact.
+
+**The fix (30 min).** Derive the gradient from the primary variable.
+<sub>`button.tsx:86-88`.</sub>
+
+---
+
+## 4 — The Bad 🟡 (plan these)
+
+### 4.1 — Typography has no variables underneath
+Your new type scale exists as ready-made text styles (`display`, `heading-xl`…`overline`) — the equivalent of Figma text styles. But the numbers inside (56px, 64px line-height, -0.03em…) are **baked in**. There are no size/line-height/weight/tracking variables, and no desktop/mobile semantic layer (Figma variable modes equivalent).
+**Fix:** create type primitives (`--font-size-display`, `--line-height-display`, `--font-weight-display`, `--tracking-display`, etc.) with desktop and mobile values, rebuild the text styles from them. AI tools can then read your typography as data instead of parsing CSS.
+
+### 4.2 — All 7 blocks ignore the new type scale
+Every block heading hand-builds its typography (`text-5xl` + bold + tight tracking) instead of using your text styles — FAQ even re-creates your `overline` style from scratch, and Result-card headings skip the display font entirely.
+**What it means:** change the type scale, and none of your marketing/product blocks follow. Two sources of typographic truth.
+**Fix:** migrate all block headings/body text to the scale classes. Visible change — review each block after.
+<sub>hero:47,68 · faq:56,57,80,107-114 · auth:51 · result:64,67,91,123 · open-positions:66,85,193 · header-nav:44.</sub>
+
+### 4.3 — Three controls never joined the family
+Toggle, native Select, and Combobox still wear shadcn defaults: **36px height** (your ladder is 32/40/48) and **8px corners** (your controls use 4px). Two "select" controls exist with different heights and corners. A few more leftovers (Command, Menubar, NavigationMenu, InputOTP, Sidebar) use the orphan 36px/28px rungs.
+**Fix:** re-size to the family ladder and 4px corners. Visible change — verify side-by-side.
+<sub>toggle.tsx:10,19 · native-select.tsx:20 · combobox.tsx:236 · command:70 · menubar:17 · navigation-menu:62 · input-otp:54 · sidebar:496,696.</sub>
+
+### 4.4 — Broken variable chains inside the token file
+Several semantic variables hold raw color values instead of referencing a primitive — including a mystery near-black with a green tint (`oklch(0.07 0.012 165)`) repeated in three places that matches nothing in your palette, and a slider color that hand-copies a primitive's value instead of referencing it.
+**What it means:** edit the primitive palette and these won't follow — silent inconsistencies later.
+**Fix:** re-point each to the primitive it should come from; add a primitive where none exists.
+<sub>--subtle, --on-subtle, --border-subtle, --card-foreground, --popover-foreground, --sidebar-foreground, --sidebar-accent(-foreground), --slider-range (≡ --primitive-blue-alpha-40), --input-inverse-surface, --semantic-boost-surface.</sub>
+
+### 4.5 — Two naming languages
+Your custom convention says "text on X" = `on-*` (`on-primary`, `on-subtle`). The un-renamed shadcn sidebar/card/popover block still says `*-foreground`. Same concept, two names — confusing for humans and AI alike. Also an orphan: `secondary-hover` exists with no `secondary`.
+**Fix:** rename the leftovers into the `on-*` convention (keep old names as aliases during transition).
+
+### 4.6 — Missing variable categories
+No spacing scale variables, no elevation/shadow variables, no z-index (layer order) variables; breakpoints are magic numbers (320/600/1136). Universal systems tokenize all four. Motion, again, is the model to copy.
+
+### 4.7 — Odd one-off values in core components
+A frosted `white/5` fill in 4 input components (should be a surface token); off-scale text sizes in Alert (13px/11px), TicketCard (20px), Calendar (0.8rem); Button's large size uses a 14px vertical pad (off-grid) and a 14px icon written as an arbitrary value; a notification badge hand-built from three arbitrary values (18×18px, 10px text); off-token corner radii (Checkbox 2px, Slider 4px-arbitrary, InputGroup "radius minus 5px", Textarea 6px vs Input's 4px).
+
+### 4.8 — Small consistency drifts
+NavigationButton's focus ring omits the border tint others have; Sidebar uses a 2px ring (standard is 3px); NavigationMenu adds an outline on top; icon-to-box ratios differ between Button and NavigationButton at identical sizes; blocks split between two responsive strategies (`min-[600px]` media queries vs `@[600px]` container queries).
+
+---
+
+## 5 — Fix roadmap (gradual batches — each one you verify in the demo before it ships)
+
+| Batch | Contents | Effort | What you visually verify |
+|---|---|---|---|
+| **1 — Stop the bleeding** | Re-point dead `destructive`/`border` variables; fix shimmer blue; merge the two token files into one source | **S** (≈1 day) | Invalid inputs show a red border; separators/kbd chips visible; shimmer looks identical; demo pixel-identical otherwise |
+| **2 — Typography becomes variables** | Type primitives + desktop/mobile semantic layer; text styles rebuilt from variables; all 7 blocks adopt the scale | **M** | Typography page unchanged; every block heading matches the scale spec; resize = smooth scaling |
+| **3 — Bring strays into the family** | Toggle/native-select/Combobox to 32/40/48 + 4px corners; radius strays; leftover 36px rungs; focus-ring stragglers; `white/5` → token | **M** | Controls side-by-side: equal heights, equal corners, one focus style |
+| **4 — AI-ready polish** | Spacing/elevation/z-index variables; off-grid paddings; icon ratios; one responsive strategy; machine-readable `tokens.json` export | **M–L** | Spacing rhythm audit passes; AI tools can read tokens as data |
+
+Batch 1 has **zero intentional visual change** (it only repairs broken styling). Batches 2–3 change visible design on purpose — each ships as its own minor version so consuming projects upgrade deliberately.
+
+---
+
+## 6 — Accepted exceptions (policy — don't re-flag these)
+
+1. **Third-party brand colors** — Google's four-color G and Telegram blue in the sign-in buttons are brand marks and stay hardcoded by design. <sub>auth-block.tsx:100-124.</sub>
+2. **Numeric displays** — P&L amounts and balances use `tabular-nums` with bespoke sizing for alignment; they are data displays, not headings, and may stay off the heading scale. <sub>result-block.tsx:67, header-navigation-block.tsx:44, open-positions-block.tsx:178.</sub>
+3. **Toast styling workaround** — the toast library (Sonner) requires `!important`-style overrides; they reference real tokens, just in an unusual syntax. Acceptable. <sub>toast.tsx:34-37.</sub>
+4. **Light-only theming** — a deliberate product decision (no dark mode planned). The inverse-token family covers dark surfaces where needed.
+
+---
+
+*Audit date: 14 Jul 2026 · Scope: `src/styles.css`, `app/globals.css`, 61 files in `components/ui/`, 7 files in `components/blocks/` · Method: exhaustive automated scans + manual verification of every flagged line.*

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

@@ -122,6 +122,62 @@ Token rules apply **only** to: color (bg, text, border, ring, shadow color), bor
 
 ---
 
+## 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 4 — Do NOT install or configure these separately
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trading-game/design-intelligence-layer",
-  "version": "0.17.4",
+  "version": "1.0.1",
   "description": "Trading Game Design System — shadcn/ui components with Tailwind CSS v4",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -29,11 +29,13 @@
     "build:next": "next build",
     "start": "next start",
     "lint": "eslint",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "check:tokens": "node scripts/check-token-docs.mjs"
   },
   "files": [
     "dist/",
     "src/styles.css",
+    "docs/",
     "guides/",
     "AGENTS.md"
   ],
@@ -46,7 +48,6 @@
     "tailwindcss": ">=4"
   },
   "dependencies": {
-    "@base-ui/react": "^1.2.0",
     "@hookform/resolvers": "^5.2.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -57,11 +58,10 @@
     "lucide-react": "^0.577.0",
     "radix-ui": "^1.4.3",
     "react-day-picker": "^9.14.0",
-    "react-hook-form": "^7.71.2",
     "react-resizable-panels": "^4.7.1",
-    "recharts": "^2.15.4",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
+    "tw-animate-css": "^1.4.0",
     "vaul": "^1.1.2",
     "zod": "^4.3.6"
   },
@@ -79,7 +79,6 @@
     "shadcn": "^3.8.5",
     "tailwindcss": "^4",
     "tsup": "^8.5.1",
-    "tw-animate-css": "^1.4.0",
     "typescript": "^5"
   }
 }