@hanzo/design 0.3.2 → 0.3.4

package/dist/tokens.gen.d.ts

@@ -178,6 +178,20 @@ export declare const spacing: {
     readonly 'hero-y-lg': "8rem";
     readonly 'header-height': "4rem";
 };
+/** grid tokens (from tokens/grid.css). Values are raw CSS. */
+export declare const grid: {
+    readonly 'grid-columns': "12";
+    readonly 'grid-gap': "var(--space-6)";
+    readonly 'grid-gap-tight': "var(--space-4)";
+    readonly 'grid-gap-loose': "var(--space-8)";
+    readonly 'breakpoint-sm': "40rem";
+    readonly 'breakpoint-md': "48rem";
+    readonly 'breakpoint-lg': "64rem";
+    readonly 'breakpoint-xl': "80rem";
+    readonly 'breakpoint-2xl': "96rem";
+    readonly 'grid-card-min': "18rem";
+    readonly 'grid-card-min-wide': "24rem";
+};
 /** radius tokens (from tokens/radius.css). Values are raw CSS. */
 export declare const radius: {
     readonly radius: "0.5rem";
@@ -418,6 +432,17 @@ export declare const cssVars: {
     readonly '--hero-y': "5rem";
     readonly '--hero-y-lg': "8rem";
     readonly '--header-height': "4rem";
+    readonly '--grid-columns': "12";
+    readonly '--grid-gap': "var(--space-6)";
+    readonly '--grid-gap-tight': "var(--space-4)";
+    readonly '--grid-gap-loose': "var(--space-8)";
+    readonly '--breakpoint-sm': "40rem";
+    readonly '--breakpoint-md': "48rem";
+    readonly '--breakpoint-lg': "64rem";
+    readonly '--breakpoint-xl': "80rem";
+    readonly '--breakpoint-2xl': "96rem";
+    readonly '--grid-card-min': "18rem";
+    readonly '--grid-card-min-wide': "24rem";
     readonly '--radius': "0.5rem";
     readonly '--radius-sm': "0.375rem";
     readonly '--radius-md': "0.5rem";

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

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

package/dist/tokens.gen.js

@@ -181,6 +181,20 @@ export const spacing = {
     'hero-y-lg': '8rem',
     'header-height': '4rem',
 };
+/** grid tokens (from tokens/grid.css). Values are raw CSS. */
+export const grid = {
+    'grid-columns': '12',
+    'grid-gap': 'var(--space-6)',
+    'grid-gap-tight': 'var(--space-4)',
+    'grid-gap-loose': 'var(--space-8)',
+    'breakpoint-sm': '40rem',
+    'breakpoint-md': '48rem',
+    'breakpoint-lg': '64rem',
+    'breakpoint-xl': '80rem',
+    'breakpoint-2xl': '96rem',
+    'grid-card-min': '18rem',
+    'grid-card-min-wide': '24rem',
+};
 /** radius tokens (from tokens/radius.css). Values are raw CSS. */
 export const radius = {
     'radius': '0.5rem',
@@ -421,6 +435,17 @@ export const cssVars = {
     '--hero-y': '5rem',
     '--hero-y-lg': '8rem',
     '--header-height': '4rem',
+    '--grid-columns': '12',
+    '--grid-gap': 'var(--space-6)',
+    '--grid-gap-tight': 'var(--space-4)',
+    '--grid-gap-loose': 'var(--space-8)',
+    '--breakpoint-sm': '40rem',
+    '--breakpoint-md': '48rem',
+    '--breakpoint-lg': '64rem',
+    '--breakpoint-xl': '80rem',
+    '--breakpoint-2xl': '96rem',
+    '--grid-card-min': '18rem',
+    '--grid-card-min-wide': '24rem',
     '--radius': '0.5rem',
     '--radius-sm': '0.375rem',
     '--radius-md': '0.5rem',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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",
@@ -68,4 +68,4 @@
   "bin": {
     "hanzo-design-lint": "./scripts/lint.mjs"
   }
-}
+}

package/scripts/check-tokens.mjs

@@ -16,16 +16,34 @@ let failures = 0
 const fail = (msg) => { console.error(`  FAIL  ${msg}`); failures++ }
 const pass = (msg) => console.log(`  ok    ${msg}`)
 
-// ── 1. styles.css must serve every token file ────────────────────────────
+// ── 1. styles.css must CARRY every token file ────────────────────────────
 // tokens/z.css was authored, exported and documented — and left out of
 // styles.css, so the whole ladder resolved to nothing on every consumer.
+//
+// The entry point is now generated and FLATTENED, so this checks for the
+// declarations themselves rather than for an @import naming the file. That is
+// the stronger test and it is the one that was actually needed: the old shape
+// passed for years while no bundler could resolve a single token, because a
+// relative url() resolves against the CONSUMER's directory. Presence of the
+// import proved nothing about presence of the tokens.
 {
-  const entry = read(join(root, 'styles.css'))
+  const entry = strip(read(join(root, 'styles.css')))
   const files = readdirSync(tokensDir).filter((f) => f.endsWith('.css'))
-  const missing = files.filter((f) => !entry.includes(`tokens/${f}`))
+  const missing = files.filter((f) => {
+    const decls = [...strip(read(join(tokensDir, f))).matchAll(/--([A-Za-z0-9-]+)\s*:/g)].map((m) => m[1])
+    // A file with no custom properties (pure element rules, e.g. base.css) is
+    // carried if one of its selectors made it across.
+    if (!decls.length) return !entry.includes(strip(read(join(tokensDir, f))).trim().split('\n')[0].trim())
+    return !decls.every((d) => entry.includes(`--${d}`))
+  })
   missing.length
-    ? fail(`styles.css does not import: ${missing.join(', ')}`)
-    : pass(`styles.css serves all ${files.length} token files`)
+    ? fail(`styles.css does not carry the tokens from: ${missing.join(', ')}`)
+    : pass(`styles.css carries all ${files.length} token files, flattened`)
+
+  // And it must stay resolvable: an @import here is the exact defect above.
+  entry.includes('@import')
+    ? fail('styles.css contains an @import — a consumer cannot resolve it (see gen-tokens.mjs)')
+    : pass('styles.css has no @import to resolve')
 }
 
 // ── 2. every var() used inside the token layer must resolve ──────────────

package/scripts/gen-tokens.mjs

@@ -14,7 +14,7 @@ const tokensDir = join(root, 'tokens')
 // The token files, in the same order styles.css imports them. base.css is the
 // semantic-alias layer (references other vars) — parsed too, so `--background`
 // etc. are available programmatically.
-const FILES = ['colors', 'typography', 'spacing', 'radius', 'elevation', 'motion', 'z', 'fonts', 'base']
+const FILES = ['colors', 'typography', 'spacing', 'grid', 'radius', 'elevation', 'motion', 'z', 'fonts', 'base']
 
 // group name for each file (the export const); a couple read better renamed.
 const GROUP = { z: 'zIndex' }
@@ -76,3 +76,42 @@ ts += `export type CssVarName = keyof typeof cssVars\n`
 
 writeFileSync(join(root, 'src', 'tokens.gen.ts'), ts)
 console.log(`gen-tokens: wrote src/tokens.gen.ts — ${flat.length} tokens across ${Object.keys(groups).length} groups`)
+
+// ── styles.css, FLATTENED ────────────────────────────────────────────────
+// The entry point says "import THIS one file", and for a long time no bundler
+// could. It was a list of `@import url("tokens/*.css")`, and a relative url
+// resolves against the file doing the importing — so a consumer's
+// `@import "@hanzo/design/styles.css"` sent webpack looking for
+// `<their app>/tokens/fonts.css` and the build died on a module it never had.
+// Nested imports also have to precede every other rule, which the spec then
+// invalidates the moment the consumer imports anything before them; browsers
+// drop them silently, every token resolves to nothing, and `border-border`
+// falls back to currentColor — a stark white hairline on black.
+//
+// Both failures are the same fact: an @import list is not a stylesheet a
+// consumer can use. So the entry point is now the CONTENT, concatenated in the
+// same order, with no imports to resolve and no order to get wrong. That is why
+// nothing consumed this package and every app hand-rolled its own palette.
+//
+// Authoring does not change: tokens/*.css stays the source of truth and this is
+// its build product, exactly like tokens.gen.ts.
+const banner = `/* 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.
+ */
+`
+const bundle = banner + FILES.map((f) => {
+  const css = readFileSync(join(tokensDir, `${f}.css`), 'utf8').trim()
+  return `\n/* ── tokens/${f}.css ─────────────────────────────────────── */\n${css}\n`
+}).join('')
+writeFileSync(join(root, 'styles.css'), bundle)
+console.log(`gen-tokens: wrote styles.css — ${FILES.length} token groups, flattened`)

package/src/tokens.gen.ts

@@ -185,6 +185,21 @@ export const spacing = {
   'header-height': '4rem',
 } as const
 
+/** grid tokens (from tokens/grid.css). Values are raw CSS. */
+export const grid = {
+  'grid-columns': '12',
+  'grid-gap': 'var(--space-6)',
+  'grid-gap-tight': 'var(--space-4)',
+  'grid-gap-loose': 'var(--space-8)',
+  'breakpoint-sm': '40rem',
+  'breakpoint-md': '48rem',
+  'breakpoint-lg': '64rem',
+  'breakpoint-xl': '80rem',
+  'breakpoint-2xl': '96rem',
+  'grid-card-min': '18rem',
+  'grid-card-min-wide': '24rem',
+} as const
+
 /** radius tokens (from tokens/radius.css). Values are raw CSS. */
 export const radius = {
   'radius': '0.5rem',
@@ -433,6 +448,17 @@ export const cssVars = {
   '--hero-y': '5rem',
   '--hero-y-lg': '8rem',
   '--header-height': '4rem',
+  '--grid-columns': '12',
+  '--grid-gap': 'var(--space-6)',
+  '--grid-gap-tight': 'var(--space-4)',
+  '--grid-gap-loose': 'var(--space-8)',
+  '--breakpoint-sm': '40rem',
+  '--breakpoint-md': '48rem',
+  '--breakpoint-lg': '64rem',
+  '--breakpoint-xl': '80rem',
+  '--breakpoint-2xl': '96rem',
+  '--grid-card-min': '18rem',
+  '--grid-card-min-wide': '24rem',
   '--radius': '0.5rem',
   '--radius-sm': '0.375rem',
   '--radius-md': '0.5rem',

package/styles.css

@@ -1,14 +1,497 @@
-/* Hanzo Design System — global entry point. Import THIS one file.
-   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");
-@import url("tokens/spacing.css");
-@import url("tokens/radius.css");
-@import url("tokens/elevation.css");
-@import url("tokens/motion.css");
-@import url("tokens/z.css");
-@import url("tokens/base.css");
+/* 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. */
+*{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/tokens/grid.css

@@ -0,0 +1,50 @@
+/* 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;
+}