@hanzo/design 0.5.0 → 0.5.2

package/dist/tokens.gen.js

@@ -94,31 +94,32 @@ export const colors = {
 };
 /** typography tokens (from tokens/typography.css). Values are raw CSS. */
 export const typography = {
-    'text-xs': '0.6875rem',
-    'leading-xs': '1rem',
-    'text-sm': '0.8125rem',
-    'leading-sm': '1.15rem',
-    'text-base': '0.875rem',
-    'leading-base': '1.35rem',
-    'text-lg': '0.9375rem',
-    'leading-lg': '1.4rem',
-    'text-xl': '1.0625rem',
-    'leading-xl': '1.55rem',
-    'text-2xl': '1.3125rem',
-    'leading-2xl': '1.7rem',
-    'text-3xl': '1.625rem',
-    'leading-3xl': '1.95rem',
-    'text-4xl': '2rem',
-    'leading-4xl': '2.25rem',
-    'text-5xl': '2.5rem',
+    'type-scale': '1',
+    'text-xs': 'calc(0.6875rem * var(--type-scale, 1))',
+    'leading-xs': 'calc(1rem * var(--type-scale, 1))',
+    'text-sm': 'calc(0.8125rem * var(--type-scale, 1))',
+    'leading-sm': 'calc(1.15rem * var(--type-scale, 1))',
+    'text-base': 'calc(0.875rem * var(--type-scale, 1))',
+    'leading-base': 'calc(1.35rem * var(--type-scale, 1))',
+    'text-lg': 'calc(0.9375rem * var(--type-scale, 1))',
+    'leading-lg': 'calc(1.4rem * var(--type-scale, 1))',
+    'text-xl': 'calc(1.0625rem * var(--type-scale, 1))',
+    'leading-xl': 'calc(1.55rem * var(--type-scale, 1))',
+    'text-2xl': 'calc(1.3125rem * var(--type-scale, 1))',
+    'leading-2xl': 'calc(1.7rem * var(--type-scale, 1))',
+    'text-3xl': 'calc(1.625rem * var(--type-scale, 1))',
+    'leading-3xl': 'calc(1.95rem * var(--type-scale, 1))',
+    'text-4xl': 'calc(2rem * var(--type-scale, 1))',
+    'leading-4xl': 'calc(2.25rem * var(--type-scale, 1))',
+    'text-5xl': 'calc(2.5rem * var(--type-scale, 1))',
     'leading-5xl': '1.05',
-    'text-6xl': '3.25rem',
+    'text-6xl': 'calc(3.25rem * var(--type-scale, 1))',
     'leading-6xl': '1',
-    'text-7xl': '4rem',
+    'text-7xl': 'calc(4rem * var(--type-scale, 1))',
     'leading-7xl': '1',
-    'text-8xl': '5.25rem',
+    'text-8xl': 'calc(5.25rem * var(--type-scale, 1))',
     'leading-8xl': '1',
-    'text-9xl': '7rem',
+    'text-9xl': 'calc(7rem * var(--type-scale, 1))',
     'leading-9xl': '1',
     'font-size-xs': 'var(--text-xs)',
     'font-size-sm': 'var(--text-sm)',
@@ -159,21 +160,22 @@ export const typography = {
 };
 /** spacing tokens (from tokens/spacing.css). Values are raw CSS. */
 export const spacing = {
+    'density': '1',
     'space-0': '0',
-    'space-1': '0.25rem',
-    'space-2': '0.5rem',
-    'space-3': '0.75rem',
-    'space-4': '1rem',
-    'space-5': '1.25rem',
-    'space-6': '1.5rem',
-    'space-8': '2rem',
-    'space-10': '2.5rem',
-    'space-12': '3rem',
-    'space-14': '3.5rem',
-    'space-16': '4rem',
-    'space-20': '5rem',
-    'space-24': '6rem',
-    'space-32': '8rem',
+    'space-1': 'calc(0.25rem * var(--density, 1))',
+    'space-2': 'calc(0.5rem * var(--density, 1))',
+    'space-3': 'calc(0.75rem * var(--density, 1))',
+    'space-4': 'calc(1rem * var(--density, 1))',
+    'space-5': 'calc(1.25rem * var(--density, 1))',
+    'space-6': 'calc(1.5rem * var(--density, 1))',
+    'space-8': 'calc(2rem * var(--density, 1))',
+    'space-10': 'calc(2.5rem * var(--density, 1))',
+    'space-12': 'calc(3rem * var(--density, 1))',
+    'space-14': 'calc(3.5rem * var(--density, 1))',
+    'space-16': 'calc(4rem * var(--density, 1))',
+    'space-20': 'calc(5rem * var(--density, 1))',
+    'space-24': 'calc(6rem * var(--density, 1))',
+    'space-32': 'calc(8rem * var(--density, 1))',
     'golden-1': '0.25rem',
     'golden-2': '0.405rem',
     'golden-3': '0.654rem',
@@ -240,6 +242,13 @@ export const elevation = {
     '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)',
+    'sheet-0': 'var(--surface-page)',
+    'sheet-1': 'var(--surface-card)',
+    'sheet-2': 'var(--surface-card-emphasis)',
+    'shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+    'shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+    'fold': '12px',
+    'fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
     '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%)',
@@ -377,31 +386,32 @@ export const cssVars = {
     '--chrome-dot-red': 'rgb(239 68 68 / .6)',
     '--chrome-dot-yellow': 'rgb(234 179 8 / .6)',
     '--chrome-dot-green': 'rgb(34 197 94 / .6)',
-    '--text-xs': '0.6875rem',
-    '--leading-xs': '1rem',
-    '--text-sm': '0.8125rem',
-    '--leading-sm': '1.15rem',
-    '--text-base': '0.875rem',
-    '--leading-base': '1.35rem',
-    '--text-lg': '0.9375rem',
-    '--leading-lg': '1.4rem',
-    '--text-xl': '1.0625rem',
-    '--leading-xl': '1.55rem',
-    '--text-2xl': '1.3125rem',
-    '--leading-2xl': '1.7rem',
-    '--text-3xl': '1.625rem',
-    '--leading-3xl': '1.95rem',
-    '--text-4xl': '2rem',
-    '--leading-4xl': '2.25rem',
-    '--text-5xl': '2.5rem',
+    '--type-scale': '1',
+    '--text-xs': 'calc(0.6875rem * var(--type-scale, 1))',
+    '--leading-xs': 'calc(1rem * var(--type-scale, 1))',
+    '--text-sm': 'calc(0.8125rem * var(--type-scale, 1))',
+    '--leading-sm': 'calc(1.15rem * var(--type-scale, 1))',
+    '--text-base': 'calc(0.875rem * var(--type-scale, 1))',
+    '--leading-base': 'calc(1.35rem * var(--type-scale, 1))',
+    '--text-lg': 'calc(0.9375rem * var(--type-scale, 1))',
+    '--leading-lg': 'calc(1.4rem * var(--type-scale, 1))',
+    '--text-xl': 'calc(1.0625rem * var(--type-scale, 1))',
+    '--leading-xl': 'calc(1.55rem * var(--type-scale, 1))',
+    '--text-2xl': 'calc(1.3125rem * var(--type-scale, 1))',
+    '--leading-2xl': 'calc(1.7rem * var(--type-scale, 1))',
+    '--text-3xl': 'calc(1.625rem * var(--type-scale, 1))',
+    '--leading-3xl': 'calc(1.95rem * var(--type-scale, 1))',
+    '--text-4xl': 'calc(2rem * var(--type-scale, 1))',
+    '--leading-4xl': 'calc(2.25rem * var(--type-scale, 1))',
+    '--text-5xl': 'calc(2.5rem * var(--type-scale, 1))',
     '--leading-5xl': '1.05',
-    '--text-6xl': '3.25rem',
+    '--text-6xl': 'calc(3.25rem * var(--type-scale, 1))',
     '--leading-6xl': '1',
-    '--text-7xl': '4rem',
+    '--text-7xl': 'calc(4rem * var(--type-scale, 1))',
     '--leading-7xl': '1',
-    '--text-8xl': '5.25rem',
+    '--text-8xl': 'calc(5.25rem * var(--type-scale, 1))',
     '--leading-8xl': '1',
-    '--text-9xl': '7rem',
+    '--text-9xl': 'calc(7rem * var(--type-scale, 1))',
     '--leading-9xl': '1',
     '--font-size-xs': 'var(--text-xs)',
     '--font-size-sm': 'var(--text-sm)',
@@ -439,21 +449,22 @@ export const cssVars = {
     '--type-caption': '400 var(--text-xs)/var(--leading-xs) var(--font-sans)',
     '--type-code': '400 var(--text-sm)/var(--leading-relaxed) var(--font-mono)',
     '--type-eyebrow': '600 0.625rem/1 var(--font-sans)',
+    '--density': '1',
     '--space-0': '0',
-    '--space-1': '0.25rem',
-    '--space-2': '0.5rem',
-    '--space-3': '0.75rem',
-    '--space-4': '1rem',
-    '--space-5': '1.25rem',
-    '--space-6': '1.5rem',
-    '--space-8': '2rem',
-    '--space-10': '2.5rem',
-    '--space-12': '3rem',
-    '--space-14': '3.5rem',
-    '--space-16': '4rem',
-    '--space-20': '5rem',
-    '--space-24': '6rem',
-    '--space-32': '8rem',
+    '--space-1': 'calc(0.25rem * var(--density, 1))',
+    '--space-2': 'calc(0.5rem * var(--density, 1))',
+    '--space-3': 'calc(0.75rem * var(--density, 1))',
+    '--space-4': 'calc(1rem * var(--density, 1))',
+    '--space-5': 'calc(1.25rem * var(--density, 1))',
+    '--space-6': 'calc(1.5rem * var(--density, 1))',
+    '--space-8': 'calc(2rem * var(--density, 1))',
+    '--space-10': 'calc(2.5rem * var(--density, 1))',
+    '--space-12': 'calc(3rem * var(--density, 1))',
+    '--space-14': 'calc(3.5rem * var(--density, 1))',
+    '--space-16': 'calc(4rem * var(--density, 1))',
+    '--space-20': 'calc(5rem * var(--density, 1))',
+    '--space-24': 'calc(6rem * var(--density, 1))',
+    '--space-32': 'calc(8rem * var(--density, 1))',
     '--golden-1': '0.25rem',
     '--golden-2': '0.405rem',
     '--golden-3': '0.654rem',
@@ -511,6 +522,13 @@ export const cssVars = {
     '--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)',
+    '--sheet-0': 'var(--surface-page)',
+    '--sheet-1': 'var(--surface-card)',
+    '--sheet-2': 'var(--surface-card-emphasis)',
+    '--shadow-sheet-1': 'var(--edge-highlight),var(--shadow-md)',
+    '--shadow-sheet-2': 'var(--edge-highlight),var(--shadow-lg)',
+    '--fold': '12px',
+    '--fold-face': 'linear-gradient(315deg,var(--glass-strong) 0,var(--glass-strong) calc(var(--fold) - 1px),var(--border-strong) calc(var(--fold) - 1px),var(--border-strong) var(--fold),transparent var(--fold))',
     '--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%)',

package/guidelines/brand-paper.card.html

@@ -0,0 +1,22 @@
+<!-- @dsCard group="Brand" viewport="700x240" name="Paper" subtitle="Three sheets, one light, and a fold that means this opens" -->
+<!doctype html><html class="dark"><head><meta charset="utf-8"><title>Paper</title><link rel="stylesheet" href="../styles.css">
+<style>body{margin:0;padding:20px;background:var(--sheet-0);font-family:var(--font-sans);color:var(--foreground)}
+.n{font-size:10px;font-weight:600;letter-spacing:.06em;color:var(--neutral-300);font-family:var(--font-mono)}
+.v{font-size:9px;color:var(--neutral-600);font-family:var(--font-mono);margin-top:3px}
+.sheet{padding:14px;border-radius:var(--radius-lg);font-size:12px;color:var(--neutral-400)}
+.s1{background:var(--sheet-1);box-shadow:var(--shadow-sheet-1)}
+.s2{background:var(--sheet-2);box-shadow:var(--shadow-sheet-2)}
+.fold{background-image:var(--fold-face);border-bottom-right-radius:0}
+</style></head><body>
+<div style="display:flex;gap:16px;align-items:stretch">
+  <div class="sheet" style="flex:1">the workspace — no lift, no box<div class="n" style="margin-top:10px">--sheet-0</div><div class="v">the ground</div></div>
+  <div class="sheet s1" style="flex:1">an active tool<div class="n" style="margin-top:10px">--sheet-1</div><div class="v">+ --shadow-sheet-1</div></div>
+  <div class="sheet s2" style="flex:1">what opened<div class="n" style="margin-top:10px">--sheet-2</div><div class="v">+ --shadow-sheet-2</div></div>
+  <div class="sheet s1 fold" style="flex:1">this one expands<div class="n" style="margin-top:10px">--fold-face</div><div class="v">the only mark</div></div>
+</div>
+<div style="margin-top:18px;display:flex;gap:16px">
+  <div class="sheet s1" style="flex:1">a sheet on a sheet lands a step lighter
+    <div class="sheet s1" style="margin-top:10px">nested<div class="sheet s1" style="margin-top:10px">nested again</div></div>
+  </div>
+</div>
+</body></html>

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@hanzo/design",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "packageManager": "pnpm@11.17.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": "BSD-3-Clause",
+  "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/hanzoai/design.git"
@@ -19,8 +19,10 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
+    "./package.json": "./package.json",
     "./styles.css": "./styles.css",
     "./tokens/*": "./tokens/*",
     "./components/*": "./components/*",
@@ -32,8 +34,8 @@
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "test": "node scripts/check-tokens.mjs && node scripts/lint.mjs .",
-    "build": "pnpm gen && pnpm test && tsc -p tsconfig.json",
+    "test": "node scripts/check-tokens.mjs && node scripts/check-preference.mjs && node scripts/lint.mjs .",
+    "build": "pnpm gen && pnpm test && tsc -p tsconfig.json && node scripts/check-dist.mjs",
     "prepublishOnly": "pnpm build",
     "lint": "node scripts/lint.mjs"
   },
@@ -70,4 +72,4 @@
   "bin": {
     "hanzo-design-lint": "./scripts/lint.mjs"
   }
-}
+}

package/prompts/rules.md

@@ -33,7 +33,9 @@ token or pattern that makes the "do" trivial.
 |----|-------|
 | One primary (white) action per view; everything else outline or ghost. | Two competing primary buttons. |
 | Plain `<a>` / `<Link>` with className, or the shipped `<Button>`. | `<Button asChild>` — it breaks the build under React 18 strict children. |
-| Elevation as a hairline border + `--shadow-floating` only when floating. | Drop shadows on flat, in-flow cards. |
+| Separate two surfaces by RAISING one — `--sheet-1` + `--shadow-sheet-1`. | Outlining both, then raising one anyway. |
+| A level because the surface means something: workspace, tool, opened. | A drop shadow for looks, or a second lamp — every shadow drops straight down. |
+| A fold (`--fold-face`) only where the item expands. | A fold as ornament. |
 
 ## Motion
 

package/prompts/system.md

@@ -73,8 +73,14 @@ That is not Hanzo. Make it white-on-black and let the content carry it.
 
 - `--radius-sm` on buttons/inputs, `--radius-lg` on cards, `--radius-full` on
   pills and avatars. `--radius-composer` (28px) only for the chat composer.
-- Hanzo barely uses shadow. On black, elevation is a hairline border plus, for
-  truly floating surfaces, `--shadow-floating`. Heroes get one ambient
+- Depth is the hierarchy. Three levels of paper: `--sheet-0` is the workspace,
+  `--sheet-1` an active tool, `--sheet-2` what opened — each with the matching
+  `--shadow-sheet-*`, which carries the top edge-light and the drop together.
+  Raise a surface before you outline it, and never do both.
+- One light, above: every shadow in the system is `0 <y> …`. A sideways offset
+  is a second lamp, and the screen stops reading as one space.
+- `--fold-face` marks an item that expands, and nothing else. `--shadow-floating`
+  is for what actually floats — menus, dialogs. Heroes get one ambient
   `--glow-hero` radial, nothing more.
 
 ## Motion

package/scripts/check-dist.mjs

@@ -0,0 +1,81 @@
+/**
+ * Import the BUILT package the way a consumer does.
+ *
+ * Everything else in this repo checks the sources: the token files, the
+ * generator's output, the preference contract. All of it passed while
+ * `dist/index.js` was unimportable — 0.4.10 and 0.4.11 both shipped a barrel
+ * that re-exported `'./preference'` with no extension, which TypeScript emits
+ * verbatim and Node ESM refuses to resolve. `pnpm build` was green, `pnpm test`
+ * was green, and `import '@hanzo/design'` threw ERR_MODULE_NOT_FOUND for every
+ * consumer.
+ *
+ * A test that reads source cannot see that. This one loads the artifact.
+ */
+import { readFileSync, existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { dirname, join } from 'node:path'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const root = join(here, '..')
+
+let failed = 0
+const check = async (name, fn) => {
+  try {
+    await fn()
+    console.log(`  ok   ${name}`)
+  } catch (e) {
+    failed++
+    console.error(`  FAIL ${name}\n       ${e.message}`)
+  }
+}
+
+console.log('dist:')
+
+const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+
+await check('every export the package advertises actually exists on disk', () => {
+  const missing = []
+  for (const [name, entry] of Object.entries(pkg.exports ?? {})) {
+    for (const target of typeof entry === 'string' ? [entry] : Object.values(entry)) {
+      if (typeof target !== 'string' || target.includes('*')) continue
+      if (!existsSync(join(root, target))) missing.push(`${name} -> ${target}`)
+    }
+  }
+  if (missing.length) throw new Error(`exports pointing at nothing:\n         ${missing.join('\n         ')}`)
+})
+
+await check('the barrel IMPORTS — the check that 0.4.10 and 0.4.11 needed', async () => {
+  const entry = join(root, 'dist/index.js')
+  if (!existsSync(entry)) throw new Error('dist/index.js is missing — run the build first')
+  const mod = await import(pathToFileURL(entry).href)
+  // The preference API is the part that was unreachable; naming it here means a
+  // future re-export losing its extension fails by name rather than by silence.
+  for (const name of ['vars', 'css', 'isColor', 'TYPE_MIN', 'TYPE_MAX', 'cssVar', 'tokenValue']) {
+    if (mod[name] === undefined) throw new Error(`dist/index.js does not export ${name}`)
+  }
+  if (typeof mod.vars !== 'function') throw new Error('vars is not callable from the built package')
+  const v = mod.vars({ type: 1.2, density: 'compact' })
+  if (v['--type-scale'] !== '1.2') throw new Error(`built vars() returned ${JSON.stringify(v)}`)
+})
+
+await check('no emitted module uses an extensionless relative specifier', () => {
+  // The class of bug, not just the one instance: Node ESM resolves relative
+  // specifiers literally, so a missing `.js` is always a runtime failure.
+  const bad = []
+  for (const [, entry] of Object.entries(pkg.exports ?? {})) {
+    const target = typeof entry === 'string' ? entry : entry.import
+    if (typeof target !== 'string' || target.includes('*') || !target.endsWith('.js')) continue
+    const file = join(root, target)
+    if (!existsSync(file)) continue
+    for (const m of readFileSync(file, 'utf8').matchAll(/from\s+['"](\.[^'"]*)['"]/g)) {
+      if (!/\.(js|mjs|cjs|json|css)$/.test(m[1])) bad.push(`${target}: ${m[1]}`)
+    }
+  }
+  if (bad.length) throw new Error(`extensionless relative imports:\n         ${bad.join('\n         ')}`)
+})
+
+if (failed) {
+  console.error(`\n${failed} dist check(s) failed`)
+  process.exit(1)
+}
+console.log('dist: all checks passed')

package/scripts/check-preference.mjs

@@ -0,0 +1,168 @@
+/**
+ * Preference contract, checked the way this package already checks tokens:
+ * a plain node script, no framework, run by `npm test`.
+ *
+ * The load-bearing check is the last one. The first version of preference.ts
+ * kept its own copy of the type ramp and the copy was WRONG (lg/xl were 16/18
+ * against the tokens' 15/17), so a preference of 1 — "leave it alone" — would
+ * have resized two rungs of the published design. Nothing caught it, because
+ * nothing compared the copy to the source. Now there is no copy: the knobs are
+ * multipliers and the ramps live only in tokens/*.css, and check 5 fails if a
+ * rung ever stops carrying its multiplier.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const root = join(here, "..");
+
+// Load the source directly — this package ships tokens, and the preference
+// module is small enough to evaluate without a build step in the check.
+const src = readFileSync(join(root, "src/preference.ts"), "utf8");
+const js = src
+  .replace(/^import[^\n]*\n/gm, "")
+  .replace(/export (type|interface) [\s\S]*?\n}\n/g, "")
+  .replace(/export type [^\n]*\n/g, "")
+  .replace(/: Record<[^>]*>/g, "")
+  .replace(/: Preference/g, "")
+  .replace(/: Density/g, "")
+  .replace(/: string/g, "")
+  .replace(/: number/g, "")
+  .replace(/: boolean/g, "")
+  .replace(/export /g, "");
+
+const mod = new Function(`${js}; return { vars, css, isColor, TYPE_MIN, TYPE_MAX };`)();
+const { vars, css, isColor, TYPE_MIN, TYPE_MAX } = mod;
+
+let failed = 0;
+const check = (name, fn) => {
+  try {
+    fn();
+    console.log(`  ok   ${name}`);
+  } catch (e) {
+    failed++;
+    console.error(`  FAIL ${name}\n       ${e.message}`);
+  }
+};
+const eq = (a, b, m) => {
+  const A = JSON.stringify(a), B = JSON.stringify(b);
+  if (A !== B) throw new Error(`${m || ""} got ${A} want ${B}`);
+};
+const ok = (v, m) => { if (!v) throw new Error(m || "expected truthy"); };
+
+console.log("preference:");
+
+check("an unset preference changes nothing", () => {
+  eq(vars({}), {});
+  eq(css({}), "");
+});
+
+check("type is ONE knob, not a restated ramp", () => {
+  const v = vars({ type: 1.2 });
+  eq(Object.keys(v), ["--type-scale"], "type must emit exactly one name:");
+  eq(v["--type-scale"], "1.2");
+});
+
+check("type is CLAMPED — a preference cannot make the UI illegible", () => {
+  eq(vars({ type: 0.1 })["--type-scale"], String(TYPE_MIN), "min");
+  eq(vars({ type: 99 })["--type-scale"], String(TYPE_MAX), "max");
+  // the smallest rung must stay readable at the floor: 11px * TYPE_MIN
+  ok(11 * TYPE_MIN >= 9, "xs falls below 9px at the floor");
+});
+
+check("density moves spacing only, and never touches type", () => {
+  const v = vars({ density: "compact" });
+  eq(Object.keys(v), ["--density"]);
+  ok(Number(v["--density"]) < 1, "compact should tighten");
+  ok(Number(vars({ density: "comfortable" })["--density"]) > 1, "comfortable should loosen");
+  ok(!("--type-scale" in v), "density must not touch type");
+  // Spacing compounds through nesting, so the range stays tight enough that a
+  // 44px coarse-pointer target does not fall under the floor.
+  ok(Number(vars({ density: "compact" })["--density"]) >= 0.8, "compact is too tight to stay tappable");
+});
+
+check("EVERY ramp rung carries its multiplier — no rung can opt out", () => {
+  // This is the check that the drifting copy would have failed.
+  const type = readFileSync(join(root, "tokens/typography.css"), "utf8");
+  const space = readFileSync(join(root, "tokens/spacing.css"), "utf8");
+
+  const bare = [];
+  for (const [file, text, knob, re] of [
+    ["typography.css", type, "--type-scale", /--text-[a-z0-9]+:\s*([^;]+);/g],
+    ["spacing.css", space, "--density", /--space-\d+:\s*([^;]+);/g],
+  ]) {
+    for (const m of text.matchAll(re)) {
+      const value = m[1].trim();
+      if (value === "0") continue;                 // zero times anything is zero
+      if (value.startsWith("var(")) continue;      // an alias inherits its target's calc
+      if (!value.includes(`var(${knob}`)) bare.push(`${file}: ${m[0].trim()}`);
+    }
+  }
+  eq(bare, [], "rungs that do NOT scale with their knob:");
+});
+
+check("a unitless leading stays a RATIO — scaling it would double-apply", () => {
+  const type = readFileSync(join(root, "tokens/typography.css"), "utf8");
+  const bad = [];
+  for (const m of type.matchAll(/--leading-[a-z0-9]+:\s*([^;]+);/g)) {
+    const v = m[1].trim();
+    // A ratio (`1.05`) already scales with the font size it multiplies.
+    if (/^[0-9.]+$/.test(v) === false) continue;
+    if (v.includes("var(")) bad.push(m[0].trim());
+  }
+  eq(bad, [], "unitless leadings must not carry a multiplier:");
+});
+
+check("a colour lands on both --primary and --accent", () => {
+  const v = vars({ accent: "#808000" });
+  eq(v["--primary"], "#808000");
+  eq(v["--accent"], "#808000");
+});
+
+check("a NON-colour is dropped, never sanitised into something plausible", () => {
+  for (const bad of [
+    "red; background-image:url(//evil/x)",
+    "}html{display:none",
+    "url(//evil/x)",
+    "expression(alert(1))",
+    "",
+    "   ",
+  ]) {
+    const v = vars({ accent: bad });
+    ok(!("--primary" in v), `accepted ${JSON.stringify(bad)}`);
+    ok(!isColor(bad), `isColor said yes to ${JSON.stringify(bad)}`);
+  }
+});
+
+check("real colour notations are accepted", () => {
+  for (const good of ["#fff", "#ffffff", "#ffffffff", "rgb(1 2 3)", "oklch(.7 .1 120)", "rebeccapurple"]) {
+    ok(isColor(good), `isColor said no to ${good}`);
+  }
+});
+
+check("css() emits ONE block for the selector it is given", () => {
+  const out = css({ type: 1.1, density: "compact", accent: "#fff" }, ":root");
+  ok(out.startsWith(":root{") && out.endsWith("}"), out.slice(0, 40));
+  ok(!out.includes("}" + "{"), "emitted more than one block");
+});
+
+check("every emitted name is one the token files actually read", () => {
+  // A variable nothing reads is a write into another document — the exact
+  // mistake this package exists to prevent. The knobs are READ by the ramps
+  // (as var(--knob, 1)); the colours are DECLARED by colors.css.
+  const files = ["tokens/typography.css", "tokens/spacing.css", "tokens/grid.css", "tokens/colors.css"];
+  const text = files.map((f) => readFileSync(join(root, f), "utf8")).join("\n");
+  const declared = new Set([...text.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gm)].map((m) => m[1]));
+  const read = new Set([...text.matchAll(/var\((--[a-z0-9-]+)/g)].map((m) => m[1]));
+
+  const emitted = Object.keys(vars({ type: 1.1, density: "compact", accent: "#fff" }));
+  const orphans = emitted.filter((k) => !declared.has(k) && !read.has(k));
+  eq(orphans, [], "emitted names no token file declares or reads:");
+});
+
+if (failed) {
+  console.error(`\n${failed} preference check(s) failed`);
+  process.exit(1);
+}
+console.log("preference: all checks passed");

package/scripts/check-tokens.mjs

@@ -140,6 +140,40 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : fail('base.css is UNLAYERED — its element rules outrank every utility an app writes')
 }
 
+// ── 1d. exactly ONE rule decides focus ───────────────────────────────────
+// Until 0.4.9 there were two: a field rule that suppressed the outline and drew
+// a brightened edge + halo, and the generic ring. Both computed to (0,1,0) —
+// :where() zeroes its contents and each side keeps one pseudo-class — so the
+// cascade fell through to SOURCE ORDER inside @layer base, the generic rule was
+// written later, and it overrode the `outline:none` the field rule stated
+// expressly to prevent it. Every focused input on every consumer drew BOTH.
+// Each rule read as correct alone; the defect existed only in their order,
+// which is why it survived review in both files.
+//
+// Order is not testable as intent, so this tests the property that replaced it:
+// one rule paints the indicator, and nothing else touches focus. A second rule
+// is how they disagree, `outline:none` is how an indicator disappears, and
+// box-shadow is how a second one appears — none of the three can return quietly.
+{
+  const base = strip(read(join(tokensDir, 'base.css')))
+  // `outline-offset` is a different property and never matches: the colon must
+  // follow `outline` itself.
+  const OUTLINE = /(?:^|[;{\s])outline\s*:\s*([^;}]+)/
+  const rules = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+    .map(([, sel, body]) => ({ sel: sel.trim().replace(/\s+/g, ' '), body }))
+    .filter(({ sel }) => sel.includes(':focus-visible'))
+
+  const paints = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() !== 'none' })
+  const mutes = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() === 'none' })
+  const halos = rules.filter(({ body }) => /(?:^|[;{\s])box-shadow\s*:/.test(body))
+
+  paints.length === 1
+    ? pass(`one focus indicator, one rule: \`${paints[0].sel}\``)
+    : fail(`${paints.length} rules paint a focus outline (${paints.map((r) => r.sel).join(' / ')}) — equal specificity inside @layer base, so source order decides which one a user actually sees`)
+  mutes.forEach(({ sel }) => fail(`\`${sel}\` sets outline:none — it removes the focus indicator instead of replacing it`))
+  halos.forEach(({ sel }) => fail(`\`${sel}\` adds a box-shadow on focus — a second indicator beside the ring`))
+}
+
 // ── 2. every var() used inside the token layer must resolve ──────────────
 {
   const declared = new Set()
@@ -268,5 +302,31 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
   }
 }
 
+// ── 5. one light, from one direction ─────────────────────────────────────
+// The paper ramp reads as one space only while every edge and every drop in
+// the system agrees where the light is. A single `2px 4px` — the spelling
+// every other library ships — puts a second lamp in the room, and the failure
+// is not visible on any one component: the panel with the offset shadow looks
+// fine, and it is the SCREEN that stops making sense. So the rule is checked
+// on the values instead of trusted to whoever writes the next one: the light
+// is directly above, so a shadow moves down and never sideways.
+//
+// Structural, not by name — a layer counts as a shadow when its first two
+// lengths are lengths, which is what a shadow is and what a size is not.
+{
+  const css = strip(read(join(tokensDir, 'elevation.css')))
+  const LEN = /^-?[\d.]+(px|rem|em)?$/
+  const offenders = []
+  for (const [, name, value] of css.matchAll(/--([A-Za-z0-9-]+)\s*:\s*([^;]+);/g))
+    for (const layer of value.split(',')) {
+      const t = layer.trim().replace(/^inset\s+/, '').split(/\s+/)
+      if (LEN.test(t[0]) && LEN.test(t[1] ?? '') && parseFloat(t[0]) !== 0)
+        offenders.push(`--${name} (${layer.trim()})`)
+    }
+  offenders.length
+    ? offenders.forEach((o) => fail(`${o} is offset sideways — the light is above, so every shadow is \`0 <y> …\``))
+    : pass('one light direction — every shadow in elevation.css drops straight down')
+}
+
 console.log(failures ? `\n${failures} check(s) failed` : '\nall token checks passed')
 process.exit(failures ? 1 : 0)