@hanzo/design 0.2.0 → 0.3.1

package/dist/tokens.gen.js

@@ -44,7 +44,7 @@ export const colors = {
     'destructive-foreground': '#f5f5f5',
     'border': '#1f1f1f',
     'input': '#1f1f1f',
-    'ring': '#333333',
+    'ring': 'var(--neutral-500)',
     'brand': '#e4e4e7',
     'brand-foreground': '#09090b',
     'brand-muted': '#a3a3a3',
@@ -56,9 +56,14 @@ export const colors = {
     'surface-card-quiet': 'rgb(23 23 23 / .4)',
     'surface-overlay': 'rgb(10 10 10 / .95)',
     'surface-header': 'rgb(0 0 0 / .7)',
+    'surface-scrim': 'rgb(0 0 0 / .8)',
     'border-hairline': 'var(--neutral-800)',
     'border-card': 'var(--white-10)',
-    'border-strong': 'var(--neutral-700)',
+    'border-strong': 'var(--neutral-500)',
+    'surface-0': 'var(--background)',
+    'surface-1': 'var(--card)',
+    'surface-2': 'var(--muted)',
+    'surface-3': 'var(--secondary)',
     'text-primary': 'var(--pure-white)',
     'text-secondary': 'var(--white-80)',
     'text-tertiary': 'var(--white-60)',
@@ -97,6 +102,23 @@ export const typography = {
     'leading-6xl': '1',
     'text-7xl': '4rem',
     'leading-7xl': '1',
+    'text-8xl': '5.25rem',
+    'leading-8xl': '1',
+    'text-9xl': '7rem',
+    'leading-9xl': '1',
+    'font-size-xs': 'var(--text-xs)',
+    'font-size-sm': 'var(--text-sm)',
+    'font-size-base': 'var(--text-base)',
+    'font-size-lg': 'var(--text-lg)',
+    'font-size-xl': 'var(--text-xl)',
+    'font-size-2xl': 'var(--text-2xl)',
+    'font-size-3xl': 'var(--text-3xl)',
+    'font-size-4xl': 'var(--text-4xl)',
+    'font-size-5xl': 'var(--text-5xl)',
+    'font-size-6xl': 'var(--text-6xl)',
+    'font-size-7xl': 'var(--text-7xl)',
+    'font-size-8xl': 'var(--text-8xl)',
+    'font-size-9xl': 'var(--text-9xl)',
     'weight-normal': '400',
     'weight-medium': '500',
     'weight-semibold': '600',
@@ -176,6 +198,12 @@ export const elevation = {
     'shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
     'shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
     'ring-focus': '0 0 0 2px var(--ring)',
+    'shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+    'shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+    'shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+    'shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+    'shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+    'shadow-2xl': 'var(--shadow-floating)',
     'glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     'glow-hero-blur': '120px',
     'sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -207,6 +235,8 @@ export const zIndex = {
     'z-modal': '600',
     'z-popover': '700',
     'z-toast': '800',
+    'z-tooltip': 'var(--z-popover)',
+    'z-notification': 'var(--z-toast)',
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export const fonts = {
@@ -261,7 +291,7 @@ export const cssVars = {
     '--destructive-foreground': '#f5f5f5',
     '--border': '#1f1f1f',
     '--input': '#1f1f1f',
-    '--ring': '#333333',
+    '--ring': 'var(--neutral-500)',
     '--brand': '#e4e4e7',
     '--brand-foreground': '#09090b',
     '--brand-muted': '#a3a3a3',
@@ -273,9 +303,14 @@ export const cssVars = {
     '--surface-card-quiet': 'rgb(23 23 23 / .4)',
     '--surface-overlay': 'rgb(10 10 10 / .95)',
     '--surface-header': 'rgb(0 0 0 / .7)',
+    '--surface-scrim': 'rgb(0 0 0 / .8)',
     '--border-hairline': 'var(--neutral-800)',
     '--border-card': 'var(--white-10)',
-    '--border-strong': 'var(--neutral-700)',
+    '--border-strong': 'var(--neutral-500)',
+    '--surface-0': 'var(--background)',
+    '--surface-1': 'var(--card)',
+    '--surface-2': 'var(--muted)',
+    '--surface-3': 'var(--secondary)',
     '--text-primary': 'var(--pure-white)',
     '--text-secondary': 'var(--white-80)',
     '--text-tertiary': 'var(--white-60)',
@@ -311,6 +346,23 @@ export const cssVars = {
     '--leading-6xl': '1',
     '--text-7xl': '4rem',
     '--leading-7xl': '1',
+    '--text-8xl': '5.25rem',
+    '--leading-8xl': '1',
+    '--text-9xl': '7rem',
+    '--leading-9xl': '1',
+    '--font-size-xs': 'var(--text-xs)',
+    '--font-size-sm': 'var(--text-sm)',
+    '--font-size-base': 'var(--text-base)',
+    '--font-size-lg': 'var(--text-lg)',
+    '--font-size-xl': 'var(--text-xl)',
+    '--font-size-2xl': 'var(--text-2xl)',
+    '--font-size-3xl': 'var(--text-3xl)',
+    '--font-size-4xl': 'var(--text-4xl)',
+    '--font-size-5xl': 'var(--text-5xl)',
+    '--font-size-6xl': 'var(--text-6xl)',
+    '--font-size-7xl': 'var(--text-7xl)',
+    '--font-size-8xl': 'var(--text-8xl)',
+    '--font-size-9xl': 'var(--text-9xl)',
     '--weight-normal': '400',
     '--weight-medium': '500',
     '--weight-semibold': '600',
@@ -381,6 +433,12 @@ export const cssVars = {
     '--shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
     '--shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
     '--ring-focus': '0 0 0 2px var(--ring)',
+    '--shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+    '--shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+    '--shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+    '--shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+    '--shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+    '--shadow-2xl': 'var(--shadow-floating)',
     '--glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     '--glow-hero-blur': '120px',
     '--sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -406,6 +464,8 @@ export const cssVars = {
     '--z-modal': '600',
     '--z-popover': '700',
     '--z-toast': '800',
+    '--z-tooltip': 'var(--z-popover)',
+    '--z-notification': 'var(--z-toast)',
     '--font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
     '--font-display': 'var(--font-sans)',
     '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',

package/docs/README.md

@@ -8,7 +8,7 @@ If you remember one thing: **import one file, then reach for a token instead of
 literal.** Do that and your surface is already 90% on-brand.
 
 ```css
-@import "@hanzoai/design/styles.css";
+@import "@hanzo/design/styles.css";
 ```
 
 ## The map

package/docs/integrate.md

@@ -3,14 +3,14 @@
 ## 1. Install
 
 ```bash
-pnpm add @hanzoai/design
+pnpm add @hanzo/design
 ```
 
 ## 2. Import the tokens — once
 
 ```css
 /* app/globals.css, or the root of your styles */
-@import "@hanzoai/design/styles.css";
+@import "@hanzo/design/styles.css";
 ```
 
 That one file pulls in, in order: fonts (Geist + Geist Mono), color, typography,
@@ -54,8 +54,8 @@ Each part ships as `.jsx` + `.d.ts` + a `.prompt.md` usage guide. They are
 self-contained (inline styles), so they need no framework:
 
 ```jsx
-import { Button } from "@hanzoai/design/components/core/Button.jsx";
-import { HanzoLogo } from "@hanzoai/design/components/core/HanzoLogo.jsx";
+import { Button } from "@hanzo/design/components/core/Button.jsx";
+import { HanzoLogo } from "@hanzo/design/components/core/HanzoLogo.jsx";
 
 <HanzoLogo />
 <Button pill>Get started</Button>

package/guidelines/DESIGN.md

@@ -0,0 +1,106 @@
+# Hanzo Design System — Canonical Tokens
+
+`@hanzo/ui` is the single source of truth for the shared Hanzo product look across
+the **Tailwind** apps (hanzo.chat, hanzo.app, hanzo console, commerce, hanzo-desktop).
+Change a value here; apps converge on it. This file is that source of truth for the
+three things that must read as **one product**: typography, the sidebar/panel system,
+and the dark-black palette.
+
+> One library: **`@hanzo/ui@8`** (`pkg/ui`, on **`@hanzo/gui`**) IS the component
+> library — the cross-platform product/record layer every surface consumes.
+> **`@hanzo/ui-shadcn`** (`pkgs/ui`) is the legacy shadcn/Tailwind/Radix kit, kept
+> only for existing v5 consumers (pin `@hanzo/ui-shadcn@^5`; no new adoptions).
+> This file stays the source of truth for the *token values* (fonts, dark palette,
+> the sidebar glyph) both render.
+
+---
+
+## 1. Typography — Basel Grotesk + Geist Mono
+
+| Role | Family | Notes |
+|------|--------|-------|
+| UI / body / display / heading (`sans`) | **Basel Grotesk** | Self-hosted. Book = weight **400**, Medium = weight **500**. |
+| code / data / mono (`mono`) | **Geist Mono** | `next/font/google` (`Geist_Mono`) or the geist CDN. |
+| Arabic / Hebrew (`--font-ar` / `--font-he`) | unchanged | i18n only — keep. |
+
+**Dropped as defaults:** Geist Sans, DM Sans, Figtree, Inter, PT Sans, Roboto Mono.
+
+Basel is a **licensed, non-Google** face — **self-host** the woff2/woff, do NOT use
+`next/font/google` for it. Canonical files (mirror lux.exchange):
+`Basel-Grotesk-Book.woff2/.woff` (400), `Basel-Grotesk-Medium.woff2/.woff` (500).
+
+`@font-face` (weights 400/500, `font-display: swap`, `font-style: normal`):
+
+```css
+@font-face {
+  font-family: 'Basel';
+  font-style: normal;
+  font-weight: 400; /* Book; 500 = Medium */
+  font-display: swap;
+  src: url('.../Basel-Grotesk-Book.woff2') format('woff2'),
+       url('.../Basel-Grotesk-Book.woff') format('woff');
+}
+```
+
+Per-app adoption (converge the value, keep each app's own mechanism):
+- **@hanzo/ui / Next apps** → `next/font/local` for Basel (`--font-basel-sans`) +
+  `next/font/google` `Geist_Mono` (`--font-geist-mono`). See `app/lib/fonts.ts`;
+  tailwind `sans → var(--font-basel-sans)`, `mono → var(--font-geist-mono)`.
+- **Vite + Tailwind apps** (chat, launcher, desktop) → self-host Basel `@font-face`
+  + geist-mono CDN import; tailwind `fontFamily.sans = ['Basel', …]`,
+  `mono = ['Geist Mono', …]`.
+- **Tamagui (console)** → Basel `@font-face` in globals + override the Tamagui
+  `body`/`heading` font `family` to Basel; Geist Mono for `code`/`pre`.
+
+---
+
+## 2. Sidebar toggle icon — lucide `PanelLeft`
+
+One glyph everywhere: lucide **`PanelLeft`** (the shadcn `SidebarTrigger` default).
+Where a directional open/close affordance is wanted, use the pair
+**`PanelLeftClose`** (expanded) / **`PanelLeft`** (collapsed). Never a hamburger,
+a magnifier, a directional arrow, or a bespoke panel SVG for the sidebar toggle.
+
+- Icon: stroke-2, ~16–20px, `currentColor`.
+- Button: ghost/outline, square (`size-7`/`h-6 w-6`), subtle hover.
+
+---
+
+## 3. Sidebar + panels
+
+| Spec | Value |
+|------|-------|
+| Sidebar width (expanded) | **16rem / 256px** (`SIDEBAR_WIDTH`) |
+| Sidebar width (collapsed / icon rail) | **3rem / 48px** (apps vary 48–70px) |
+| Sidebar / panel surface | resting **#0a0a0a** over the true-black page |
+| Border / separation | `border-border` — subtle white-alpha ~10% in dark (`border-r` / `border-l`) |
+| Item hover | subtle `white/5` |
+| Item active | monochrome `white/10` — **no colored accent** (the house style is monochrome) |
+| Right panel rail | `border-l border-border`, same surface, collapsible |
+
+Prefer the `@hanzo/ui` `Sidebar` primitive (`pkgs/ui/primitives/sidebar.tsx`,
+`SidebarTrigger` → `PanelLeft`) where the app can consume it; otherwise match these
+classes/tokens.
+
+---
+
+## 4. Dark-black palette (true-black OLED)
+
+The house dark theme is a **true-black** canvas (matches hanzo.ai marketing +
+hanzo.chat OLED), with a shallow surface-depth ladder for cards/panels and quiet
+hairline borders — never harsh pure-white on pure-black.
+
+| Token | Value | Use |
+|-------|-------|-----|
+| Page background | **#000000** (`oklch(0 0 0)`) | body / canvas |
+| Surface / sidebar / panel (resting) | **#0a0a0a** | sidebars, panels, cards |
+| Press | **#050505** | pressed surface |
+| Elevated / hover | **#171717** | hover, raised card |
+| Border / divider | **rgba(255,255,255,0.10)** (≈ `#171717` opaque on black) | hairlines |
+| Foreground (primary text) | near-white **#ededf1** (`oklch(0.985)`) — not pure `#fff` | body text |
+| Muted / secondary text | `white/70` (≈ `#a1a1aa`) | secondary |
+
+Keep each app's theme-token engine (CSS vars / Tailwind tokens / Tamagui `$color*`);
+converge the **values/usage** to the table above, don't rip the engine.
+
+Reference: `pkgs/ui/style/hanzo-default-colors.css` (`.dark` / `.hanzo-ui-dark-theme`).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hanzo/design",
-  "version": "0.2.0",
-  "description": "Hanzo Design System \u2014 monochrome, dark-default tokens + components + brand assets, the single source of truth for every Hanzo surface. CSS + typed programmatic tokens.",
-  "license": "MIT",
+  "version": "0.3.1",
+  "description": "Hanzo Design System — monochrome, dark-default tokens + components + brand assets, the single source of truth for every Hanzo surface. CSS + typed programmatic tokens.",
+  "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
     "url": "https://github.com/hanzoai/design.git"
@@ -25,12 +25,15 @@
     "./components/*": "./components/*",
     "./prompts/*": "./prompts/*",
     "./content/*": "./content/*",
-    "./assets/*": "./assets/*"
+    "./assets/*": "./assets/*",
+    "./skills/*": "./skills/*"
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "build": "npm run gen && tsc -p tsconfig.json",
-    "prepublishOnly": "npm run build"
+    "test": "node scripts/check-tokens.mjs && node scripts/lint.mjs components",
+    "build": "npm run gen && npm test && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "lint": "node scripts/lint.mjs"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -42,6 +45,8 @@
     "tokens",
     "components",
     "prompts",
+    "skills",
+    "scripts",
     "content",
     "docs",
     "assets",
@@ -58,5 +63,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "hanzo-design-lint": "./scripts/lint.mjs"
   }
-}
+}

package/prompts/README.md

@@ -1,5 +1,10 @@
 # prompts — make an AI build it Hanzo
 
+> **Entry point is `skills/design-system/SKILL.md`**, not this folder. The skill
+> is what chat, hanzo.app and Claude Code load; it points here for the long form
+> and finishes by running `hanzo-design-lint`. Everything below is the reference
+> the skill cites.
+
 Guidance an agent reads *before* generating a Hanzo surface. Two layers, no
 overlap:
 
@@ -20,7 +25,14 @@ place.
 Everything here assumes one import gives you the tokens:
 
 ```css
-@import "@hanzoai/design/styles.css";
+@import "@hanzo/design/styles.css";
 ```
 
 So every rule below can be obeyed with a CSS variable, never a hardcoded hex.
+
+## The two prompts (one and one way)
+- **`system.md`** — the design LANGUAGE prompt: paste as a system prompt to make any
+  model generate Hanzo-looking output (monochrome, true-black, token-only).
+- **`studio-designer.md`** — the AGENTIC prompt Hanzo Studio's Design System designer
+  hands the Hanzo agent stack to GENERATE/EDIT this repo's file tree with its file
+  tools, grounded in `guidelines/DESIGN.md`. Uses `system.md`'s language rules.

package/prompts/studio-designer.md

@@ -0,0 +1,41 @@
+# Hanzo Studio — Design System Designer (agentic prompt)
+
+The system prompt the Studio "Design System" designer hands to the Hanzo agent
+stack. The agent generates/edits the design-system file tree in **hanzoai/design**
+using its file tools (write/edit/tree), grounded in the canon.
+
+---
+
+You are the **Hanzo Design System designer**, an agent operating on the
+`hanzoai/design` repository. You produce and maintain a complete, coherent design
+system as real files, using your file tools (read, write, edit, tree).
+
+## The canon (never contradict)
+- **Typography:** Basel Grotesk (`sans`, weights 400 Book / 500 Medium, self-hosted
+  woff2) + Geist Mono (`mono`). No Inter/Roboto/DM Sans as defaults.
+- **Palette:** true-black OLED. Page `#000`, surface `#0a0a0a`, press `#050505`,
+  elevated `#171717`, border `rgba(255,255,255,.10)`, text `#ededf1`. **Monochrome —
+  no colored accents.** Semantic color only for live/error/warning.
+- **Sidebar:** 256px expanded / 48px rail; lucide `PanelLeft` toggle; `white/5` hover,
+  `white/10` active.
+- Full source: `guidelines/DESIGN.md`.
+
+## Structure you own
+`tokens/` (base·colors·fonts·spacing·radius·elevation·motion.css + TS modules) ·
+`guidelines/` · `assets/{brand,logos,providers,fonts}` · `components/` · `ui_kits/`.
+
+## How you work
+1. **Read before writing.** `tree` the repo + read `guidelines/DESIGN.md` and the
+   relevant `tokens/*` so every new value stays consistent with what exists.
+2. **Tokens are the source.** A component reads token vars (`var(--hz-*)`), never a
+   hardcoded hex/px. If a needed token is missing, add it to `tokens/` first, then use it.
+3. **One and one way.** One place per value. Don't duplicate a color/space/font.
+4. **Generate real, coherent files** — a request like "add a Card component" writes
+   `components/card.{css,tsx,md}` referencing the tokens + a usage note, not a mock.
+5. **Honor the request scope.** "Generate a design system" → the full tree from the
+   canon. "Add elevation tokens" → just `tokens/elevation.css` + wire into `base.css`.
+6. **Never fabricate brand assets.** Reference real files in `assets/`; if a logo/font
+   is missing, note it as a TODO, don't invent bytes.
+7. **Explain what you wrote** (files + why) so the review is legible.
+
+Output: the files, written to the repo, plus a one-paragraph summary of the change.

package/prompts/system.md

@@ -12,7 +12,7 @@ and frontier models. Every surface you produce obeys one atom:
 
 ## Foundation
 
-- **Import once.** `@import "@hanzoai/design/styles.css";` gives you every token
+- **Import once.** `@import "@hanzo/design/styles.css";` gives you every token
   as a CSS custom property. Use the variables. Never write a raw hex, rgb, px
   font-size, or magic z-index — if you reach for a literal, there is a token for
   it and you are doing it wrong.

package/scripts/check-tokens.mjs

@@ -0,0 +1,93 @@
+// check-tokens.mjs — the gate. Every defect this file tests for was, at some
+// point, LIVE and SILENT: an undefined custom property paints nothing, an
+// unimported token file resolves nothing, and a 1.66:1 focus ring looks fine to
+// whoever shipped it. None of them can fail loudly on their own, so they fail
+// here. Run via `npm test` (part of `build`).
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const tokensDir = join(root, 'tokens')
+const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '')
+const read = (p) => readFileSync(p, 'utf8')
+
+let failures = 0
+const fail = (msg) => { console.error(`  FAIL  ${msg}`); failures++ }
+const pass = (msg) => console.log(`  ok    ${msg}`)
+
+// ── 1. styles.css must serve every token file ────────────────────────────
+// tokens/z.css was authored, exported and documented — and left out of
+// styles.css, so the whole ladder resolved to nothing on every consumer.
+{
+  const entry = read(join(root, 'styles.css'))
+  const files = readdirSync(tokensDir).filter((f) => f.endsWith('.css'))
+  const missing = files.filter((f) => !entry.includes(`tokens/${f}`))
+  missing.length
+    ? fail(`styles.css does not import: ${missing.join(', ')}`)
+    : pass(`styles.css serves all ${files.length} token files`)
+}
+
+// ── 2. every var() used inside the token layer must resolve ──────────────
+{
+  const declared = new Set()
+  const used = new Map() // name -> file
+  for (const f of readdirSync(tokensDir).filter((f) => f.endsWith('.css'))) {
+    const css = strip(read(join(tokensDir, f)))
+    for (const [, n] of css.matchAll(/--([A-Za-z0-9-]+)\s*:/g)) declared.add(n)
+    for (const [, n] of css.matchAll(/var\(\s*--([A-Za-z0-9-]+)/g)) if (!used.has(n)) used.set(n, f)
+  }
+  const ghosts = [...used].filter(([n]) => !declared.has(n))
+  ghosts.length
+    ? ghosts.forEach(([n, f]) => fail(`tokens/${f} references --${n}, which nothing declares`))
+    : pass(`all ${used.size} internal var() references resolve`)
+}
+
+// ── 3. the non-text contrast gate (WCAG 1.4.11 / 2.4.11) ─────────────────
+// A focus indicator and a control boundary must clear 3:1 against EVERY surface
+// they can land on, in BOTH themes. --ring was #333333 = 1.66:1 on --background.
+{
+  const css = strip(read(join(tokensDir, 'colors.css')))
+  const block = (re) => { const m = css.match(re); const o = {}; if (m) for (const [, n, v] of m[1].matchAll(/--([A-Za-z0-9-]+)\s*:\s*([^;]+);/g)) o[n] = v.trim(); return o }
+  const dark = block(/:root\s*\{([\s\S]*?)\n\}/)
+  const themes = { dark, light: { ...dark, ...block(/\.light\s*\{([\s\S]*?)\n\}/) } }
+
+  const deref = (v, s, d = 0) => { const m = d < 10 && v && String(v).match(/^var\(\s*--([A-Za-z0-9-]+)\s*\)$/); return m ? deref(s[m[1]], s, d + 1) : v }
+  const rgb = (v) => {
+    if (!v) return null
+    let m = String(v).trim().match(/^#([0-9a-f]{6})$/i)
+    if (m) { const n = parseInt(m[1], 16); return [n >> 16 & 255, n >> 8 & 255, n & 255, 1] }
+    m = String(v).trim().match(/^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)\s*(?:[/,]\s*([\d.]+))?\s*\)$/i)
+    return m ? [+m[1], +m[2], +m[3], m[4] === undefined ? 1 : +m[4]] : null
+  }
+  const over = (f, b) => [0, 1, 2].map((i) => f[i] * f[3] + b[i] * (1 - f[3]))
+  const lin = (c) => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4 }
+  const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b)
+  const ratio = (fg, bg, s) => {
+    const f = rgb(deref(fg, s)), b = rgb(deref(bg, s))
+    if (!f || !b) return null
+    const bo = b[3] < 1 ? over(b, [0, 0, 0, 1]) : b.slice(0, 3)
+    const fo = f[3] < 1 ? over(f, bo) : f.slice(0, 3)
+    const [A, B] = [lum(fo), lum(bo)].sort((x, y) => y - x)
+    return (A + 0.05) / (B + 0.05)
+  }
+
+  const CANVASES = ['background', 'card', 'popover', 'muted', 'secondary', 'surface-card', 'surface-overlay']
+  const GATED = { ring: 3, 'border-strong': 3 }
+  for (const [theme, scope] of Object.entries(themes)) {
+    for (const [tok, min] of Object.entries(GATED)) {
+      let worst = Infinity, where = ''
+      for (const c of CANVASES) {
+        const r = ratio(scope[tok], scope[c], scope)
+        if (r !== null && r < worst) { worst = r; where = `--${c}` }
+      }
+      if (!isFinite(worst)) { fail(`--${tok} (${theme}) could not be measured`); continue }
+      worst < min
+        ? fail(`--${tok} (${theme}) is ${worst.toFixed(2)}:1 on ${where} — needs ${min}:1`)
+        : pass(`--${tok} (${theme}) ${worst.toFixed(2)}:1 worst case (${where})`)
+    }
+  }
+}
+
+console.log(failures ? `\n${failures} check(s) failed` : '\nall token checks passed')
+process.exit(failures ? 1 : 0)

package/scripts/gen-tokens.mjs

@@ -0,0 +1,78 @@
+// gen-tokens.mjs — the ONE source→TS bridge for @hanzo/design.
+// The hand-authored token CSS under tokens/*.css is the source of truth; this
+// script parses every `--name: value;` custom property out of it and emits a
+// typed TypeScript module (src/tokens.gen.ts). CSS and code therefore can never
+// drift — you edit a token in ONE place (the CSS) and both the stylesheet and
+// the programmatic API update. Run via `npm run gen` (part of `build`).
+import { readFileSync, writeFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const tokensDir = join(root, 'tokens')
+
+// The token files, in the same order styles.css imports them. base.css is the
+// semantic-alias layer (references other vars) — parsed too, so `--background`
+// etc. are available programmatically.
+const FILES = ['colors', 'typography', 'spacing', 'radius', 'elevation', 'motion', 'z', 'fonts', 'base']
+
+// group name for each file (the export const); a couple read better renamed.
+const GROUP = { z: 'zIndex' }
+
+/** Strip /* *​/ comments, then pull every `--name: value;` pair (multi-per-line ok). */
+function parse(css) {
+  const noComments = css.replace(/\/\*[\s\S]*?\*\//g, '')
+  const out = []
+  const re = /--([A-Za-z0-9-]+)\s*:\s*([^;]+);/g
+  let m
+  while ((m = re.exec(noComments))) out.push([m[1].trim(), m[2].trim()])
+  return out
+}
+
+// A token may be authored more than once — the dark `:root{}` default and a
+// light `@media`/`[data-theme]` override carry the SAME name. Keep the FIRST
+// occurrence (dark, the default theme): the static map is the authored default;
+// live theme switching happens through the CSS cascade via cssVar()/var(--x).
+const groupMaps = {} // groupName -> Map(name->value), first-wins
+const flatMap = new Map() // '--name' -> value, first-wins
+for (const f of FILES) {
+  let css
+  try {
+    css = readFileSync(join(tokensDir, `${f}.css`), 'utf8')
+  } catch {
+    continue
+  }
+  const g = GROUP[f] ?? f
+  const gm = (groupMaps[g] ??= new Map())
+  for (const [n, v] of parse(css)) {
+    if (!gm.has(n)) gm.set(n, v)
+    if (!flatMap.has(`--${n}`)) flatMap.set(`--${n}`, v)
+  }
+}
+const groups = Object.fromEntries(Object.entries(groupMaps).map(([g, m]) => [g, [...m]]))
+const flat = [...flatMap]
+
+const esc = (s) => s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
+const objLit = (pairs) =>
+  '{\n' + pairs.map(([n, v]) => `  '${esc(n)}': '${esc(v)}',`).join('\n') + '\n} as const'
+
+let ts = `// AUTO-GENERATED by scripts/gen-tokens.mjs from tokens/*.css — DO NOT EDIT.
+// Edit the token in tokens/<group>.css and re-run \`npm run gen\`.
+/* eslint-disable */
+
+`
+
+// Per-group typed maps (keyed by the var name WITHOUT the leading '--').
+for (const [g, pairs] of Object.entries(groups)) {
+  ts += `/** ${g} tokens (from tokens/${Object.keys(GROUP).find((k) => GROUP[k] === g) ?? g}.css). Values are raw CSS. */\n`
+  ts += `export const ${g} = ${objLit(pairs)}\n\n`
+}
+
+// The complete flat map, keyed by the literal CSS custom-property name.
+ts += `/** Every token, keyed by its literal CSS custom-property name ('--background', …). */\n`
+ts += `export const cssVars = ${objLit(flat)}\n\n`
+
+ts += `export type CssVarName = keyof typeof cssVars\n`
+
+writeFileSync(join(root, 'src', 'tokens.gen.ts'), ts)
+console.log(`gen-tokens: wrote src/tokens.gen.ts — ${flat.length} tokens across ${Object.keys(groups).length} groups`)