@hanzo/design 0.3.5 → 0.4.0

package/README.md

@@ -127,3 +127,28 @@ Tokens track `hanzo.ai` (`app/globals.css`, `tailwind.config.ts`, `DESIGN.md`) a
 ## License
 
 BSD-3-Clause. Brand marks (the Hanzo logo, partner and provider logos) are the property of their respective owners and are provided for identification.
+
+## Using it in a Tailwind app
+
+One import, after Tailwind's:
+
+```css
+@import "tailwindcss";
+@import "@hanzo/design/tailwind.css";
+```
+
+That carries the tokens **and** maps them onto Tailwind's namespace, so
+`bg-background`, `text-muted-foreground` and `border-border` resolve to the
+system's values. There is no `@theme` block to hand-write and keep in sync.
+
+Not using Tailwind? `@import "@hanzo/design/styles.css"` is the same tokens
+without the bridge.
+
+### Two rules, and the build enforces both
+
+- **Import it after `tailwindcss`.** `@theme` extends the framework, so it has
+  to follow it.
+- **Don't re-declare tokens in your app.** An app that states its own palette
+  drifts from every other surface, and any token it forgets resolves to nothing
+  — `border-border` becomes `currentColor`, which paints a white hairline on
+  black and reads as a design choice rather than a missing line.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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",
@@ -27,7 +27,8 @@
     "./prompts/*": "./prompts/*",
     "./content/*": "./content/*",
     "./assets/*": "./assets/*",
-    "./skills/*": "./skills/*"
+    "./skills/*": "./skills/*",
+    "./tailwind.css": "./tailwind.css"
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
@@ -41,6 +42,7 @@
   },
   "files": [
     "dist",
+    "tailwind.css",
     "src",
     "styles.css",
     "tokens",

package/scripts/check-tokens.mjs

@@ -59,6 +59,46 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : pass(`all ${urls.length} asset url()s resolve from the package root`)
 }
 
+// ── 1b. the Tailwind bridge is complete and self-contained ───────────────
+// An app should write ONE import and get working utilities. Each thing checked
+// here failed silently in production before it was checked: a missing slot
+// makes that utility resolve to nothing (`border-border` -> currentColor -> a
+// white hairline on black), and a surviving @import makes the browser drop
+// every token without a word.
+{
+  const tw = strip(read(join(root, 'tailwind.css')))
+  tw.includes('@import')
+    ? fail('tailwind.css contains an @import — invalid after `@import "tailwindcss"`, so the tokens are dropped')
+    : pass('tailwind.css has no @import to invalidate')
+
+  // Every Tailwind colour slot an app will reach for must be mapped.
+  const slots = ['background', 'foreground', 'card', 'popover', 'primary', 'secondary',
+                 'muted', 'muted-foreground', 'accent', 'destructive', 'border', 'input', 'ring']
+  const unmapped = slots.filter((s) => !tw.includes(`--color-${s}:`))
+  unmapped.length
+    ? fail(`tailwind.css does not map: ${unmapped.join(', ')}`)
+    : pass(`tailwind.css maps all ${slots.length} core colour slots`)
+
+  // And it must carry the values, not merely reference them.
+  tw.includes('--border:')
+    ? pass('tailwind.css carries the token values inline')
+    : fail('tailwind.css maps slots but carries no tokens — every utility resolves to nothing')
+}
+
+// ── 1c. element defaults must LOSE to an app's utilities ─────────────────
+// A rule outside a cascade layer beats a rule inside one regardless of
+// specificity, so an unlayered `a{color:...}` here silently outranked every
+// Tailwind text utility on every anchor — a `text-neutral-950` primary button
+// rendered white-on-white and read as a rendering glitch. These are DEFAULTS;
+// a default that cannot be overridden is not a default.
+{
+  const base = strip(read(join(tokensDir, 'base.css'))).trim()
+  const layered = /^@layer\s+base\s*\{/.test(base) && base.endsWith('}')
+  layered
+    ? pass('base.css element defaults are inside @layer base')
+    : fail('base.css is UNLAYERED — its element rules outrank every utility an app writes')
+}
+
 // ── 2. every var() used inside the token layer must resolve ──────────────
 {
   const declared = new Set()

package/scripts/gen-tokens.mjs

@@ -124,3 +124,82 @@ const bundle = banner + FILES.map((f) => {
 }).join('')
 writeFileSync(join(root, 'styles.css'), bundle)
 console.log(`gen-tokens: wrote styles.css — ${FILES.length} token groups, flattened`)
+
+// ── tailwind.css — the ONE line a Tailwind app writes ────────────────────
+// Every app that consumed these tokens still had to hand-write the bridge from
+// our variable names to Tailwind's utility namespace:
+//
+//   @theme inline { --color-background: var(--background); ...twenty more }
+//
+// Twenty lines of boilerplate, copied into each new app, is a drift vector with
+// a silent failure mode: miss one and that utility resolves to nothing —
+// `border-border` becomes currentColor and paints a white hairline on black,
+// which reads as a design choice rather than a missing line. Tabs shipped with
+// three of these and used forty-one.
+//
+// So the bridge is generated here from SLOTS, and an app writes one import
+// after `@import "tailwindcss"`. There is nothing left to get wrong, and adding
+// a semantic token wires it up for every app at once.
+const SLOTS = [
+  'background', 'foreground',
+  'card', 'card-foreground',
+  'popover', 'popover-foreground',
+  'primary', 'primary-foreground',
+  'secondary', 'secondary-foreground',
+  'muted', 'muted-foreground',
+  'accent', 'accent-foreground',
+  'destructive', 'destructive-foreground',
+  'border', 'input', 'ring',
+]
+// State colours are their own vocabulary and keep their names, so `text-error`
+// and `bg-online` mean what they say instead of borrowing a neutral slot.
+const STATE = { error: 'state-error', success: 'state-success', online: 'state-online' }
+
+const declared = new Set(flat.map(([n]) => n.replace(/^--/, '')))
+const missing = SLOTS.filter((s) => !declared.has(s))
+if (missing.length) {
+  console.error(`gen-tokens: tokens/colors.css declares no --${missing.join(', --')}`)
+  process.exit(1)
+}
+
+const tw = `/* Hanzo Design System — Tailwind v4 bridge. The ONE import a Tailwind app adds.
+ *
+ * AUTO-GENERATED by scripts/gen-tokens.mjs — DO NOT EDIT.
+ *
+ *   @import "tailwindcss";
+ *   @import "@hanzo/design/tailwind.css";
+ *
+ * It carries the tokens AND maps them onto Tailwind's utility namespace, so
+ * \`bg-background\`, \`text-muted-foreground\` and \`border-border\` resolve to the
+ * system's values with nothing to wire up by hand.
+ *
+ * Import it AFTER tailwindcss: @theme has to come after the framework it
+ * extends, and the element defaults are layered so your utilities still win.
+ *
+ * "inline" is deliberate — it compiles \`border-border\` to var(--border) rather
+ * than to that variable's build-time value, so switching .light at runtime moves
+ * the UI and not merely the variables.
+ *
+ * The tokens are inlined below rather than @imported for the reason styles.css
+ * is flattened: an @import must precede every other rule, so importing this
+ * after tailwindcss would invalidate it and the browser would drop the whole
+ * token layer without a word.
+ */
+${bundle}
+
+@theme inline {
+${SLOTS.map((s) => `  --color-${s}: var(--${s});`).join('\n')}
+
+${Object.entries(STATE).map(([k, v]) => `  --color-${k}: var(--${v});`).join('\n')}
+
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+}
+`
+writeFileSync(join(root, 'tailwind.css'), tw)
+console.log(`gen-tokens: wrote tailwind.css — ${SLOTS.length} colour slots + ${Object.keys(STATE).length} states`)

package/styles.css

@@ -473,25 +473,40 @@
 
 /* ── tokens/base.css ─────────────────────────────────────── */
 /* Minimal element defaults so specimen cards and kits inherit the brand without
-   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}
-/* 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,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)}
-/* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
-   bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
-   blanket `a:hover` underlined every one of them on every surface that imports
-   these tokens. Scope it to the elements that actually carry prose; a link that
-   is a component states its own hover. The old rule also re-set `color` to the
-   value `a` already has — a no-op that only served to outrank a component's own
-   hover colour. */
-:is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
-:focus-visible{outline:2px solid var(--ring);outline-offset:2px}
-::selection{background:var(--white-20);color:#fff}
+   a utility framework. Components carry their own styles inline.
+
+   EVERYTHING HERE IS LAYERED, and that is the most important line in the file.
+   A rule outside a cascade layer beats a rule inside one no matter how specific
+   the loser is — so an unlayered `a{color:...}` here outranked EVERY Tailwind
+   text utility on every anchor, on every surface that imports these tokens. A
+   white-on-white primary button is what that looks like: `text-neutral-950` on
+   an anchor, silently overridden to --text-primary, invisible on its own white
+   fill, and reading as a rendering glitch rather than a cascade bug.
+
+   The same trap already bit `text-decoration` here once (see the a:hover note
+   below). It was fixed by deleting that one declaration, which left the identical
+   defect in `color` untouched. Layering fixes the whole class: these are
+   DEFAULTS, and a default must lose to anything an app states deliberately. */
+@layer base {
+  *{box-sizing:border-box;border-color:var(--border)}
+  html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
+  /* 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,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)}
+  /* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
+     bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
+     blanket `a:hover` underlined every one of them on every surface that imports
+     these tokens. Scope it to the elements that actually carry prose; a link that
+     is a component states its own hover. The old rule also re-set `color` to the
+     value `a` already has — a no-op that only served to outrank a component's own
+     hover colour. */
+  :is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  ::selection{background:var(--white-20);color:#fff}
+}

package/tailwind.css

@@ -0,0 +1,570 @@
+/* Hanzo Design System — Tailwind v4 bridge. The ONE import a Tailwind app adds.
+ *
+ * AUTO-GENERATED by scripts/gen-tokens.mjs — DO NOT EDIT.
+ *
+ *   @import "tailwindcss";
+ *   @import "@hanzo/design/tailwind.css";
+ *
+ * It carries the tokens AND maps them onto Tailwind's utility namespace, so
+ * `bg-background`, `text-muted-foreground` and `border-border` resolve to the
+ * system's values with nothing to wire up by hand.
+ *
+ * Import it AFTER tailwindcss: @theme has to come after the framework it
+ * extends, and the element defaults are layered so your utilities still win.
+ *
+ * "inline" is deliberate — it compiles `border-border` to var(--border) rather
+ * than to that variable's build-time value, so switching .light at runtime moves
+ * the UI and not merely the variables.
+ *
+ * The tokens are inlined below rather than @imported for the reason styles.css
+ * is flattened: an @import must precede every other rule, so importing this
+ * after tailwindcss would invalidate it and the browser would drop the whole
+ * token layer without a word.
+ */
+/* Hanzo Design System — the entry point. Import THIS one file.
+ *
+ * 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".
+ *
+ * Flattened deliberately: a consumer's bundler resolves a nested url() against
+ * ITS OWN directory, not ours, so an @import list here is a build error in
+ * every app that follows the instruction above. Nested imports must also
+ * precede all other rules, which the spec invalidates the moment the consumer
+ * imports anything first — browsers then drop them silently and every token
+ * resolves to nothing. The content is inlined in the order the groups were
+ * always imported in.
+ */
+
+/* ── tokens/colors.css ─────────────────────────────────────── */
+/* Hanzo is monochrome. One hue rendered through an opacity ladder.
+   Base ladder = Tailwind neutral (tailwind.config.ts). Semantic names match
+   hanzo.ai's CSS variables exactly, so code copies over 1:1.
+   DARK IS THE DEFAULT THEME (hanzo.ai mounts ThemeProvider defaultTheme="dark"). */
+
+:root{
+  /* ——— base neutral ladder ——— */
+  --neutral-50:#FAFAFA;
+  --neutral-100:#F5F5F5;
+  --neutral-200:#E5E5E5;
+  --neutral-300:#D4D4D4;
+  --neutral-400:#A3A3A3;
+  --neutral-500:#737373;
+  --neutral-600:#525252;
+  --neutral-700:#404040;
+  --neutral-800:#262626;
+  --neutral-900:#171717;
+  --neutral-950:#0A0A0A;
+  --pure-black:#000000;
+  --pure-white:#FFFFFF;
+  /* Press-kit brand constants (public/press/hanzo/README.md). */
+  --hanzo-black:#0A0A0B;
+  --hanzo-white:#FFFFFF;
+
+  /* ——— the opacity ladder: the real palette ——— */
+  --white-05:rgb(255 255 255 / .05);
+  --white-10:rgb(255 255 255 / .10);
+  --white-15:rgb(255 255 255 / .15);
+  --white-20:rgb(255 255 255 / .20);
+  --white-30:rgb(255 255 255 / .30);
+  --white-40:rgb(255 255 255 / .40);
+  --white-60:rgb(255 255 255 / .60);
+  --white-80:rgb(255 255 255 / .80);
+
+  /* ——— semantic aliases (dark, the default) ——— */
+  --background:#000000;
+  --foreground:#ededed;
+  --card:#0a0a0a;
+  --card-foreground:#f5f5f5;
+  --popover:#0a0a0a;
+  --popover-foreground:#f5f5f5;
+  --primary:#ffffff;
+  --primary-foreground:#000000;
+  --secondary:#1a1a1a;
+  --secondary-foreground:#f5f5f5;
+  --muted:#101010;
+  --muted-foreground:#888888;
+  --accent:#1a1a1a;
+  --accent-foreground:#f5f5f5;
+  --destructive:#666666;
+  --destructive-foreground:#f5f5f5;
+  --border:#1f1f1f;
+  --input:#1f1f1f;
+  /* 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;
+  --black:#000000;
+  --white:#f5f5f5;
+
+  /* ——— surface recipes (card fills used across hanzo.ai) ——— */
+  --surface-page:var(--background);
+  --surface-card:rgb(23 23 23 / .5);        /* bg-neutral-900/50 — grid tiles */
+  --surface-card-emphasis:rgb(23 23 23 / .8);/* bg-neutral-900/80 — featured   */
+  --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-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);
+  --text-secondary:var(--white-80);
+  --text-tertiary:var(--white-60);
+  --text-helper:var(--muted-foreground);
+  --text-disabled:var(--white-30);
+
+  /* ——— the ONLY permitted hues (DESIGN.md §2.4) ——— */
+  --state-error:#ef4444;        /* red-500  — destructive / blocking error   */
+  --state-error-text:#fca5a5;   /* red-300                                    */
+  --state-error-bg:rgb(239 68 68 / .1);
+  --state-online:#4ade80;       /* green-400 — live status dot                */
+  --state-success:#22c55e;      /* green-500 — "Free" / "Save N%" callouts    */
+  --chrome-dot-red:rgb(239 68 68 / .6);
+  --chrome-dot-yellow:rgb(234 179 8 / .6);
+  --chrome-dot-green:rgb(34 197 94 / .6);
+}
+
+/* Light theme — the same tokens, inverted. Rare: only /brand-style docs pages. */
+.light{
+  --background:#ffffff;
+  --foreground:#0a0a0a;
+  --card:#f5f5f5;
+  --card-foreground:#0a0a0a;
+  --popover:#ffffff;
+  --popover-foreground:#0a0a0a;
+  --primary:#0a0a0a;
+  --primary-foreground:#ffffff;
+  --secondary:#f5f5f5;
+  --secondary-foreground:#0a0a0a;
+  --muted:#f5f5f5;
+  --muted-foreground:#525252;
+  --accent:#f5f5f5;
+  --accent-foreground:#0a0a0a;
+  --destructive:#999999;
+  --destructive-foreground:#ffffff;
+  --border:#e5e5e5;
+  --input:#e5e5e5;
+  /* 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;
+  --surface-card-emphasis:#ffffff;
+  --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 */
+  /* 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);
+  --text-disabled:rgb(10 10 10 / .3);
+}
+
+/* ── tokens/typography.css ─────────────────────────────────────── */
+/* TIGHT app-first type scale — the compact developer-app register (linear.app /
+   vercel.com / the Codex desktop look), the Hanzo default across chat / app /
+   desktop. Base is 14px, nav 13px, labels 11px; display sizes tightened. Kept in
+   lockstep with @hanzo/brand (styles/variables.css --font-size-* + typography.ts)
+   — the two are the SAME scale, mirrored. A surface/tenant overrides any --text-*
+   on :root to retune density on demand. */
+:root{
+  --text-xs:0.6875rem;  --leading-xs:1rem;      /* 11px — eyebrows / section labels */
+  --text-sm:0.8125rem;  --leading-sm:1.15rem;   /* 13px — nav labels, dense body */
+  --text-base:0.875rem; --leading-base:1.35rem; /* 14px — base app text (was 16px) */
+  --text-lg:0.9375rem;  --leading-lg:1.4rem;    /* 15px */
+  --text-xl:1.0625rem;  --leading-xl:1.55rem;   /* 17px */
+  --text-2xl:1.3125rem; --leading-2xl:1.7rem;   /* 21px */
+  --text-3xl:1.625rem;  --leading-3xl:1.95rem;  /* 26px */
+  --text-4xl:2rem;      --leading-4xl:2.25rem;  /* 32px */
+  --text-5xl:2.5rem;    --leading-5xl:1.05;     /* 40px */
+  --text-6xl:3.25rem;   --leading-6xl:1;        /* 52px */
+  --text-7xl:4rem;      --leading-7xl:1;        /* 64px */
+  --text-8xl:5.25rem;   --leading-8xl:1;        /* 84px */
+  --text-9xl:7rem;      --leading-9xl:1;        /* 112px */
+
+  /* The SAME scale under @hanzo/brand's spelling. @hanzo/gui's shell theme and
+     Hanzo Studio address the ramp as --font-size-*; both names are one value, so
+     a component written against either resolves here. --text-* is canonical. */
+  --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;
+  --weight-bold:700;
+
+  --tracking-tight:-0.025em;
+  --tracking-normal:0em;
+  --tracking-wide:0.025em;
+  --tracking-widest:0.1em;   /* eyebrows / uppercase category labels */
+
+  --leading-none:1;
+  --leading-tight:1.25;
+  --leading-snug:1.375;
+  --leading-normal:1.5;
+  --leading-relaxed:1.625;
+  --leading-golden:1.618;
+
+  /* named roles */
+  --type-hero:600 var(--text-5xl)/1.05 var(--font-display);
+  --type-h2:700 var(--text-4xl)/var(--leading-4xl) var(--font-display);
+  --type-h3:600 var(--text-xl)/var(--leading-xl) var(--font-display);
+  --type-lead:400 var(--text-lg)/var(--leading-relaxed) var(--font-sans);
+  --type-body:400 var(--text-sm)/var(--leading-sm) var(--font-sans);
+  --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);
+}
+
+/* ── tokens/spacing.css ─────────────────────────────────────── */
+/* Spacing: the 4px Tailwind ramp is what ships. The golden-ratio ramp below is
+   declared in hanzo.ai's tailwind.config.ts (legacy v3 config, kept for
+   reference) — use it for editorial layouts, not for component padding. */
+:root{
+  --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;
+
+  /* golden ramp (φ) — hanzo.ai tailwind.config.ts */
+  --golden-1:0.25rem;
+  --golden-2:0.405rem;
+  --golden-3:0.654rem;
+  --golden-4:1.059rem;
+  --golden-5:1.713rem;
+  --golden-6:2.772rem;
+  --golden-7:4.487rem;
+  --golden-8:7.26rem;
+  --golden-9:11.749rem;
+  --golden-split:38.2% 61.8%; /* @kind other */
+
+  /* layout rules (DESIGN.md §1.3) */
+  --container-max:80rem;      /* max-w-7xl — grids            */
+  --container-prose:48rem;    /* max-w-3xl — centered text    */
+  --container-wide:72rem;     /* max-w-6xl — landing sections */
+  --gutter:1rem;              /* px-4                          */
+  --gutter-sm:1.5rem;         /* sm:px-6                       */
+  --gutter-lg:2rem;           /* lg:px-8                       */
+  --section-y:4rem;           /* py-16 — content sections      */
+  --section-y-lg:6rem;        /* py-24 — landing sections      */
+  --hero-y:5rem;              /* py-20 …                       */
+  --hero-y-lg:8rem;           /* … lg:py-32                    */
+  --header-height:4rem;
+}
+
+/* ── tokens/grid.css ─────────────────────────────────────── */
+/* Grid — one definition of the field every Hanzo surface lays out on.
+
+   Derived, not invented. Across hanzo.ai and hanzo.app the grid written by hand
+   is overwhelmingly ONE grid: `grid-cols-1 md:grid-cols-2 lg:grid-cols-3` with a
+   1.5rem gutter (240 / 197 / 127 / 185 occurrences on hanzo.ai alone, and the
+   same shape leads on app). 1, 2, 3 and 4 columns account for 97% of every
+   grid-cols- in both repos, and all four divide 12 cleanly — so 12 is the base
+   the spans are cut from, and the long tail (5, 6, 7, 8, 12) still lands on it.
+
+   Containers, gutters and section rhythm are NOT restated here: spacing.css
+   already owns --container-max / --container-prose / --container-wide /
+   --gutter* / --section-y*, and a grid that redeclared them would be a second
+   answer to a settled question. This file adds only what a grid knows that
+   spacing does not — how many columns, how far apart, and where it reflows. */
+:root{
+  /* The base. Spans are cut from twelve because 1/2/3/4/6 all divide it. */
+  --grid-columns:12;
+
+  /* Gutter. --grid-gap is the measured card-grid default (gap-6 leads hanzo.ai
+     at 185 uses); tight and loose are the neighbouring steps that cover app's
+     gap-4 (45) and the wide editorial grids (gap-8, 75). All three reference the
+     space ramp — the grid does not get its own private set of distances. */
+  --grid-gap:var(--space-6);
+  --grid-gap-tight:var(--space-4);
+  --grid-gap-loose:var(--space-8);
+
+  /* Reflow points, byte-identical to the Tailwind v4 defaults these surfaces
+     already compile against. Same NAMES and same VALUES on purpose: the utility
+     layer and anything reading tokens then resolve one value, not two that agree
+     by luck. md and lg carry ~85% of every breakpoint prefix in use; xl is 44
+     occurrences across both repos and 2xl is 1. */
+  --breakpoint-sm:40rem;
+  --breakpoint-md:48rem;
+  --breakpoint-lg:64rem;
+  --breakpoint-xl:80rem;
+  --breakpoint-2xl:96rem;
+
+  /* Intrinsic card grids: state ONE track minimum instead of three column counts
+     at three breakpoints. `repeat(auto-fit, minmax(var(--grid-card-min), 1fr))`
+     reflows 1 -> 2 -> 3 at the same widths the explicit recipe does, and it does
+     it from the space available rather than from the viewport — so a card grid
+     inside a sidebar behaves correctly, which the breakpoint version cannot.
+
+     18rem is chosen, not rounded to: inside --container-max less --gutter-lg on
+     both sides, lg (64rem) leaves ~60rem, where 3 tracks need 3x18 + 2x1.5 =
+     57rem and 4 would need 76.5rem; md (48rem) leaves ~44rem, where 2 tracks
+     need 37.5rem and 3 would need 57rem. The measured 1/2/3 ladder falls out. */
+  --grid-card-min:18rem;
+  --grid-card-min-wide:24rem;
+}
+
+/* ── tokens/radius.css ─────────────────────────────────────── */
+:root{
+  --radius:0.5rem;            /* the base token (globals.css)      */
+  --radius-sm:0.375rem;       /* rounded-md — buttons, inputs      */
+  --radius-md:0.5rem;
+  --radius-lg:0.75rem;        /* rounded-xl — cards                */
+  --radius-xl:1rem;           /* rounded-2xl — dropdown panels     */
+  --radius-2xl:1.5rem;        /* rounded-3xl — story / hero cards  */
+  --radius-composer:28px;     /* the chat composer, exactly 28px   */
+  --radius-full:9999px;       /* pills, CTAs, avatars, badges      */
+}
+
+/* ── tokens/elevation.css ─────────────────────────────────────── */
+/* Hanzo barely uses shadow: on black, elevation reads as a hairline border plus
+   a wide, very dark drop. Only two levels ship (Tailwind's shadow-2xl for
+   floating surfaces) plus the ambient radial glow used behind heroes. */
+:root{
+  --shadow-none:none;
+  --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;
+  /* Card top-corner sheen used on the story cards. */
+  --sheen-card:radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%); /* @kind color */
+  /* Chrome text: the canonical headline gradient. Never a saturated rainbow. */
+  --gradient-chrome:linear-gradient(to right,#ffffff,var(--white-80),var(--white-60));
+  --gradient-chrome-2:linear-gradient(to right,#ffffff,var(--neutral-500));
+  /* Section-top protection gradient (hero overlays). */
+  --gradient-protect:linear-gradient(to bottom,var(--white-10),transparent);
+}
+
+/* ── tokens/motion.css ─────────────────────────────────────── */
+/* Motion is restrained: fade + small rise, CSS-only hovers, one breathing glow.
+   No springs, no bounce, no parallax, no autoplay carousels. */
+:root{
+  --duration-fast:150ms; /* @kind other */   /* dropdown / panel open        */
+  --duration-base:300ms; /* @kind other */   /* slide-up-fade                */
+  --duration-slow:400ms; /* @kind other */   /* hero element entry           */
+  --duration-slower:500ms; /* @kind other */ /* section entry                */
+  --duration-glow:9s; /* @kind other */      /* ambient radial breathe       */
+  --ease-out:cubic-bezier(0,0,0.2,1); /* @kind other */
+  --ease-in-out:cubic-bezier(0.4,0,0.2,1); /* @kind other */
+  --stagger:60ms; /* @kind other */          /* per-element delay in a group */
+  --entry-rise:16px;       /* hero y-offset                */
+  --entry-rise-lg:24px;    /* card y-offset                */
+}
+
+@keyframes hanzo-fade-up{from{opacity:0;transform:translateY(10px)}to{opacity:1;transform:translateY(0)}}
+@keyframes hanzo-fade-down{from{opacity:0;transform:translateY(-10px)}to{opacity:1;transform:translateY(0)}}
+@keyframes hanzo-slide-up-fade{from{opacity:0;transform:translateY(20px)}to{opacity:1;transform:translateY(0)}}
+@keyframes hanzo-glow{0%,100%{transform:scale(1);opacity:.45}50%{transform:scale(1.08);opacity:.65}}
+@keyframes hanzo-pulse-dot{0%,100%{opacity:1}50%{opacity:.35}}
+
+@media (prefers-reduced-motion:reduce){
+  *,*::before,*::after{animation-duration:.001ms!important;animation-iteration-count:1!important;transition-duration:.001ms!important}
+}
+
+/* ── tokens/z.css ─────────────────────────────────────── */
+/* Stacking order — the one z-index ladder. Layers are named by role, never by a
+   magic number, so a dropdown opened from the fixed header always sits above it
+   and nothing ever reaches for 9999. Below --z-raised is ordinary document flow.
+
+   Rungs are 100 apart so a surface can slot a one-off BETWEEN two roles
+   (calc(var(--z-modal) + 1)) without inventing a new decade. */
+:root{
+  --z-base:0;
+  --z-raised:10;       /* hover-lifted cards, sticky table headers          */
+  --z-sticky:200;      /* pinned section rails                              */
+  --z-header:300;      /* the fixed site header                             */
+  --z-dropdown:400;    /* menus, selects, comboboxes                        */
+  --z-overlay:500;     /* dialog / sheet scrim                              */
+  --z-modal:600;       /* dialogs, sheets, command palette                  */
+  --z-popover:700;     /* popovers, tooltips (also when anchored in modals) */
+  --z-toast:800;       /* toasts / notifications — always on top            */
+
+  /* @hanzo/brand spells the top two rungs --z-tooltip and --z-notification.
+     Same rungs, so a component written against either vocabulary stacks
+     identically. --z-popover / --z-toast are canonical. */
+  --z-tooltip:var(--z-popover);
+  --z-notification:var(--z-toast);
+}
+
+/* ── tokens/fonts.css ─────────────────────────────────────── */
+/* Geist Sans + Geist Mono — the only two faces on Hanzo surfaces.
+   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;
+  --font-display:var(--font-sans);
+  --font-mono:"Geist Mono",ui-monospace,SFMono-Regular,monospace;
+  --font-serif:Georgia,serif;
+  /* hanzo.ai sets these OpenType features on <body>. */
+  --font-feature-settings:"ss01","ss02","cv01","cv02","cv03";
+}
+
+/* ── tokens/base.css ─────────────────────────────────────── */
+/* Minimal element defaults so specimen cards and kits inherit the brand without
+   a utility framework. Components carry their own styles inline.
+
+   EVERYTHING HERE IS LAYERED, and that is the most important line in the file.
+   A rule outside a cascade layer beats a rule inside one no matter how specific
+   the loser is — so an unlayered `a{color:...}` here outranked EVERY Tailwind
+   text utility on every anchor, on every surface that imports these tokens. A
+   white-on-white primary button is what that looks like: `text-neutral-950` on
+   an anchor, silently overridden to --text-primary, invisible on its own white
+   fill, and reading as a rendering glitch rather than a cascade bug.
+
+   The same trap already bit `text-decoration` here once (see the a:hover note
+   below). It was fixed by deleting that one declaration, which left the identical
+   defect in `color` untouched. Layering fixes the whole class: these are
+   DEFAULTS, and a default must lose to anything an app states deliberately. */
+@layer base {
+  *{box-sizing:border-box;border-color:var(--border)}
+  html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
+  /* 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,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)}
+  /* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
+     bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
+     blanket `a:hover` underlined every one of them on every surface that imports
+     these tokens. Scope it to the elements that actually carry prose; a link that
+     is a component states its own hover. The old rule also re-set `color` to the
+     value `a` already has — a no-op that only served to outrank a component's own
+     hover colour. */
+  :is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  ::selection{background:var(--white-20);color:#fff}
+}
+
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+
+  --color-error: var(--state-error);
+  --color-success: var(--state-success);
+  --color-online: var(--state-online);
+
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+}

package/tokens/base.css

@@ -1,23 +1,38 @@
 /* Minimal element defaults so specimen cards and kits inherit the brand without
-   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}
-/* 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,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)}
-/* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
-   bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
-   blanket `a:hover` underlined every one of them on every surface that imports
-   these tokens. Scope it to the elements that actually carry prose; a link that
-   is a component states its own hover. The old rule also re-set `color` to the
-   value `a` already has — a no-op that only served to outrank a component's own
-   hover colour. */
-:is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
-:focus-visible{outline:2px solid var(--ring);outline-offset:2px}
-::selection{background:var(--white-20);color:#fff}
+   a utility framework. Components carry their own styles inline.
+
+   EVERYTHING HERE IS LAYERED, and that is the most important line in the file.
+   A rule outside a cascade layer beats a rule inside one no matter how specific
+   the loser is — so an unlayered `a{color:...}` here outranked EVERY Tailwind
+   text utility on every anchor, on every surface that imports these tokens. A
+   white-on-white primary button is what that looks like: `text-neutral-950` on
+   an anchor, silently overridden to --text-primary, invisible on its own white
+   fill, and reading as a rendering glitch rather than a cascade bug.
+
+   The same trap already bit `text-decoration` here once (see the a:hover note
+   below). It was fixed by deleting that one declaration, which left the identical
+   defect in `color` untouched. Layering fixes the whole class: these are
+   DEFAULTS, and a default must lose to anything an app states deliberately. */
+@layer base {
+  *{box-sizing:border-box;border-color:var(--border)}
+  html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
+  /* 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,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)}
+  /* Underline is the accessible affordance for a link in RUNNING TEXT and a visual
+     bug everywhere else: nav items, cards and anchor-buttons are all <a> too, so a
+     blanket `a:hover` underlined every one of them on every surface that imports
+     these tokens. Scope it to the elements that actually carry prose; a link that
+     is a component states its own hover. The old rule also re-set `color` to the
+     value `a` already has — a no-op that only served to outrank a component's own
+     hover colour. */
+  :is(p,li,blockquote,dd,dt,td,th,figcaption) a:hover{text-decoration:underline}
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  ::selection{background:var(--white-20);color:#fff}
+}