@hanzo/design 0.5.16 → 0.5.18

package/README.md

@@ -81,7 +81,7 @@ import { HanzoLogo } from "@hanzo/design/components/core/HanzoLogo.jsx";
 | `content/` | The words — brand voice and taglines. |
 | `docs/` | How to use the system — integrate the tokens, theme, extend. |
 | `guidelines/` | Specimen cards — color, type, spacing, brand, iconography — the visual reference. |
-| `assets/fonts/` | Geist Sans + Geist Mono, self-hosted (two variable `.woff2`, 141 KB, SIL OFL-1.1). No Google Fonts request. |
+| `assets/fonts/` | Zen + Zen Mono, self-hosted (two variable `.woff2`, 141 KB, SIL OFL-1.1). No Google Fonts request. |
 | `assets/` | The mark, wordmark, favicon, provider + partner logos, brand imagery. |
 | `scripts/check-tokens.mjs` | The gate: every token file is served, every internal `var()` resolves, and the contrast floors hold. Runs on `npm run build`. |
 | `ui_kits/` | Composed surfaces (e.g. `SiteChrome`) assembled from the components. |

package/assets/fonts/{LICENSE-Geist.txt → LICENSE-Zen.txt}

@@ -1,4 +1,5 @@
 Copyright (c) 2023 Vercel, in collaboration with basement.studio
+Copyright (c) 2026 Hanzo AI, Inc.
 
 This Font Software is licensed under the SIL Open Font License, Version 1.1.
 This license is copied below, and is also available with a FAQ at:

package/dist/brand.cjs

@@ -0,0 +1,62 @@
+"use strict";
+// A brand's declared theme, projected onto the semantic tokens.
+//
+// A brand package (@luxfi/brand, @zooai/brand) carries its own light and dark
+// theme in brand.json. This is the ONE place that says which semantic token each
+// of those answers for — the design system owns the token contract, a brand owns
+// the values, and neither holds a copy of the other.
+//
+// It exists because that mapping was about to be written twice: once in each
+// brand package to generate a stylesheet, and once in every app that resolves its
+// brand at runtime and cannot import a build-time stylesheet. Two copies of a
+// mapping is how a brand comes to look like itself in one surface and not
+// another.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.themeToTokens = themeToTokens;
+exports.applyBrandTheme = applyBrandTheme;
+/** theme key → the semantic tokens it answers for. */
+const OWNS = {
+    surface1: ['--background'],
+    surface2: ['--card', '--popover', '--muted'],
+    surface3: ['--accent'],
+    neutral1: ['--foreground', '--card-foreground', '--popover-foreground', '--accent-foreground'],
+    neutral2: ['--muted-foreground'],
+    neutral3: [],
+    accent1: ['--primary'],
+    accent2: [],
+    accent3: [],
+    border: ['--border'],
+    success: ['--state-success'],
+    warning: ['--state-warning'],
+    error: ['--state-error'],
+};
+/**
+ * The tokens a brand's theme sets, as `{ '--background': '#000', … }`.
+ *
+ * Only ground, ink, accent and the edges drawn on them. The radius scale, the
+ * type ramp, spacing, motion and z are NOT here and must not be: they are the
+ * system's grammar rather than a brand's voice, and a brand that redefines them
+ * is a fork wearing a stylesheet.
+ */
+function themeToTokens(theme) {
+    const out = {};
+    for (const [key, tokens] of Object.entries(OWNS)) {
+        const value = theme[key];
+        if (!value)
+            continue;
+        for (const token of tokens)
+            out[token] = value;
+    }
+    // --primary carries ink on top of it, so the accent names its own contrast
+    // partner rather than leaving whatever the previous theme set.
+    if (theme.accent1 && theme.surface1)
+        out['--primary-foreground'] = theme.surface1;
+    return out;
+}
+/** Apply a brand's theme to a live document — for an app that resolves its brand
+ *  at runtime and so cannot import a build-time stylesheet. */
+function applyBrandTheme(theme, el) {
+    for (const [name, value] of Object.entries(themeToTokens(theme))) {
+        el.style.setProperty(name, value);
+    }
+}

package/dist/index.cjs

@@ -0,0 +1,92 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RATIO_MAX = exports.RATIO_MIN = exports.TYPE_MAX = exports.TYPE_MIN = exports.isColor = exports.css = exports.vars = void 0;
+exports.cssVar = cssVar;
+exports.tokenValue = tokenValue;
+exports.injectDesignCss = injectDesignCss;
+// @hanzo/design — the ONE programmatic control plane for Hanzo's look & feel.
+//
+// The look/feel is authored ONCE as CSS custom properties in tokens/*.css
+// (monochrome, dark-default — "one hue through an opacity ladder"). This module
+// exposes those exact tokens to code, generated from the CSS so the two can
+// never drift. Change a token in the CSS → the stylesheet AND every code
+// consumer (the @hanzogui/shell theme, Tamagui, any TS surface) update together.
+//
+//   import '@hanzo/design/styles.css'                 // the CSS layer (unchanged)
+//   import { colors, spacing, radius, cssVar } from '@hanzo/design'  // the code layer
+//
+__exportStar(require("./tokens.gen.cjs"), exports);
+__exportStar(require("./brand.cjs"), exports);
+const tokens_gen_js_1 = require("./tokens.gen.cjs");
+/**
+ * A `var(--name, <authored literal>)` reference to a token — the ONE way code
+ * should reach a token, so it resolves through the live CSS cascade (honoring
+ * the viewer's light/dark theme and any brand fork) rather than baking a value.
+ *
+ *   background: cssVar('--background')      // → "var(--background, #000000)"
+ *   color:      cssVar('foreground', '#fff')// → "var(--foreground, #fff)"
+ *
+ * The name is checked AGAINST THE STYLESHEET at compile time. That check used to
+ * be opted out of with `| (string & {})`, which is how `cssVar('surface-1')`
+ * shipped: the token did not exist, `var(--surface-1)` resolved to nothing, and
+ * a menu painted transparent with no error anywhere. An undefined custom
+ * property fails SILENTLY, so the type is the only place it can be caught.
+ *
+ * When no explicit fallback is given the token's own authored literal is used,
+ * so the reference still paints on a host that has not loaded the CSS layer.
+ */
+function cssVar(name, fallback) {
+    const n = (name.startsWith('--') ? name : `--${name}`);
+    const lit = fallback ?? tokens_gen_js_1.cssVars[n];
+    return lit ? `var(${n}, ${lit})` : `var(${n})`;
+}
+/** The raw authored value of a token (the literal from the CSS), or `undefined`. */
+function tokenValue(name) {
+    return tokens_gen_js_1.cssVars[name];
+}
+/**
+ * Inject the design-system stylesheet from code (idempotent) for surfaces that
+ * cannot use a bundler CSS import (e.g. a runtime-mounted island). Prefer the
+ * static `import '@hanzo/design/styles.css'` where a bundler is available.
+ * No-op outside the browser.
+ *
+ * `href` is REQUIRED: this used to default to esm.sh, which silently made a
+ * third-party CDN the origin of the entire token layer for anyone who called it
+ * bare. Pass a URL you serve.
+ */
+function injectDesignCss(href) {
+    if (typeof document === 'undefined')
+        return;
+    if (document.querySelector('link[data-hanzo-design]'))
+        return;
+    const l = document.createElement('link');
+    l.rel = 'stylesheet';
+    l.href = 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.
+var preference_js_1 = require("./preference.cjs");
+Object.defineProperty(exports, "vars", { enumerable: true, get: function () { return preference_js_1.vars; } });
+Object.defineProperty(exports, "css", { enumerable: true, get: function () { return preference_js_1.css; } });
+Object.defineProperty(exports, "isColor", { enumerable: true, get: function () { return preference_js_1.isColor; } });
+Object.defineProperty(exports, "TYPE_MIN", { enumerable: true, get: function () { return preference_js_1.TYPE_MIN; } });
+Object.defineProperty(exports, "TYPE_MAX", { enumerable: true, get: function () { return preference_js_1.TYPE_MAX; } });
+Object.defineProperty(exports, "RATIO_MIN", { enumerable: true, get: function () { return preference_js_1.RATIO_MIN; } });
+Object.defineProperty(exports, "RATIO_MAX", { enumerable: true, get: function () { return preference_js_1.RATIO_MAX; } });

package/dist/preference.cjs

@@ -0,0 +1,225 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MODULAR_MAX = exports.MODULAR_MIN = exports.RATIO_MAX = exports.RATIO_MIN = exports.TYPE_MAX = exports.TYPE_MIN = void 0;
+exports.isColor = isColor;
+exports.vars = vars;
+exports.css = css;
+/**
+ * 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.
+ */
+exports.TYPE_MIN = 0.85;
+exports.TYPE_MAX = 1.4;
+/**
+ * The ratio's bounds are looser than type's, because the ramp defends its own
+ * floor.
+ *
+ * `tokens/typography.css` floors --text-xs/sm with `max()`, so the failure mode
+ * that forces type's tight clamp — a knob quietly rendering 9px labels — cannot
+ * happen on this axis however it combines with type. What is left to bound is
+ * only whether the ramp still READS as a ramp: at 0.75 the app register is
+ * within a hair of uniform, and past 1.5 a page's h2 has left its own body text
+ * behind entirely.
+ */
+exports.RATIO_MIN = 0.75;
+exports.RATIO_MAX = 1.5;
+/**
+ * A MODULAR scale — the classical one, where each display rung is the one below
+ * it times a fixed ratio. Golden is 1.618; the musical intervals designers name
+ * are 1.2 (minor third), 1.25 (major third), 1.333 (perfect fourth) and 1.5
+ * (perfect fifth).
+ *
+ * This is a different RULE from `ratio`, not another dial on it. `ratio` tunes
+ * the contrast of the ramp `tokens/typography.css` authored; this REPLACES that
+ * ramp's display half with a geometric one. Naming a golden-ratio preset as a
+ * contrast value would have been the dishonest version of this feature.
+ *
+ * Bounded below 1.05 because a ratio at 1 is not a scale — every display rung
+ * collapses onto the one before it — and above 2 because doubling every step
+ * puts the fourth rung past a phone's whole width.
+ *
+ * Golden is exactly 1.618 here and is NOT clamped down to something tamer,
+ * because a scale that quietly gives you not-golden when you asked for golden is
+ * worse than one that refuses. What makes that safe is the ceiling below: this
+ * ramp has EIGHT display rungs and a classical modular scale is used with about
+ * four, so at 1.618 the eighth would be 799px. Measured, --text-8xl and
+ * --text-9xl are referenced in 15 files across the fleet, so that is a broken
+ * page and not a hypothetical.
+ */
+exports.MODULAR_MIN = 1.05;
+exports.MODULAR_MAX = 2;
+/**
+ * The rungs a modular scale REGENERATES, in order, and the one it starts from.
+ *
+ * It deliberately stops at the display register. A geometric scale through the
+ * interface rungs is unusable at any real ratio: at 1.25 from a 14px base the
+ * next rungs are 17.5 and 21.9, so the 13px nav label and the 15px lead — the
+ * near-linear steps a dense interface is built on — do not exist. `xl` is the
+ * anchor because it is the last interface rung, so the display half continues
+ * from where the interface ends rather than restarting under it.
+ */
+const DISPLAY_RUNGS = ["2xl", "3xl", "4xl", "5xl", "6xl", "7xl", "8xl", "9xl"];
+const MODULAR_ANCHOR_REM = 1.0625; // --text-xl, 17px
+/**
+ * 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 = {
+    compact: 0.85,
+    default: 1,
+    comfortable: 1.15,
+};
+/**
+ * A face is chosen from the ones `tokens/fonts.css` already declares, and it is
+ * set by REFERENCE — `var(--font-serif)`, never a family list restated here.
+ *
+ * That is what keeps a preference from pinning a face: when the token file
+ * changes what "mono" means, or a brand overrides it, a person who chose mono
+ * follows. Writing `Georgia, serif` here would freeze this file's idea of serif
+ * into every document that ever stored the preference.
+ *
+ * `default` is deliberately absent from the map rather than mapped to
+ * `var(--font-sans)`: the axis writes `--font-sans`, so resolving it to itself
+ * is a cycle, and "no opinion" is already how every other axis says default.
+ */
+const FACE = {
+    system: "ui-sans-serif, system-ui, -apple-system, sans-serif",
+    serif: "var(--font-serif)",
+    mono: "var(--font-mono)",
+};
+/**
+ * The measure moves the CONTAINERS, not the columns.
+ *
+ * `--grid-columns` is 12 because layouts are authored against 12; changing it
+ * re-flows every span a page declares and is a different page, not a wider one.
+ * What a reader actually means by "wider" is how far the text runs before it
+ * wraps, which is `--container-*` — so that is the knob, and the grid inside it
+ * is untouched.
+ */
+const MEASURE = {
+    narrow: { max: "64rem", prose: "40rem", wide: "58rem" },
+    wide: { max: "96rem", prose: "56rem", wide: "86rem" },
+};
+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 round = (n) => 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.
+ */
+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.
+ */
+function vars(p) {
+    const out = {};
+    if (typeof p.type === "number" && Number.isFinite(p.type)) {
+        out["--type-scale"] = round(clamp(p.type, exports.TYPE_MIN, exports.TYPE_MAX));
+    }
+    if (typeof p.ratio === "number" && Number.isFinite(p.ratio)) {
+        out["--type-ratio"] = round(clamp(p.ratio, exports.RATIO_MIN, exports.RATIO_MAX));
+    }
+    if (typeof p.modular === "number" && Number.isFinite(p.modular)) {
+        // Each display rung is the anchor times the ratio to its step, emitted as an
+        // explicit property. An INLINE custom property on :root outranks the
+        // stylesheet, so these simply replace the authored rungs — nothing has to be
+        // unset first, and the interface rungs the sheet declares are untouched
+        // because none is named here. It multiplies out with `--type-scale` for free,
+        // since every rung is still read through that ramp's own calc.
+        const r = clamp(p.modular, exports.MODULAR_MIN, exports.MODULAR_MAX);
+        DISPLAY_RUNGS.forEach((rung, i) => {
+            const rem = MODULAR_ANCHOR_REM * Math.pow(r, i + 1);
+            // THE SAME clamp the authored ramp carries, read from the same two names.
+            // A regenerated rung and an authored one must be bounded identically or
+            // the bound is a property of which code path produced the value, which is
+            // exactly the kind of "it depends" a design system exists to delete. The
+            // bounds are declared once, in tokens/typography.css, and referenced here
+            // — never restated, so moving one moves both.
+            out[`--text-${rung}`] =
+                `clamp(var(--text-floor), calc(${round(rem)}rem * var(--type-scale, 1)), var(--text-ceiling))`;
+        });
+    }
+    if (p.density && p.density in DENSITY) {
+        out["--density"] = round(DENSITY[p.density]);
+    }
+    // Indexed, not `in`-checked: the maps omit `default`, so a lookup answers
+    // undefined for it and for anything stored that is not a face at all. One
+    // read, no cast, and an unknown value is refused by the same line that
+    // resolves a known one.
+    const face = p.font ? FACE[p.font] : undefined;
+    if (face)
+        out["--font-sans"] = face;
+    const measure = p.width ? MEASURE[p.width] : undefined;
+    if (measure) {
+        out["--container-max"] = measure.max;
+        out["--container-prose"] = measure.prose;
+        out["--container-wide"] = measure.wide;
+    }
+    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. */
+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(";")}}`;
+}