@hanzo/design 0.3.0 → 0.3.1

package/README.md

@@ -6,10 +6,25 @@
 
 The single source of truth for how every Hanzo surface looks — tokens, components, brand assets, and the guidelines that hold them together.
 
-`@hanzoai/design`
+`@hanzo/design`
 
 </div>
 
+## If you are an agent
+
+Read [`skills/design-system/SKILL.md`](skills/design-system/SKILL.md). It is the
+**one** way an AI surface learns this design system — chat, hanzo.app and Claude
+Code all load the same file, so there is a single author and nothing to drift.
+It ends by running the gate below, which is what makes the rules enforceable
+rather than advisory:
+
+```sh
+npx hanzo-design-lint <paths…>
+```
+
+`prompts/` holds the longer material the skill points at. It is reference, not a
+second entry point.
+
 ## Use it
 
 One import pulls in the whole token layer — fonts, colour, type, spacing, radius,
@@ -49,8 +64,8 @@ Groups: `colors`, `typography`, `spacing`, `radius`, `elevation`, `motion`, `zIn
 Everything below is expressed as CSS custom properties, so code copies over 1:1 — the semantic names match `hanzo.ai`'s variables exactly.
 
 ```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";
 
 <Button pill>Try Hanzo</Button>
 ```

package/components/core/HanzoLogo.jsx

@@ -22,7 +22,7 @@ export function HanzoWordmark({ size = 22, label = 'Hanzo AI', variant = 'white'
   return (
     <span style={{ display: 'inline-flex', alignItems: 'center', gap: 8, ...style }}>
       <HanzoLogo size={size} variant={variant} />
-      <span style={{ fontSize: 15, fontWeight: 600, letterSpacing: 'var(--tracking-tight)', color: 'var(--text-primary)' }}>{label}</span>
+      <span style={{ fontSize: 'var(--text-sm)', fontWeight: 600, letterSpacing: 'var(--tracking-tight)', color: 'var(--text-primary)' }}>{label}</span>
     </span>
   )
 }

package/components/overlays/Dialog.jsx

@@ -11,7 +11,7 @@ export function Dialog({ open, onOpenChange, children }) {
   return (
     <div
       onClick={() => onOpenChange && onOpenChange(false)}
-      style={{position:'fixed',inset:0,zIndex:80,display:'flex',alignItems:'center',justifyContent:'center',padding:24,background:'rgb(0 0 0 / .8)',backdropFilter:'blur(4px)',animation:'hanzo-fade-up var(--duration-fast) var(--ease-out)'}}
+      style={{position:'fixed',inset:0,zIndex:'var(--z-modal)',display:'flex',alignItems:'center',justifyContent:'center',padding:24,background:'var(--surface-scrim)',backdropFilter:'blur(4px)',animation:'hanzo-fade-up var(--duration-fast) var(--ease-out)'}}
     >
       {children}
     </div>

package/components/overlays/DropdownMenu.jsx

@@ -18,7 +18,7 @@ export function DropdownMenu({ align = 'right', hover = false, trigger, style, c
     >
       <span onClick={() => setOpen((v) => !v)} style={{display:'inline-flex'}}>{trigger}</span>
       {open && (
-        <div style={{position:'absolute',top:'100%',[align]:0,paddingTop:12,zIndex:70,minWidth:208}}>
+        <div style={{position:'absolute',top:'100%',[align]:0,paddingTop:12,zIndex:'var(--z-dropdown)',minWidth:208}}>
           <div style={{display:'flex',flexDirection:'column',padding:8,background:'var(--surface-overlay)',border:'1px solid var(--border-hairline)',borderRadius:'var(--radius-xl)',boxShadow:'var(--shadow-floating)',backdropFilter:'blur(16px)',animation:'hanzo-fade-down var(--duration-fast) var(--ease-out)'}}>
             {children}
           </div>

package/components/overlays/Sheet.jsx

@@ -12,7 +12,7 @@ export function Sheet({ open, onOpenChange, side = 'right', width = 380, childre
     ? { left: 0, top: 0, bottom: 0, width, borderRight: '1px solid var(--border-hairline)' }
     : { right: 0, top: 0, bottom: 0, width, borderLeft: '1px solid var(--border-hairline)' }
   return (
-    <div onClick={() => onOpenChange && onOpenChange(false)} style={{position:'fixed',inset:0,zIndex:80,background:'rgb(0 0 0 / .7)'}}>
+    <div onClick={() => onOpenChange && onOpenChange(false)} style={{position:'fixed',inset:0,zIndex:'var(--z-modal)',background:'var(--surface-scrim)'}}>
       <div
         onClick={(e) => e.stopPropagation()}
         style={{position:'absolute',display:'flex',flexDirection:'column',background:'var(--popover)',boxShadow:'var(--shadow-floating)',animation:'hanzo-fade-up var(--duration-base) var(--ease-out)',...pos}}

package/components/overlays/Toaster.jsx

@@ -29,7 +29,7 @@ export function Toaster({ duration = 3500, position = 'bottom-right' }) {
   }, [duration])
   const anchor = position === 'top-right' ? { top: 24, right: 24 } : { bottom: 24, right: 24 }
   return (
-    <div style={{position:'fixed',zIndex:90,display:'flex',flexDirection:'column',gap:8,...anchor}}>
+    <div style={{position:'fixed',zIndex:'var(--z-toast)',display:'flex',flexDirection:'column',gap:8,...anchor}}>
       {items.map((i) => (
         <div key={i.id} style={{
           minWidth:260,maxWidth:380,padding:'12px 14px',display:'flex',alignItems:'flex-start',gap:10,

package/dist/tokens.gen.d.ts

@@ -53,6 +53,7 @@ export declare const colors: {
     readonly 'surface-card-quiet': "rgb(23 23 23 / .4)";
     readonly 'surface-overlay': "rgb(10 10 10 / .95)";
     readonly 'surface-header': "rgb(0 0 0 / .7)";
+    readonly 'surface-scrim': "rgb(0 0 0 / .8)";
     readonly 'border-hairline': "var(--neutral-800)";
     readonly 'border-card': "var(--white-10)";
     readonly 'border-strong': "var(--neutral-500)";
@@ -299,6 +300,7 @@ export declare const cssVars: {
     readonly '--surface-card-quiet': "rgb(23 23 23 / .4)";
     readonly '--surface-overlay': "rgb(10 10 10 / .95)";
     readonly '--surface-header': "rgb(0 0 0 / .7)";
+    readonly '--surface-scrim': "rgb(0 0 0 / .8)";
     readonly '--border-hairline': "var(--neutral-800)";
     readonly '--border-card': "var(--white-10)";
     readonly '--border-strong': "var(--neutral-500)";

package/dist/tokens.gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ET,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Db,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCV,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;CAiBZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6NV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}
+{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2ET,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Db,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCV,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;CAiBZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8NV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}

package/dist/tokens.gen.js

@@ -56,6 +56,7 @@ 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-500)',
@@ -302,6 +303,7 @@ 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-500)',

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hanzo/design",
-  "version": "0.3.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.",
+  "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",
@@ -25,13 +25,15 @@
     "./components/*": "./components/*",
     "./prompts/*": "./prompts/*",
     "./content/*": "./content/*",
-    "./assets/*": "./assets/*"
+    "./assets/*": "./assets/*",
+    "./skills/*": "./skills/*"
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "test": "node scripts/check-tokens.mjs",
+    "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"
+    "prepublishOnly": "npm run build",
+    "lint": "node scripts/lint.mjs"
   },
   "devDependencies": {
     "typescript": "^5.9.3"
@@ -43,6 +45,8 @@
     "tokens",
     "components",
     "prompts",
+    "skills",
+    "scripts",
     "content",
     "docs",
     "assets",
@@ -59,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,7 @@ 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.

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`)

package/scripts/lint.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// lint.mjs — the gate on CONSUMER code. `check-tokens.mjs` proves the token
+// layer is sound; this proves the code that USES it actually reaches it.
+//
+// Every rule here is a defect that shipped, silently, to a live Hanzo surface:
+// a var() nothing declares paints nothing, a raw hex ignores the theme, a bare
+// z-index wins a fight it should have lost, an ALL-CAPS label is a different
+// brand. None of them throw. So they fail here.
+//
+//   npx hanzo-design-lint <path...>        # default: cwd
+//
+// Exit 1 on any violation. That is the point.
+import { readFileSync, readdirSync, statSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { dirname, join, relative, extname, sep } from 'node:path'
+
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+// ── the vocabulary: every token the design system actually declares ──────
+const TOKENS = new Set()
+{
+  const dir = join(pkgRoot, 'tokens')
+  for (const f of readdirSync(dir).filter((f) => f.endsWith('.css')))
+    for (const [, n] of readFileSync(join(dir, f), 'utf8').matchAll(/--([A-Za-z0-9-]+)\s*:/g))
+      TOKENS.add(n)
+}
+
+// ── what we read ─────────────────────────────────────────────────────────
+const EXT = new Set(['.css', '.scss', '.jsx', '.tsx', '.js', '.ts', '.vue', '.svelte', '.html'])
+const SKIP = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'out', 'coverage', 'vendor', '__pycache__'])
+// Third-party marks keep their own hex by design (DESIGN.md §2.4); so do the
+// token files themselves, which are where raw values are SUPPOSED to live.
+const EXEMPT = /(^|\/)(tokens|assets|logos|providers|ui_kits|guidelines)(\/|$)|\.card\.html$/
+
+const walk = (p, out = []) => {
+  const st = statSync(p)
+  if (st.isFile()) { if (EXT.has(extname(p))) out.push(p); return out }
+  for (const e of readdirSync(p)) if (!SKIP.has(e) && !e.startsWith('.')) walk(join(p, e), out)
+  return out
+}
+
+const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
+const lineOf = (src, i) => src.slice(0, i).split('\n').length
+
+// Read one property's value out of a JSX style object, respecting quotes and
+// nested parens — `linear-gradient(a, var(--x))` is ONE value, not two.
+function styleValue(body, key) {
+  const at = body.search(new RegExp(`\\b${key}\\s*:`))
+  if (at < 0) return null
+  let i = body.indexOf(':', at) + 1, depth = 0, quote = null, out = ''
+  for (; i < body.length; i++) {
+    const c = body[i]
+    if (quote) { out += c; if (c === quote && body[i - 1] !== '\\') quote = null; continue }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; continue }
+    if (c === '(' || c === '[') depth++
+    if (c === ')' || c === ']') depth--
+    if (c === ',' && depth === 0) break
+    out += c
+  }
+  return out.trim()
+}
+
+const findings = []
+const flag = (file, line, rule, detail, fix) =>
+  findings.push({ file, line, rule, detail, fix })
+
+// ── the rules ────────────────────────────────────────────────────────────
+function lintFile(abs, root) {
+  const rel = relative(root, abs).split(sep).join('/')
+  if (EXEMPT.test('/' + rel)) return
+  const raw = readFileSync(abs, 'utf8')
+  const src = strip(raw)
+  const isStyle = /\.(css|scss)$/.test(rel)
+
+  // 1. var() must resolve — against the design tokens or a local declaration.
+  //    This is the menu that painted with undefined tokens.
+  const local = new Set([...src.matchAll(/--([A-Za-z0-9-]+)\s*:/g)].map((m) => m[1]))
+  for (const m of src.matchAll(/var\(\s*--([A-Za-z0-9-]+)\s*(\)|,)/g)) {
+    const [, name, close] = m
+    if (TOKENS.has(name) || local.has(name)) continue
+    if (close === ',') continue // an explicit fallback is a deliberate choice
+    flag(rel, lineOf(src, m.index), 'unresolved-token',
+      `var(--${name}) — nothing declares it`,
+      'use a token from @hanzo/design or declare it locally')
+  }
+
+  // 2. no raw colour in a surface. The theme cannot reach a literal.
+  for (const m of src.matchAll(/#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})\b|\b(?:rgba?|hsla?)\(/g)) {
+    const line = lineOf(src, m.index)
+    const text = src.split('\n')[line - 1] ?? ''
+    if (/currentColor|transparent|url\(|\.svg|<svg|xmlns|viewBox|stopColor|fill=/.test(text)) continue
+    flag(rel, line, 'raw-color', m[0].startsWith('#') ? m[0] : m[0] + '…)',
+      'use --foreground / --surface-card / the --white-* ladder')
+  }
+
+  // 3. no bare z-index. The ladder is --z-base … --z-notification.
+  for (const m of src.matchAll(/z-?[Ii]ndex\s*[:=]\s*['"{ ]*(-?\d+)/g))
+    flag(rel, lineOf(src, m.index), 'raw-z-index', `z-index: ${m[1]}`,
+      'use --z-dropdown / --z-modal / --z-toast …')
+  for (const m of src.matchAll(/\bz-\[(-?\d+)\]/g))
+    flag(rel, lineOf(src, m.index), 'raw-z-index', `z-[${m[1]}]`,
+      'use var(--z-…) via an arbitrary property, not a magic number')
+
+  // 4. no raw font-size. The scale is --type-* / --text-*.
+  for (const m of src.matchAll(/font-?[Ss]ize\s*[:=]\s*['"{ ]*(\d+(?:\.\d+)?)(px|pt)/g))
+    flag(rel, lineOf(src, m.index), 'raw-font-size', `${m[1]}${m[2]}`,
+      'use --type-body / --type-h2 / the --text-* scale')
+
+  // 5. sentence case. ALL CAPS is a different brand — eyebrows excepted, and
+  //    an eyebrow says so by using --type-eyebrow / the eyebrow class.
+  if (isStyle) {
+    for (const m of src.matchAll(/text-transform\s*:\s*uppercase/g)) {
+      const around = src.slice(Math.max(0, m.index - 400), m.index)
+      if (/eyebrow|--type-eyebrow|tracking-widest/i.test(around)) continue
+      flag(rel, lineOf(src, m.index), 'all-caps', 'text-transform: uppercase',
+        'sentence case; use --type-eyebrow if it is genuinely an eyebrow')
+    }
+  } else {
+    for (const m of src.matchAll(/>\s*([A-Z][A-Z0-9 &/'-]{5,40})\s*</g)) {
+      const t = m[1].trim()
+      if (!/[A-Z]{2}/.test(t) || /^[A-Z0-9 &/'-]+$/.test(t) === false) continue
+      if (t.split(/\s+/).every((w) => w.length <= 3)) continue // AI, API, GPU…
+      const line = lineOf(src, m.index)
+      const around = src.split('\n').slice(Math.max(0, line - 4), line).join(' ')
+      if (/eyebrow|uppercase|tracking-widest/i.test(around)) continue
+      flag(rel, line, 'all-caps', `"${t}"`, 'sentence case for labels and headings')
+    }
+  }
+
+  // 6. no inline style carrying design decisions. It outranks every token and
+  //    every theme, which is exactly why it keeps being reached for.
+  //    Only a LITERAL is a violation: `color:'#fff'`, `fontSize:13`. An
+  //    identifier (`background:FILL[variant]`) is indirection we cannot read,
+  //    and guessing there would train people to ignore the linter.
+  for (const m of src.matchAll(/style=\{\{([^}]*)\}\}/g)) {
+    const body = m[1]
+    const bad = ['color', 'background', 'backgroundColor', 'fontSize', 'boxShadow', 'borderColor']
+      .filter((k) => {
+        const val = styleValue(body, k)
+        if (val === null) return false
+        if (/var\(/.test(val)) return false
+        if (/^['"`]?(transparent|none|inherit|currentColor|unset|initial|auto)['"`]?$/i.test(val)) return false
+        return /^['"`]/.test(val) || /^-?\d/.test(val)
+      })
+    if (bad.length)
+      flag(rel, lineOf(src, m.index), 'inline-style', `style={{ ${bad.join(', ')} }}`,
+        'move to a class; if it must be inline, the value must be var(--token)')
+  }
+
+  // 7. one icon set.
+  for (const m of src.matchAll(/from\s+['"](@?[\w./-]*(?:react-icons|heroicons|font-awesome|@mui\/icons|feather-icons|phosphor)[\w./-]*)['"]/g))
+    flag(rel, lineOf(src, m.index), 'icon-set', m[1], 'lucide-react, one set, no other')
+
+  // 8. the import that makes all of the above resolvable.
+  for (const m of src.matchAll(/['"]@hanzoai\/design/g))
+    flag(rel, lineOf(src, m.index), 'wrong-package', '@hanzoai/design',
+      'the package is @hanzo/design — @hanzoai/design is a 404 and resolves nothing')
+}
+
+// ── run ──────────────────────────────────────────────────────────────────
+const targets = process.argv.slice(2).filter((a) => !a.startsWith('-'))
+const roots = targets.length ? targets : [process.cwd()]
+let scanned = 0
+for (const r of roots) for (const f of walk(r)) { scanned++; lintFile(f, r === f ? dirname(r) : r) }
+
+const RULES = ['unresolved-token', 'raw-color', 'raw-z-index', 'raw-font-size', 'all-caps', 'inline-style', 'icon-set', 'wrong-package']
+if (!findings.length) {
+  console.log(`hanzo-design-lint: ${scanned} files, clean`)
+  process.exit(0)
+}
+for (const rule of RULES) {
+  const hits = findings.filter((f) => f.rule === rule)
+  if (!hits.length) continue
+  console.log(`\n${rule}  (${hits.length})  — ${hits[0].fix}`)
+  for (const h of hits.slice(0, 20)) console.log(`  ${h.file}:${h.line}  ${h.detail}`)
+  if (hits.length > 20) console.log(`  … ${hits.length - 20} more`)
+}
+console.log(`\n${findings.length} violation(s) across ${scanned} files`)
+process.exit(1)

package/skills/design-system/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: design-system
+description: "Use whenever you generate, edit, or review a Hanzo user interface — a page, component, screen, email, or any code change touching colour, type, spacing, elevation, motion, or stacking order. Use it when PLANNING UI work too, so the plan names tokens rather than values. Teaches the Hanzo token layer (@hanzo/design, derived from @hanzo/brand plus @hanzo/logo) and runs the linter that proves generated code actually reaches it. Triggers — build a page, add a component, style, theme, dark mode, colour, hex, palette, font size, spacing, padding, z-index, modal, dropdown, toast, button, card, dialog, icon, make it look Hanzo, brand, design review."
+license: BSD-3-Clause
+---
+
+# The Hanzo design system
+
+One atom, and everything else follows from it:
+
+**Monochrome. True black. White type. Colour only as state, never as decoration.**
+
+## The derivation chain — never reach past it
+
+```
+@hanzo/brand   (brand.json — the identity: marks, palette source, motion intent)
+@hanzo/logo    (the mark itself, as SVG + React)
+        │  derive
+        ▼
+@hanzo/design  (tokens/*.css — 221 CSS custom properties, the ONLY vocabulary)
+        │  consume
+        ▼
+your component
+```
+
+A component reads `@hanzo/design`. It does **not** reach past it to `@hanzo/brand`,
+to `@hanzo/logo`'s raw SVG, or to a literal value. If a component needs something
+the token layer does not express, the fix is a **new token**, not a local
+constant — otherwise the next surface invents a second one and the two drift.
+(That is how one product ended up with 25 different z-index values.)
+
+The package is **`@hanzo/design`**. `@hanzoai/design` does not exist on npm; an
+import of it resolves to nothing, and an unresolved token layer paints nothing.
+
+## Start here
+
+```css
+@import "@hanzo/design/styles.css";   /* every token, as a CSS custom property */
+```
+
+Then reach for a **name**, never a value:
+
+| You want | Use | Never |
+|---|---|---|
+| a page / text | `--background`, `--foreground`, `--text-secondary` | `#000`, `#fff`, `rgb(…)` |
+| a card, a panel | `--surface-card`, `--border-hairline` | a hand-mixed grey |
+| rank / emphasis | the ladder `--white-05 … --white-80` | an off-ladder 12% or 37% |
+| a size | `--type-body`, `--type-h2`, `--text-sm` | `font-size: 13px` |
+| space | `--space-*`, `--gutter*`, `--container-max` | `padding: 13px` |
+| a layer | `--z-dropdown`, `--z-modal`, `--z-toast` | `z-index: 9999` |
+| a scrim | `--surface-scrim` | `rgba(0,0,0,.8)` |
+| an icon | `lucide-react` | react-icons, heroicons, MUI |
+
+The **only** coloured pixels permitted: `--state-error`, `--state-online`,
+`--state-success`, the macOS chrome dot trio, and third-party brand logos. A blue
+button or a purple gradient is not Hanzo — make it white on black.
+
+Sentence case for headings and buttons. ALL CAPS is only an eyebrow, and an
+eyebrow says so with `--type-eyebrow`.
+
+## Read before you write
+
+Load these from the installed package (`node_modules/@hanzo/design/`) or the repo:
+
+| File | When |
+|---|---|
+| `prompts/system.md` | Always. The whole language, one screen. Paste as system prompt for a sub-agent. |
+| `prompts/rules.md` | The do/don't table. Walk it before you return code. |
+| `components/**/*.prompt.md` | Per component, when you place one. |
+| `guidelines/DESIGN.md` | The reasoning, when a rule seems to be in your way. |
+| `tokens/*.css` | The authoritative list. Grep it rather than guessing a name. |
+
+## Finish by proving it — this step is not optional
+
+Generated code that violates the token layer must be **caught, not shipped**.
+Nothing here fails loudly on its own: an undefined `var()` paints nothing, a raw
+hex silently ignores the theme, a class with no rule paints nothing. So run the
+gate on every file you touched:
+
+```sh
+npx hanzo-design-lint <paths…>        # exit 0 = clean, exit 1 = violations
+```
+
+It checks eight things, each of which has shipped to production at least once:
+
+1. `unresolved-token` — a `var(--x)` nothing declares
+2. `raw-color` — a hex / `rgb()` / `hsl()` literal in a surface
+3. `raw-z-index` — a magic number instead of the ladder
+4. `raw-font-size` — `px`/`pt` instead of the scale
+5. `all-caps` — an uppercase label that is not an eyebrow
+6. `inline-style` — a literal colour/size in `style={{…}}` (a `var()` is fine)
+7. `icon-set` — an icon library that is not lucide
+8. `wrong-package` — `@hanzoai/design`, which resolves to nothing
+
+Fix every finding, then re-run until clean. **Do not** silence a rule, and do not
+report the work as done on a red gate. If a rule is genuinely wrong for a case,
+say so explicitly in your summary rather than working around it.
+
+## The one test
+
+Monochrome, true black, white type, colour only as state. If the screenshot would
+look at home on hanzo.ai, it passes. If it looks like a generic SaaS template, it
+fails — and the fix is your work, never the atom.

package/src/tokens.gen.ts

@@ -57,6 +57,7 @@ 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-500)',
@@ -314,6 +315,7 @@ 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-500)',

package/tokens/colors.css

@@ -70,6 +70,7 @@
   --surface-card-quiet:rgb(23 23 23 / .4);   /* bg-neutral-900/40 — story cards */
   --surface-overlay:rgb(10 10 10 / .95);     /* dropdown / popover panels       */
   --surface-header:rgb(0 0 0 / .7);          /* fixed nav, with backdrop blur   */
+  --surface-scrim:rgb(0 0 0 / .8);           /* the dialog / sheet backdrop     */
   /* Boundaries come in two kinds and they are NOT interchangeable.
      DECORATIVE (--border, --border-hairline, --border-card): separates content;
      WCAG imposes no ratio. Keep them quiet.
@@ -138,6 +139,7 @@
   --surface-card-quiet:#fafafa;
   --surface-overlay:rgb(255 255 255 / .95);
   --surface-header:rgb(255 255 255 / .8);
+  --surface-scrim:rgb(0 0 0 / .5);
   --border-hairline:var(--neutral-200);
   --border-card:rgb(0 0 0 / .1);
   --border-strong:var(--neutral-500);   /* was --neutral-300 = 1.48:1 on white */