@hanzo/design 0.4.9 → 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.9",
+  "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/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(";")}}`;
+}