@hanzo/design 0.4.8 → 0.4.10

package/dist/index.d.ts

@@ -33,4 +33,6 @@ export declare function tokenValue(name: CssVarName): string | undefined;
  * bare. Pass a URL you serve.
  */
 export declare function injectDesignCss(href: string): void;
+export { vars, css, isColor, TYPE_MIN, TYPE_MAX } from './preference';
+export type { Preference, Density } from './preference';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE1D,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG,UAAU,SAAS,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAA;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9E;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,cAAc,iBAAiB,CAAA;AAC/B,OAAO,EAAW,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE1D,uFAAuF;AACvF,MAAM,MAAM,SAAS,GAAG,UAAU,SAAS,KAAK,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAA;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAI9E;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAQlD;AAKD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACtE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -58,3 +58,7 @@ export function injectDesignCss(href) {
     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';

package/dist/preference.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Three axes, because those are the three the token files already separate:
+ *
+ *   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)
+ */
+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 declare const TYPE_MIN = 0.85;
+export declare const TYPE_MAX = 1.4;
+/**
+ * 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 declare function isColor(v: string): boolean;
+/**
+ * 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 declare function vars(p: Preference): Record<string, string>;
+/** `vars()` as a declaration block, for a <style> tag or an SSR inline. */
+export declare function css(p: Preference, selector?: string): string;
+//# sourceMappingURL=preference.d.ts.map

package/dist/preference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preference.d.ts","sourceRoot":"","sources":["../src/preference.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;AAE5D,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,QAAQ,OAAO,CAAC;AAC7B,eAAO,MAAM,QAAQ,MAAM,CAAC;AA2B5B;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAS1C;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAqB1D;AAED,2EAA2E;AAC3E,wBAAgB,GAAG,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,SAAc,GAAG,MAAM,CAKjE"}

package/dist/preference.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Three axes, because those are the three the token files already separate:
+ *
+ *   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)
+ */
+/**
+ * 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;
+const DENSITY_SCALE = {
+    compact: 0.75,
+    default: 1,
+    comfortable: 1.35,
+};
+/** The type ramp, by name, in rem at a 16px root — mirrors tokens/typography.css. */
+const TEXT = {
+    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 = {
+    "grid-gap-tight": 0.5,
+    "grid-gap": 1,
+    "grid-gap-loose": 1.5,
+};
+const clamp = (n, lo, hi) => 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) => `${Math.round(n * 10000) / 10000}rem`;
+/**
+ * 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) {
+    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) {
+    const out = {};
+    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);
+    }
+    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.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, selector = "html:root") {
+    const v = vars(p);
+    const keys = Object.keys(v);
+    if (!keys.length)
+        return "";
+    return `${selector}{${keys.map((k) => `${k}:${v[k]}`).join(";")}}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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": "MIT OR Apache-2.0",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "test": "node scripts/check-tokens.mjs && node scripts/lint.mjs .",
+    "test": "node scripts/check-tokens.mjs && node scripts/check-preference.mjs && node scripts/lint.mjs .",
     "build": "pnpm gen && pnpm test && tsc -p tsconfig.json",
     "prepublishOnly": "pnpm build",
     "lint": "node scripts/lint.mjs"

package/scripts/check-preference.mjs

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+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 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 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");
+});
+
+check("density moves the gap ramp, not the type ramp", () => {
+  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");
+});
+
+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 declare", () => {
+  // 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]);
+    }
+  }
+  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:");
+});
+
+if (failed) {
+  console.error(`\n${failed} preference check(s) failed`);
+  process.exit(1);
+}
+console.log("preference: all checks passed");

package/scripts/check-tokens.mjs

@@ -140,30 +140,38 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
     : fail('base.css is UNLAYERED — its element rules outrank every utility an app writes')
 }
 
-// ── 1d. a focused element gets exactly ONE indicator ─────────────────────
-// The field rule and the generic ring rule both compute to (0,1,0) — :where()
-// zeroes its contents and each side keeps one pseudo-class — so the cascade
-// falls through to SOURCE ORDER inside @layer base. The generic rule was
-// written later, so it overrode the `outline:none` that the field rule states
-// expressly to prevent it, and every focused input on every consumer drew the
-// 2px ring AND the edge+halo. Both rules read as correct in isolation; only
-// their order was wrong, which is why nobody saw it in either file.
+// ── 1d. exactly ONE rule decides focus ───────────────────────────────────
+// Until 0.4.9 there were two: a field rule that suppressed the outline and drew
+// a brightened edge + halo, and the generic ring. Both computed to (0,1,0) —
+// :where() zeroes its contents and each side keeps one pseudo-class — so the
+// cascade fell through to SOURCE ORDER inside @layer base, the generic rule was
+// written later, and it overrode the `outline:none` the field rule stated
+// expressly to prevent it. Every focused input on every consumer drew BOTH.
+// Each rule read as correct alone; the defect existed only in their order,
+// which is why it survived review in both files.
 //
-// Order is not testable as intent, so this tests the property instead: a rule
-// that paints an outline on focus must not be able to land on a field.
+// Order is not testable as intent, so this tests the property that replaced it:
+// one rule paints the indicator, and nothing else touches focus. A second rule
+// is how they disagree, `outline:none` is how an indicator disappears, and
+// box-shadow is how a second one appears — none of the three can return quietly.
 {
   const base = strip(read(join(tokensDir, 'base.css')))
-  const FIELDS = 'input,select,textarea'
-  // `outline:none` disarms; anything else paints. `outline-offset` is a
-  // different property and never matches — the colon must follow `outline`.
-  const paints = (body) => /(?:^|[;{\s])outline\s*:\s*(?!none\b)[^;}]+/.test(body)
-  const scoped = (sel) => sel.includes(`:where(${FIELDS})`) || sel.includes(`:not(${FIELDS})`)
-  const doubled = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
+  // `outline-offset` is a different property and never matches: the colon must
+  // follow `outline` itself.
+  const OUTLINE = /(?:^|[;{\s])outline\s*:\s*([^;}]+)/
+  const rules = [...base.matchAll(/([^{}]+)\{([^{}]*)\}/g)]
     .map(([, sel, body]) => ({ sel: sel.trim().replace(/\s+/g, ' '), body }))
-    .filter(({ sel, body }) => sel.includes(':focus-visible') && paints(body) && !scoped(sel))
-  doubled.length
-    ? doubled.forEach(({ sel }) => fail(`\`${sel}\` paints an outline on a field that already draws its own edge + halo — two focus indicators`))
-    : pass('one focus indicator per element: fields brighten their edge, everything else rings')
+    .filter(({ sel }) => sel.includes(':focus-visible'))
+
+  const paints = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() !== 'none' })
+  const mutes = rules.filter(({ body }) => { const m = body.match(OUTLINE); return m && m[1].trim() === 'none' })
+  const halos = rules.filter(({ body }) => /(?:^|[;{\s])box-shadow\s*:/.test(body))
+
+  paints.length === 1
+    ? pass(`one focus indicator, one rule: \`${paints[0].sel}\``)
+    : fail(`${paints.length} rules paint a focus outline (${paints.map((r) => r.sel).join(' / ')}) — equal specificity inside @layer base, so source order decides which one a user actually sees`)
+  mutes.forEach(({ sel }) => fail(`\`${sel}\` sets outline:none — it removes the focus indicator instead of replacing it`))
+  halos.forEach(({ sel }) => fail(`\`${sel}\` adds a box-shadow on focus — a second indicator beside the ring`))
 }
 
 // ── 2. every var() used inside the token layer must resolve ──────────────

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,124 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * Three axes, because those are the three the token files already separate:
+ *
+ *   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)
+ */
+
+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;
+
+const DENSITY_SCALE: Record<Density, number> = {
+  compact: 0.75,
+  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,
+};
+
+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`;
+
+/**
+ * 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)) {
+    const k = clamp(p.type, TYPE_MIN, TYPE_MAX);
+    for (const [name, size] of Object.entries(TEXT)) out[`--text-${name}`] = rem(size * k);
+  }
+
+  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.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/styles.css

@@ -834,20 +834,26 @@
     padding:0 var(--space-3);
   }
   :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
-  /* ——— focus, on a control ———
-     Not the generic ring. A field already HAS an edge, so focus brightens that
-     edge (.15 -> .22) and adds a soft halo just outside it — which is what the
-     reference does (.composer-box:focus-within) and what separates a focused
-     field from a browser default. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :where(input,select,textarea):focus-visible{
-    outline:none;
-    border-color:var(--border-focus);
-    box-shadow:var(--ring-focus);
-  }
-  /* A hovered field lifts its surface a rung. Nudging its EDGE from .15 to .16
-     is a state nobody can see. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :where(input,select,textarea):hover:not(:focus-visible):not(:disabled){background:var(--surface-3)}
   :where(input,textarea)::placeholder{color:var(--text-disabled)}
   :where(input,select,textarea,button):disabled{opacity:.5;cursor:not-allowed}
@@ -887,17 +893,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */
   ::selection{background:var(--selection);color:var(--text-primary)}

package/tailwind.css

@@ -857,20 +857,26 @@
     padding:0 var(--space-3);
   }
   :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
-  /* ——— focus, on a control ———
-     Not the generic ring. A field already HAS an edge, so focus brightens that
-     edge (.15 -> .22) and adds a soft halo just outside it — which is what the
-     reference does (.composer-box:focus-within) and what separates a focused
-     field from a browser default. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :where(input,select,textarea):focus-visible{
-    outline:none;
-    border-color:var(--border-focus);
-    box-shadow:var(--ring-focus);
-  }
-  /* A hovered field lifts its surface a rung. Nudging its EDGE from .15 to .16
-     is a state nobody can see. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :where(input,select,textarea):hover:not(:focus-visible):not(:disabled){background:var(--surface-3)}
   :where(input,textarea)::placeholder{color:var(--text-disabled)}
   :where(input,select,textarea,button):disabled{opacity:.5;cursor:not-allowed}
@@ -910,17 +916,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */
   ::selection{background:var(--selection);color:var(--text-primary)}

package/tokens/base.css

@@ -99,20 +99,26 @@
     padding:0 var(--space-3);
   }
   :where(textarea){padding:var(--space-2) var(--space-3);resize:vertical}
-  /* ——— focus, on a control ———
-     Not the generic ring. A field already HAS an edge, so focus brightens that
-     edge (.15 -> .22) and adds a soft halo just outside it — which is what the
-     reference does (.composer-box:focus-within) and what separates a focused
-     field from a browser default. `outline:none` drops the UA's own focus ring,
-     which would otherwise draw a second, harder box around this one; the
-     generic ring below excludes fields for the same reason. */
-  :where(input,select,textarea):focus-visible{
-    outline:none;
-    border-color:var(--border-focus);
-    box-shadow:var(--ring-focus);
-  }
-  /* A hovered field lifts its surface a rung. Nudging its EDGE from .15 to .16
-     is a state nobody can see. */
+  /* A field has NO focus rule of its own — see the ring at the bottom of this
+     layer, which is the one focus indicator for everything.
+
+     There used to be one here: `outline:none` plus a brightened edge (.15 ->
+     .22) plus a soft halo, the composer look. It was removed because it could
+     not do the job in either of the two ways that matter.
+
+     It was never VISIBLE ENOUGH. Composited on --background the brightened edge
+     measures 1.91:1 and the halo 1.25:1, against the 3:1 that WCAG 1.4.11 asks
+     of a focus indicator and that this package already gates --ring on. The
+     budget was documented as being spent entirely on --ring "because that is
+     what a keyboard user navigates by" — true for a button, and false for a
+     field for exactly as long as this rule told fields not to use it.
+
+     And it was SUPPRESSIBLE. It carried the indicator on `border-color`, so any
+     app that states `border` on its own fields overrode it — @hanzo/id does,
+     unlayered, which beats this layer whatever its specificity, and its focused
+     fields sat at the resting .15 while both files read as correct. An outline
+     is not a border: nothing in an app's field styling reaches it, so the ring
+     paints whether or not the app has opinions about edges. */
   :where(input,select,textarea):hover:not(:focus-visible):not(:disabled){background:var(--surface-3)}
   :where(input,textarea)::placeholder{color:var(--text-disabled)}
   :where(input,select,textarea,button):disabled{opacity:.5;cursor:not-allowed}
@@ -152,17 +158,20 @@
     }
   }
 
-  /* The generic ring — for everything that is NOT a field. The exclusion is
-     load-bearing, not tidiness. This rule and the control rule above both
-     compute to (0,1,0): :where() zeroes whatever it wraps, leaving one
-     pseudo-class on each side. Equal specificity inside one layer falls through
-     to source order, this rule sits 46 lines LATER, so it overrode the
-     `outline:none` written above to prevent precisely this — and every focused
-     input, select and textarea on every consumer drew BOTH the 2px ring and the
-     edge+halo. Two indicators, from the two rules that each say there is one.
-     Stating the exclusion in the selector fixes it by MEANING rather than by
-     position, so reordering either rule cannot bring it back. */
-  :where(:not(input,select,textarea)):focus-visible{outline:2px solid var(--ring);outline-offset:2px}
+  /* THE focus indicator. One rule, every focusable thing, no exceptions — a
+     button, a link, a summary, a field. 2px at --ring is 3.77:1 on the darkest
+     canvas and clears the 2px perimeter WCAG 2.4.13 asks for; the gate in
+     check-tokens holds --ring to that and nothing else here may weaken it.
+
+     There were two rules until 0.4.9, and they collided invisibly. Both computed
+     to (0,1,0) — :where() zeroes whatever it wraps, leaving one pseudo-class on
+     each side — so the cascade fell through to SOURCE ORDER inside this layer,
+     this rule was written later, and it overrode the `outline:none` the field
+     rule stated expressly to prevent it. Every focused input on every consumer
+     drew BOTH the ring and the edge+halo. Each rule read as correct alone, which
+     is why it survived review in both files; the defect existed only in their
+     order. One rule cannot disagree with itself. */
+  :focus-visible{outline:2px solid var(--ring);outline-offset:2px}
   /* --white-20 is white-on-white in the light theme, so selection reads through
      --selection, which BOTH themes define. */
   ::selection{background:var(--selection);color:var(--text-primary)}