@hanzo/design 0.4.9 → 0.4.11

package/scripts/check-preference.mjs

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

package/src/index.ts

@@ -62,3 +62,9 @@ export function injectDesignCss(href: string): void {
   l.setAttribute('data-hanzo-design', '')
   document.head.appendChild(l)
 }
+
+// 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';

package/src/preference.ts

@@ -0,0 +1,122 @@
+/**
+ * A person's own reading of the system: type size, density, accent.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * 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";
+
+export interface Preference {
+  /** Multiplier on the type ramp. 1 is the published scale. */
+  type?: number;
+  density?: Density;
+  /** A CSS colour for --primary / --accent. Rejected unless it is one. */
+  accent?: string;
+}
+
+/**
+ * The type multiplier is CLAMPED, and the bounds are not arbitrary.
+ *
+ * Below 0.85 the smallest rung (--text-xs, 11px) drops under 9.4px, which stops
+ * being small and starts being unreadable — and a preference that lets someone
+ * render their own tools illegible is a trap, not a choice. Above 1.4 the
+ * chrome stops fitting its own containers: this app's builder header already
+ * overlaps its actions below 1440px at scale 1.
+ */
+export const TYPE_MIN = 0.85;
+export const TYPE_MAX = 1.4;
+
+/**
+ * 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.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 round = (n: number) => String(Math.round(n * 10000) / 10000);
+
+/**
+ * Is this a colour, or is it something being smuggled into a style attribute?
+ *
+ * A preference is user input and its destination is CSS. `#fff`, `rgb(...)`,
+ * `oklch(...)` and the bare keywords are colours; anything carrying a `;`, a
+ * `}`, or a `url(` is trying to be a second declaration, and the answer is to
+ * drop the axis rather than to sanitise a string into something plausible.
+ */
+export function isColor(v: string): boolean {
+  const s = v.trim();
+  if (!s || s.length > 64) return false;
+  if (/[;{}()]/.test(s) && !/^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\([^;{}]*\)$/i.test(s)) return false;
+  return (
+    /^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(s) ||
+    /^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch|color)\([^;{}]*\)$/i.test(s) ||
+    /^[a-z]{3,20}$/i.test(s)
+  );
+}
+
+/**
+ * The custom properties a preference produces.
+ *
+ * Only the axes actually set appear, so an app can spread the result over
+ * whatever it already has without a default silently overriding a brand.
+ */
+export function vars(p: Preference): Record<string, string> {
+  const out: Record<string, string> = {};
+
+  if (typeof p.type === "number" && Number.isFinite(p.type)) {
+    out["--type-scale"] = round(clamp(p.type, TYPE_MIN, TYPE_MAX));
+  }
+
+  if (p.density && p.density in DENSITY) {
+    out["--density"] = round(DENSITY[p.density]);
+  }
+
+  if (p.accent && isColor(p.accent)) {
+    // Both names, because the ramp uses --primary for action surfaces and
+    // --accent for selection. One hue, stated once, landing on both.
+    out["--primary"] = p.accent.trim();
+    out["--accent"] = p.accent.trim();
+  }
+
+  return out;
+}
+
+/** `vars()` as a declaration block, for a <style> tag or an SSR inline. */
+export function css(p: Preference, selector = "html:root"): string {
+  const v = vars(p);
+  const keys = Object.keys(v);
+  if (!keys.length) return "";
+  return `${selector}{${keys.map((k) => `${k}:${v[k]}`).join(";")}}`;
+}

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;