@hanzo/design 0.4.10 → 0.4.12

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

@@ -2,10 +2,13 @@
  * Preference contract, checked the way this package already checks tokens:
  * a plain node script, no framework, run by `npm test`.
  *
- * The three things worth pinning are the three that would hurt: a preference
- * that renders someone's own tools illegible, one that lets a colour field
- * carry a second declaration into a stylesheet, and one that emits names no
- * token file reads.
+ * 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";
@@ -55,30 +58,60 @@ check("an unset preference changes nothing", () => {
   eq(css({}), "");
 });
 
-check("type scales the WHOLE ramp, keeping every relation", () => {
-  const v = vars({ type: 2 }); // clamps to TYPE_MAX
-  const base = parseFloat(v["--text-base"]);
-  const xs = parseFloat(v["--text-xs"]);
-  // 0.875 / 0.6875 must survive the transform
-  const ratio = base / xs;
-  ok(Math.abs(ratio - 0.875 / 0.6875) < 1e-9, `ratio drifted: ${ratio}`);
+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", () => {
-  const tiny = vars({ type: 0.1 });
-  eq(tiny["--text-base"], `${Math.round(0.875 * TYPE_MIN * 10000) / 10000}rem`, "min");
-  const huge = vars({ type: 99 });
-  eq(huge["--text-base"], `${Math.round(0.875 * TYPE_MAX * 10000) / 10000}rem`, "max");
-  // the smallest rung must stay readable at the floor
-  ok(parseFloat(tiny["--text-xs"]) * 16 >= 9, "xs fell below 9px");
+  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 the gap ramp, not the type ramp", () => {
+check("density moves spacing only, and never touches type", () => {
   const v = vars({ density: "compact" });
-  ok(v["--grid-gap"], "no gap emitted");
-  ok(!v["--text-base"], "density must not touch type");
-  ok(parseFloat(v["--grid-gap"]) < 1, "compact should tighten");
-  ok(parseFloat(vars({ density: "comfortable" })["--grid-gap"]) > 1, "comfortable should loosen");
+  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", () => {
@@ -111,21 +144,21 @@ check("real colour notations are accepted", () => {
 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");
+  ok(!out.includes("}" + "{"), "emitted more than one block");
 });
 
-check("every emitted name is one the token files actually declare", () => {
+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.
-  const declared = new Set();
-  for (const f of ["tokens/typography.css", "tokens/grid.css", "tokens/colors.css"]) {
-    for (const m of readFileSync(join(root, f), "utf8").matchAll(/^\s*(--[a-z0-9-]+)\s*:/gm)) {
-      declared.add(m[1]);
-    }
-  }
+  // 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));
-  eq(orphans, [], "emitted names no token file declares:");
+  const orphans = emitted.filter((k) => !declared.has(k) && !read.has(k));
+  eq(orphans, [], "emitted names no token file declares or reads:");
 });
 
 if (failed) {

package/src/index.ts

@@ -66,5 +66,5 @@ export function injectDesignCss(href: string): void {
 // A person's own reading of the system — type size, density, accent — as CSS
 // custom properties. Pure: it maps a preference to variables and returns them,
 // so an app, an embedded preview and a server render all apply it the same way.
-export { vars, css, isColor, TYPE_MIN, TYPE_MAX } from './preference';
-export type { Preference, Density } from './preference';
+export { vars, css, isColor, TYPE_MIN, TYPE_MAX } from './preference.js';
+export type { Preference, Density } from './preference.js';

package/src/preference.ts

@@ -1,23 +1,29 @@
 /**
  * A person's own reading of the system: type size, density, accent.
  *
- * The ramps in `tokens/*.css` are the SHAPE — the relationships between sizes,
- * gaps and hues that make a surface read as one thing. A preference does not
- * replace them and cannot reach inside them. It applies ONE transform to a whole
- * axis, so every size still stands in the same relation to every other size and
- * a customised UI is the same design at a different setting, not a different
- * design.
+ * Three knobs, and each is ONE multiplier on a whole axis — never a restated
+ * ramp. The ramps live in `tokens/*.css`, authored once, and each rung carries
+ * its own `calc(<base> * var(--type-scale, 1))`. So a preference sets three
+ * numbers and every rung follows, including rungs added later and rungs this
+ * file has never heard of.
  *
- * It is a pure function on purpose. `vars()` maps a preference to the custom
- * properties that carry it, and returns them; nothing here touches a document.
- * That is what lets it be tested without a browser and reused by every surface —
- * an app, an embedded builder preview, a server render that inlines the result.
+ * That is not a style choice; it is the fix for a real bug. The first version of
+ * this module kept its own copy of the type ramp so it could recompute each
+ * rung, and the copy was WRONG — it had `lg: 1rem` and `xl: 1.125rem` (16px and
+ * 18px) while `tokens/typography.css` says `0.9375rem` and `1.0625rem` (15px and
+ * 17px). Setting a preference of 1 — "leave it alone" — would have silently
+ * resized two rungs of the published design. A second copy of a value is a
+ * second source of truth, and it drifted before anyone used it.
  *
- * Three axes, because those are the three the token files already separate:
+ * Because the knobs are plain multipliers, any OTHER ramp can opt in the same
+ * way. @hanzo/gui compiles its own `--f-size-*` scale for the 1600-odd
+ * `fontSize="$n"` call sites in the apps; an app that redeclares those as
+ * `calc(<its px> * var(--type-scale, 1))` gets the same control with no change
+ * at scale 1.
  *
- *   type    scales the --text-* ramp
- *   density scales the --grid-gap-* ramp (the spacing between things)
- *   accent  sets --primary / --accent (the one hue the monochrome brand allows)
+ * It is a pure function on purpose: it maps a preference to custom properties
+ * and returns them, touching no document. That is what lets an app, an embedded
+ * preview and a server render apply it identically.
  */
 
 export type Density = "compact" | "default" | "comfortable";
@@ -42,30 +48,24 @@ export interface Preference {
 export const TYPE_MIN = 0.85;
 export const TYPE_MAX = 1.4;
 
-const DENSITY_SCALE: Record<Density, number> = {
-  compact: 0.75,
+/**
+ * Density moves SPACING only, and its range is much tighter than type's.
+ *
+ * Spacing compounds: a page nests padding inside gap inside margin, so a 0.75
+ * multiplier is already three-quarters of every one of those in sequence. Below
+ * that, touch targets fall under the 44px floor `base.css` sets for coarse
+ * pointers, and the control that promised comfort takes it away.
+ */
+const DENSITY: Record<Density, number> = {
+  compact: 0.85,
   default: 1,
-  comfortable: 1.35,
-};
-
-/** The type ramp, by name, in rem at a 16px root — mirrors tokens/typography.css. */
-const TEXT: Record<string, number> = {
-  xs: 0.6875, sm: 0.8125, base: 0.875, lg: 1, xl: 1.125,
-  "2xl": 1.3125, "3xl": 1.625, "4xl": 2, "5xl": 2.5,
-  "6xl": 3.25, "7xl": 4, "8xl": 5.25, "9xl": 7,
-};
-
-/** The gap ramp, in rem — mirrors tokens/grid.css. */
-const GAP: Record<string, number> = {
-  "grid-gap-tight": 0.5,
-  "grid-gap": 1,
-  "grid-gap-loose": 1.5,
+  comfortable: 1.15,
 };
 
 const clamp = (n: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, n));
 
 /** Trim to 4dp so a multiplier cannot emit a 17-digit float into a stylesheet. */
-const rem = (n: number) => `${Math.round(n * 10000) / 10000}rem`;
+const round = (n: number) => String(Math.round(n * 10000) / 10000);
 
 /**
  * Is this a colour, or is it something being smuggled into a style attribute?
@@ -96,13 +96,11 @@ export function vars(p: Preference): Record<string, string> {
   const out: Record<string, string> = {};
 
   if (typeof p.type === "number" && Number.isFinite(p.type)) {
-    const k = clamp(p.type, TYPE_MIN, TYPE_MAX);
-    for (const [name, size] of Object.entries(TEXT)) out[`--text-${name}`] = rem(size * k);
+    out["--type-scale"] = round(clamp(p.type, TYPE_MIN, TYPE_MAX));
   }
 
-  if (p.density && p.density in DENSITY_SCALE) {
-    const k = DENSITY_SCALE[p.density];
-    for (const [name, size] of Object.entries(GAP)) out[`--${name}`] = rem(size * k);
+  if (p.density && p.density in DENSITY) {
+    out["--density"] = round(DENSITY[p.density]);
   }
 
   if (p.accent && isColor(p.accent)) {

package/src/tokens.gen.ts

@@ -96,31 +96,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)',
@@ -162,21 +163,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',
@@ -390,31 +392,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)',
@@ -452,21 +455,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',

package/styles.css

@@ -290,19 +290,25 @@
    — 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 type knob. 1 is the published scale; every rung below multiplies by
+     it, so a surface or a person retunes the WHOLE ramp by setting one
+     number and no rung can drift out of relation with the others.
+     @hanzo/design's `vars({type})` emits exactly this name. */
+  --type-scale:1;
+
+  --text-xs:calc(0.6875rem * var(--type-scale, 1));  --leading-xs:calc(1rem * var(--type-scale, 1));      /* 11px — eyebrows / section labels */
+  --text-sm:calc(0.8125rem * var(--type-scale, 1));  --leading-sm:calc(1.15rem * var(--type-scale, 1));   /* 13px — nav labels, dense body */
+  --text-base:calc(0.875rem * var(--type-scale, 1)); --leading-base:calc(1.35rem * var(--type-scale, 1)); /* 14px — base app text (was 16px) */
+  --text-lg:calc(0.9375rem * var(--type-scale, 1));  --leading-lg:calc(1.4rem * var(--type-scale, 1));    /* 15px */
+  --text-xl:calc(1.0625rem * var(--type-scale, 1));  --leading-xl:calc(1.55rem * var(--type-scale, 1));   /* 17px */
+  --text-2xl:calc(1.3125rem * var(--type-scale, 1)); --leading-2xl:calc(1.7rem * var(--type-scale, 1));   /* 21px */
+  --text-3xl:calc(1.625rem * var(--type-scale, 1));  --leading-3xl:calc(1.95rem * var(--type-scale, 1));  /* 26px */
+  --text-4xl:calc(2rem * var(--type-scale, 1));      --leading-4xl:calc(2.25rem * var(--type-scale, 1));  /* 32px */
+  --text-5xl:calc(2.5rem * var(--type-scale, 1));    --leading-5xl:1.05;     /* 40px */
+  --text-6xl:calc(3.25rem * var(--type-scale, 1));   --leading-6xl:1;        /* 52px */
+  --text-7xl:calc(4rem * var(--type-scale, 1));      --leading-7xl:1;        /* 64px */
+  --text-8xl:calc(5.25rem * var(--type-scale, 1));   --leading-8xl:1;        /* 84px */
+  --text-9xl:calc(7rem * var(--type-scale, 1));      --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
@@ -367,7 +373,7 @@
    form feels broken. pointer:coarse is the real signal — a desktop mouse keeps
    the compact 13px field. */
 @media (pointer:coarse){
-  :root{--text-control:1rem}
+  :root{--text-control:calc(1rem * var(--type-scale, 1))}
 }
 
 /* ── tokens/spacing.css ─────────────────────────────────────── */
@@ -375,21 +381,27 @@
    declared in hanzo.ai's tailwind.config.ts (legacy v3 config, kept for
    reference) — use it for editorial layouts, not for component padding. */
 :root{
+  /* The density knob. 1 is the published spacing; every --space-* rung below
+     multiplies by it, and --grid-gap-* reference those rungs rather than
+     restating them, so gaps, padding and section rhythm move together.
+     @hanzo/design's `vars({density})` emits exactly this name. */
+  --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 ramp (φ) — hanzo.ai tailwind.config.ts */
   --golden-1:0.25rem;