@hanzo/design 0.2.0 → 0.3.1

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/index.ts

@@ -12,17 +12,30 @@
 export * from './tokens.gen.js'
 import { cssVars, type CssVarName } from './tokens.gen.js'
 
+/** A token name with the leading `--` omitted: `'background'` for `'--background'`. */
+export type TokenName = CssVarName extends `--${infer N}` ? N : never
+
 /**
- * A `var(--name[, fallback])` reference to a token — the ONE way code should
- * reach a token so it resolves through the live CSS cascade (honoring the
- * viewer's light/dark theme) rather than baking a fixed value.
+ * A `var(--name, <authored literal>)` reference to a token — the ONE way code
+ * should reach a token, so it resolves through the live CSS cascade (honoring
+ * the viewer's light/dark theme and any brand fork) rather than baking a value.
+ *
+ *   background: cssVar('--background')      // → "var(--background, #000000)"
+ *   color:      cssVar('foreground', '#fff')// → "var(--foreground, #fff)"
  *
- *   background: cssVar('--background')      // → "var(--background)"
- *   color:      cssVar('--foreground', '#fff')
+ * The name is checked AGAINST THE STYLESHEET at compile time. That check used to
+ * be opted out of with `| (string & {})`, which is how `cssVar('surface-1')`
+ * shipped: the token did not exist, `var(--surface-1)` resolved to nothing, and
+ * a menu painted transparent with no error anywhere. An undefined custom
+ * property fails SILENTLY, so the type is the only place it can be caught.
+ *
+ * When no explicit fallback is given the token's own authored literal is used,
+ * so the reference still paints on a host that has not loaded the CSS layer.
  */
-export function cssVar(name: CssVarName | (string & {}), fallback?: string): string {
-  const n = name.startsWith('--') ? name : `--${name}`
-  return fallback ? `var(${n}, ${fallback})` : `var(${n})`
+export function cssVar(name: CssVarName | TokenName, fallback?: string): string {
+  const n = (name.startsWith('--') ? name : `--${name}`) as CssVarName
+  const lit = fallback ?? (cssVars as Record<string, string>)[n]
+  return lit ? `var(${n}, ${lit})` : `var(${n})`
 }
 
 /** The raw authored value of a token (the literal from the CSS), or `undefined`. */
@@ -35,8 +48,12 @@ export function tokenValue(name: CssVarName): string | undefined {
  * cannot use a bundler CSS import (e.g. a runtime-mounted island). Prefer the
  * static `import '@hanzo/design/styles.css'` where a bundler is available.
  * No-op outside the browser.
+ *
+ * `href` is REQUIRED: this used to default to esm.sh, which silently made a
+ * third-party CDN the origin of the entire token layer for anyone who called it
+ * bare. Pass a URL you serve.
  */
-export function injectDesignCss(href = 'https://esm.sh/@hanzo/design/styles.css'): void {
+export function injectDesignCss(href: string): void {
   if (typeof document === 'undefined') return
   if (document.querySelector('link[data-hanzo-design]')) return
   const l = document.createElement('link')

package/src/tokens.gen.ts

@@ -45,7 +45,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',
@@ -57,9 +57,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)',
@@ -99,6 +104,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',
@@ -181,6 +203,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%)',
@@ -214,6 +242,8 @@ export const zIndex = {
   'z-modal': '600',
   'z-popover': '700',
   'z-toast': '800',
+  'z-tooltip': 'var(--z-popover)',
+  'z-notification': 'var(--z-toast)',
 } as const
 
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
@@ -273,7 +303,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',
@@ -285,9 +315,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)',
@@ -323,6 +358,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',
@@ -393,6 +445,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%)',
@@ -418,6 +476,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/styles.css

@@ -1,5 +1,8 @@
 /* Hanzo Design System — global entry point. Import THIS one file.
-   Source of truth: hanzo-apps/hanzo.ai (app/globals.css, tailwind.config.ts, DESIGN.md). */
+   Every token group is served here; nothing is authored but left unimported.
+   (`tokens/z.css` went missing from this list once and the whole ladder stopped
+   resolving while still type-checking — see scripts/check-tokens.mjs, which now
+   fails the build if any tokens/*.css is not imported below.) */
 @import url("tokens/fonts.css");
 @import url("tokens/colors.css");
 @import url("tokens/typography.css");

package/tokens/base.css

@@ -2,10 +2,14 @@
    a utility framework. Components carry their own styles inline. */
 *{box-sizing:border-box;border-color:var(--border)}
 html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
-body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
-h1,h2,h3,h4{margin:0;font-family:var(--font-display);letter-spacing:var(--tracking-tight);color:var(--text-primary)}
+/* Each font-family carries the stack as a literal fallback. --font-sans lives in
+   tokens/fonts.css, which a surface may legitimately import separately; without
+   the fallback an unresolved var() makes font-family invalid and the UA drops to
+   its SERIF default — the whole console silently rendered in Times. */
+body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
+h1,h2,h3,h4{margin:0;font-family:var(--font-display,var(--font-sans,ui-sans-serif,system-ui,sans-serif));letter-spacing:var(--tracking-tight);color:var(--text-primary)}
 p{margin:0;text-wrap:pretty}
-code,pre,kbd{font-family:var(--font-mono)}
+code,pre,kbd{font-family:var(--font-mono,ui-monospace,SFMono-Regular,monospace)}
 a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px;transition:color var(--duration-fast) var(--ease-out)}
 a:hover{color:var(--text-primary);text-decoration:underline}
 :focus-visible{outline:2px solid var(--ring);outline-offset:2px}

package/tokens/colors.css

@@ -51,7 +51,12 @@
   --destructive-foreground:#f5f5f5;
   --border:#1f1f1f;
   --input:#1f1f1f;
-  --ring:#333333;
+  /* A focus indicator is a NON-TEXT CONTRAST target: WCAG 2.4.11/1.4.11 require
+     3:1 against every surface it can land on. --neutral-500 is the only rung on
+     this ladder that clears 3:1 on all of them — #000000, #0a0a0a, #101010,
+     #1a1a1a, AND the light theme's #ffffff/#f5f5f5 — so one value serves both
+     themes. (Was #333333 = 1.66:1 on --background: not a focus indicator.) */
+  --ring:var(--neutral-500);
   --brand:#e4e4e7;
   --brand-foreground:#09090b;
   --brand-muted:#a3a3a3;
@@ -65,9 +70,25 @@
   --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.
+     PERCEIVABLE (--border-strong): identifies a CONTROL — an input edge, a
+     switch, a checkbox — and must clear 3:1 (WCAG 1.4.11) on every surface.
+     Reach for --border-strong whenever the boundary IS the affordance. */
   --border-hairline:var(--neutral-800);
   --border-card:var(--white-10);
-  --border-strong:var(--neutral-700);
+  --border-strong:var(--neutral-500);   /* 3.59:1 worst case — see --ring */
+
+  /* ——— the numeric surface ladder ——— */
+  /* Aliases onto the semantic canvases above, so a brand fork that retunes
+     --card/--muted/--secondary retunes the ladder with it and the light theme
+     inverts for free. Ascending lift: 0 is the page, 3 is a hovered control. */
+  --surface-0:var(--background);
+  --surface-1:var(--card);
+  --surface-2:var(--muted);
+  --surface-3:var(--secondary);
 
   /* ——— text ranks ——— */
   --text-primary:var(--pure-white);
@@ -107,7 +128,10 @@
   --destructive-foreground:#ffffff;
   --border:#e5e5e5;
   --input:#e5e5e5;
-  --ring:#d4d4d4;
+  /* Same rung as dark: #d4d4d4 measured 1.48:1 on white and could not carry a
+     focus indicator either. --neutral-500 is 4.74:1 on #ffffff / 4.38:1 on
+     #f5f5f5, so ONE value is conformant in both themes. */
+  --ring:var(--neutral-500);
   --black:#0a0a0a;
   --white:#ffffff;
   --surface-card:#f5f5f5;
@@ -115,9 +139,13 @@
   --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-300);
+  --border-strong:var(--neutral-500);   /* was --neutral-300 = 1.48:1 on white */
+  /* The white-opacity ladder does NOT invert, so --white-40 is white-on-white
+     here (1.00:1). Anything that needs a visible edge in BOTH themes must use
+     --border-strong, never a --white-* rung. */
   --text-primary:var(--neutral-950);
   --text-secondary:rgb(10 10 10 / .8);
   --text-tertiary:rgb(10 10 10 / .6);

package/tokens/elevation.css

@@ -6,6 +6,18 @@
   --shadow-floating:0 25px 50px -12px rgb(0 0 0 / .25);  /* shadow-2xl: composer, dropdowns, mega panel */
   --shadow-inset-hairline:inset 0 0 0 1px var(--white-10);
   --ring-focus:0 0 0 2px var(--ring);
+
+  /* The t-shirt ramp. Named by size rather than by role, because that is how
+     every component library already asks for a shadow (and how @hanzo/brand
+     spells it). Alphas are heavier than Tailwind's defaults: on a near-black
+     ground a 10% black drop is invisible, so each rung is tuned to read on
+     --background. --shadow-2xl and --shadow-floating are the same rung. */
+  --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);
   /* Ambient hero glow — a single white radial, blurred 120px, low opacity. */
   --glow-hero:radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%); /* @kind color */
   --glow-hero-blur:120px;

package/tokens/fonts.css

@@ -1,7 +1,34 @@
 /* Geist Sans + Geist Mono — the only two faces on Hanzo surfaces.
-   hanzo.ai loads them via next/font/google (Geist, Geist_Mono); here they come
-   from the same Google Fonts source, so the rendered face is identical. */
-@import url("https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Geist+Mono:wght@100..900&display=swap");
+   SELF-HOSTED. The faces ship inside this package (assets/fonts/*.woff2, two
+   variable files, 141 KB total, SIL OFL-1.1 — see assets/fonts/LICENSE-Geist.txt).
+
+   Why self-hosted rather than @import from fonts.googleapis.com:
+   - A sign-in page must not make a third-party request. hanzoai/id refused to
+     import this file for exactly that reason, which split the token layer: id
+     took the colours and not the typeface. Self-hosting removes the reason, so
+     every surface can import styles.css unchanged.
+   - The @import was a render-blocking request to a host we do not control, on
+     the critical path of every surface, and it broke offline/air-gapped dev.
+   - One variable file per family replaces nine static weights, and it is fewer
+     bytes than the CSS-then-woff2 round trip Google served.
+
+   The url()s are relative to THIS file, so they resolve wherever the package is
+   mounted — node_modules, a CDN, a copied dist — with no configuration. */
+
+@font-face{
+  font-family:"Geist";
+  src:url("../assets/fonts/Geist-Variable.woff2") format("woff2");
+  font-weight:100 900;
+  font-style:normal;
+  font-display:swap;
+}
+@font-face{
+  font-family:"Geist Mono";
+  src:url("../assets/fonts/GeistMono-Variable.woff2") format("woff2");
+  font-weight:100 900;
+  font-style:normal;
+  font-display:swap;
+}
 
 :root{
   --font-sans:"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif;