@hanzo/design 0.5.17 → 0.5.19

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/tokens.gen.cjs

@@ -303,9 +303,9 @@ exports.zIndex = {
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 exports.fonts = {
-    'font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+    'font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
     'font-display': 'var(--font-sans)',
-    'font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+    'font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
     'font-serif': 'Georgia,serif',
     'font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
 };
@@ -588,9 +588,9 @@ exports.cssVars = {
     '--z-toast': '800',
     '--z-tooltip': 'var(--z-popover)',
     '--z-notification': 'var(--z-toast)',
-    '--font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+    '--font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
     '--font-display': 'var(--font-sans)',
-    '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+    '--font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
     '--font-serif': 'Georgia,serif',
     '--font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
     '--ring-offset': '-2px',

package/dist/tokens.gen.d.ts

@@ -297,9 +297,9 @@ export declare const zIndex: {
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export declare const fonts: {
-    readonly 'font-sans': "\"Geist\",\"Geist Sans\",ui-sans-serif,system-ui,sans-serif";
+    readonly 'font-sans': "\"Zen\",ui-sans-serif,system-ui,sans-serif";
     readonly 'font-display': "var(--font-sans)";
-    readonly 'font-mono': "\"Geist Mono\",ui-monospace,SFMono-Regular,monospace";
+    readonly 'font-mono': "\"Zen Mono\",ui-monospace,SFMono-Regular,monospace";
     readonly 'font-serif': "Georgia,serif";
     readonly 'font-feature-settings': "\"ss01\",\"ss02\",\"cv01\",\"cv02\",\"cv03\"";
 };
@@ -582,9 +582,9 @@ export declare const cssVars: {
     readonly '--z-toast': "800";
     readonly '--z-tooltip': "var(--z-popover)";
     readonly '--z-notification': "var(--z-toast)";
-    readonly '--font-sans': "\"Geist\",\"Geist Sans\",ui-sans-serif,system-ui,sans-serif";
+    readonly '--font-sans': "\"Zen\",ui-sans-serif,system-ui,sans-serif";
     readonly '--font-display': "var(--font-sans)";
-    readonly '--font-mono': "\"Geist Mono\",ui-monospace,SFMono-Regular,monospace";
+    readonly '--font-mono': "\"Zen Mono\",ui-monospace,SFMono-Regular,monospace";
     readonly '--font-serif': "Georgia,serif";
     readonly '--font-feature-settings': "\"ss01\",\"ss02\",\"cv01\",\"cv02\",\"cv03\"";
     readonly '--ring-offset': "-2px";

package/dist/tokens.gen.js

@@ -300,9 +300,9 @@ export const zIndex = {
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export const fonts = {
-    'font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+    'font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
     'font-display': 'var(--font-sans)',
-    'font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+    'font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
     'font-serif': 'Georgia,serif',
     'font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
 };
@@ -585,9 +585,9 @@ export const cssVars = {
     '--z-toast': '800',
     '--z-tooltip': 'var(--z-popover)',
     '--z-notification': 'var(--z-toast)',
-    '--font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+    '--font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
     '--font-display': 'var(--font-sans)',
-    '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+    '--font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
     '--font-serif': 'Georgia,serif',
     '--font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
     '--ring-offset': '-2px',

package/guidelines/DESIGN.md

@@ -15,42 +15,52 @@ and the dark-black palette.
 
 ---
 
-## 1. Typography — Basel Grotesk + Geist Mono
+## 1. Typography — Zen
 
 | Role | Family | Notes |
 |------|--------|-------|
-| UI / body / display / heading (`sans`) | **Basel Grotesk** | Self-hosted. Book = weight **400**, Medium = weight **500**. |
-| code / data / mono (`mono`) | **Geist Mono** | `next/font/google` (`Geist_Mono`) or the geist CDN. |
+| UI / body / display / heading (`sans`) | **Zen** | Variable, `wght` 100–900. One file covers every weight. |
+| code / data / mono (`mono`) | **Zen Mono** | Variable, same axis. |
+| display accents | **Zen Pixel** | Five cuts: Circle, Grid, Line, Square, Triangle. |
 | Arabic / Hebrew (`--font-ar` / `--font-he`) | unchanged | i18n only — keep. |
 
-**Dropped as defaults:** Geist Sans, DM Sans, Figtree, Inter, PT Sans, Roboto Mono.
+**There is one family.** No Basel Grotesk, no Druk, no Inter, DM Sans, Figtree,
+PT Sans or Roboto Mono — and no licensed third-party face at all, which is the
+point: Zen is ours, so nothing here is a seat count or a domain licence.
 
-Basel is a **licensed, non-Google** face — **self-host** the woff2/woff, do NOT use
-`next/font/google` for it. Canonical files (mirror lux.exchange):
-`Basel-Grotesk-Book.woff2/.woff` (400), `Basel-Grotesk-Medium.woff2/.woff` (500).
-
-`@font-face` (weights 400/500, `font-display: swap`, `font-style: normal`):
+**An app writes nothing.** `@hanzo/design/styles.css` declares the `@font-face`
+rules and serves the binaries out of this package, so importing the token layer
+is the whole integration. Do NOT hand-write an `@font-face`, do NOT reach for
+`next/font/google`, and do NOT add a per-app copy of the files.
 
 ```css
-@font-face {
-  font-family: 'Basel';
-  font-style: normal;
-  font-weight: 400; /* Book; 500 = Medium */
-  font-display: swap;
-  src: url('.../Basel-Grotesk-Book.woff2') format('woff2'),
-       url('.../Basel-Grotesk-Book.woff') format('woff');
-}
+@import "@hanzo/design/styles.css";   /* faces + tokens, one line */
 ```
 
-Per-app adoption (converge the value, keep each app's own mechanism):
-- **@hanzo/ui / Next apps** → `next/font/local` for Basel (`--font-basel-sans`) +
-  `next/font/google` `Geist_Mono` (`--font-geist-mono`). See `app/lib/fonts.ts`;
-  tailwind `sans → var(--font-basel-sans)`, `mono → var(--font-geist-mono)`.
-- **Vite + Tailwind apps** (chat, launcher, desktop) → self-host Basel `@font-face`
-  + geist-mono CDN import; tailwind `fontFamily.sans = ['Basel', …]`,
-  `mono = ['Geist Mono', …]`.
-- **Tamagui (console)** → Basel `@font-face` in globals + override the Tamagui
-  `body`/`heading` font `family` to Basel; Geist Mono for `code`/`pre`.
+Then name the role, never the face: `var(--font-sans)`, `var(--font-mono)`.
+
+### Brand presets
+
+`@hanzo/font/presets.css` carries five settings, each a point in Zen's own
+parameter space that a brand has settled on. Two were FITTED by pixel residual
+against the faces they replace, so the swap holds on metrics rather than on
+taste.
+
+| preset | wght | scaleX | track | use |
+|---|---|---|---|---|
+| `.zen-air` | 220 | — | −.030em | thin display |
+| `.zen-book` | 497 | — | — | text |
+| `.zen-medium` | 606 | — | — | UI emphasis |
+| `.zen-wide` | 845 | 1.56 | −.040em | monumental caps |
+| `.zen-round` | 900 | — | −.018em | heavy and friendly |
+
+`.zen-wide` transforms, so its LAYOUT box stays the untransformed width — give
+it room or clip its container.
+
+**Zen's own alternates cover the neo-grotesque register**, so a brand that wants
+that voice changes a feature setting rather than a family: `ss01` is the
+single-storey `a`, `ss04` the straight-leg `R`, `ss09` a slashed zero and serif
+one. Eleven sets ship.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanzo/design",
-  "version": "0.5.17",
+  "version": "0.5.19",
   "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",
@@ -30,8 +30,7 @@
     "./prompts/*": "./prompts/*",
     "./content/*": "./content/*",
     "./assets/*": "./assets/*",
-    "./skills/*": "./skills/*",
-    "./tailwind.css": "./tailwind.css"
+    "./skills/*": "./skills/*"
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",

package/prompts/studio-designer.md

@@ -11,8 +11,15 @@ You are the **Hanzo Design System designer**, an agent operating on the
 system as real files, using your file tools (read, write, edit, tree).
 
 ## The canon (never contradict)
-- **Typography:** Basel Grotesk (`sans`, weights 400 Book / 500 Medium, self-hosted
-  woff2) + Geist Mono (`mono`). No Inter/Roboto/DM Sans as defaults.
+- **Typography:** Zen (`sans`) and Zen Mono (`mono`), both variable on `wght`
+  100–900, plus Zen Pixel for display accents. ONE family, ours, no licensed
+  third-party face and no Inter/Roboto/DM Sans. An app imports
+  `@hanzo/design/styles.css` and gets the faces with it — never hand-write an
+  `@font-face` and never reach for a font CDN. Name the role (`var(--font-sans)`),
+  never the face. Brand voice comes from a preset in `@hanzo/font/presets.css`
+  (`.zen-air` `.zen-book` `.zen-medium` `.zen-wide` `.zen-round`) or from Zen's own
+  stylistic sets (`ss01` single-storey a, `ss04` straight-leg R), never from a
+  second family.
 - **Palette:** true-black OLED. Page `#000`, surface `#0a0a0a`, press `#050505`,
   elevated `#171717`, border `rgba(255,255,255,.10)`, text `#ededf1`. **Monochrome —
   no colored accents.** Semantic color only for live/error/warning.

package/scripts/check-tokens.mjs

@@ -60,7 +60,6 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
 }
 
 // ── 1a. the bundles must PARSE ───────────────────────────────────────────
-// 0.4.2 and 0.4.3 shipped a stray `*/` in styles.css AND tailwind.css: an
 // edit added prose to the end of a comment that was already closed, so a
 // paragraph of English sat in the stylesheet as raw CSS, terminated by a
 // second `*/`. Browsers recover from that — they skip to the next thing that
@@ -78,7 +77,7 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
 // that skips comment bodies finds every stray terminator and every unclosed
 // opener. A parser dependency would be a heavier answer to a smaller question.
 {
-  for (const f of ['styles.css', 'tailwind.css']) {
+  for (const f of ['styles.css']) {
     const s = read(join(root, f))
     let i = 0, opened = 0, strays = [], unterminated = null
     while (i < s.length - 1) {
@@ -100,31 +99,11 @@ const pass = (msg) => console.log(`  ok    ${msg}`)
   }
 }
 
-// ── 1b. the Tailwind bridge is complete and self-contained ───────────────
-// An app should write ONE import and get working utilities. Each thing checked
-// here failed silently in production before it was checked: a missing slot
-// makes that utility resolve to nothing (`border-border` -> currentColor -> a
-// white hairline on black), and a surviving @import makes the browser drop
-// every token without a word.
-{
-  const tw = strip(read(join(root, 'tailwind.css')))
-  tw.includes('@import')
-    ? fail('tailwind.css contains an @import — invalid after `@import "tailwindcss"`, so the tokens are dropped')
-    : pass('tailwind.css has no @import to invalidate')
-
-  // Every Tailwind colour slot an app will reach for must be mapped.
-  const slots = ['background', 'foreground', 'card', 'popover', 'primary', 'secondary',
-                 'muted', 'muted-foreground', 'accent', 'destructive', 'border', 'input', 'ring']
-  const unmapped = slots.filter((s) => !tw.includes(`--color-${s}:`))
-  unmapped.length
-    ? fail(`tailwind.css does not map: ${unmapped.join(', ')}`)
-    : pass(`tailwind.css maps all ${slots.length} core colour slots`)
-
-  // And it must carry the values, not merely reference them.
-  tw.includes('--border:')
-    ? pass('tailwind.css carries the token values inline')
-    : fail('tailwind.css maps slots but carries no tokens — every utility resolves to nothing')
-}
+// 1b was the Tailwind bridge — a generated `tailwind.css` mapping every token
+// onto a `--color-*` utility slot. Gone with the utility layer it existed to
+// feed: this system's one substrate is @hanzo/gui, which reads the tokens
+// directly, so a second sheet republishing them as utilities was the "one fact,
+// two homes" shape the `second-publisher` lint rule exists to catch.
 
 // ── 1c. element defaults must LOSE to an app's utilities ─────────────────
 // A rule outside a cascade layer beats a rule inside one regardless of

package/scripts/gen-tokens.mjs

@@ -185,81 +185,3 @@ const bundle = banner + FILES.map((f) => {
 writeFileSync(join(root, 'styles.css'), bundle)
 console.log(`gen-tokens: wrote styles.css — ${FILES.length} token groups, flattened`)
 
-// ── tailwind.css — the ONE line a Tailwind app writes ────────────────────
-// Every app that consumed these tokens still had to hand-write the bridge from
-// our variable names to Tailwind's utility namespace:
-//
-//   @theme inline { --color-background: var(--background); ...twenty more }
-//
-// Twenty lines of boilerplate, copied into each new app, is a drift vector with
-// a silent failure mode: miss one and that utility resolves to nothing —
-// `border-border` becomes currentColor and paints a white hairline on black,
-// which reads as a design choice rather than a missing line. Tabs shipped with
-// three of these and used forty-one.
-//
-// So the bridge is generated here from SLOTS, and an app writes one import
-// after `@import "tailwindcss"`. There is nothing left to get wrong, and adding
-// a semantic token wires it up for every app at once.
-const SLOTS = [
-  'background', 'foreground',
-  'card', 'card-foreground',
-  'popover', 'popover-foreground',
-  'primary', 'primary-foreground',
-  'secondary', 'secondary-foreground',
-  'muted', 'muted-foreground',
-  'accent', 'accent-foreground',
-  'destructive', 'destructive-foreground',
-  'border', 'input', 'ring',
-]
-// State colours are their own vocabulary and keep their names, so `text-error`
-// and `bg-online` mean what they say instead of borrowing a neutral slot.
-const STATE = { error: 'state-error', success: 'state-success', online: 'state-online' }
-
-const declared = new Set(flat.map(([n]) => n.replace(/^--/, '')))
-const missing = SLOTS.filter((s) => !declared.has(s))
-if (missing.length) {
-  console.error(`gen-tokens: tokens/colors.css declares no --${missing.join(', --')}`)
-  process.exit(1)
-}
-
-const tw = `/* Hanzo Design System — Tailwind v4 bridge. The ONE import a Tailwind app adds.
- *
- * AUTO-GENERATED by scripts/gen-tokens.mjs — DO NOT EDIT.
- *
- *   @import "tailwindcss";
- *   @import "@hanzo/design/tailwind.css";
- *
- * It carries the tokens AND maps them onto Tailwind's utility namespace, so
- * \`bg-background\`, \`text-muted-foreground\` and \`border-border\` resolve to the
- * system's values with nothing to wire up by hand.
- *
- * Import it AFTER tailwindcss: @theme has to come after the framework it
- * extends, and the element defaults are layered so your utilities still win.
- *
- * "inline" is deliberate — it compiles \`border-border\` to var(--border) rather
- * than to that variable's build-time value, so switching .light at runtime moves
- * the UI and not merely the variables.
- *
- * The tokens are inlined below rather than @imported for the reason styles.css
- * is flattened: an @import must precede every other rule, so importing this
- * after tailwindcss would invalidate it and the browser would drop the whole
- * token layer without a word.
- */
-${bundle}
-
-@theme inline {
-${SLOTS.map((s) => `  --color-${s}: var(--${s});`).join('\n')}
-
-${Object.entries(STATE).map(([k, v]) => `  --color-${k}: var(--${v});`).join('\n')}
-
-  --radius-sm: var(--radius-sm);
-  --radius-md: var(--radius-md);
-  --radius-lg: var(--radius-lg);
-  --radius-xl: var(--radius-xl);
-
-  --font-sans: var(--font-sans);
-  --font-mono: var(--font-mono);
-}
-`
-writeFileSync(join(root, 'tailwind.css'), tw)
-console.log(`gen-tokens: wrote tailwind.css — ${SLOTS.length} colour slots + ${Object.keys(STATE).length} states`)

package/src/tokens.gen.ts

@@ -309,9 +309,9 @@ export const zIndex = {
 
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export const fonts = {
-  'font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+  'font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
   'font-display': 'var(--font-sans)',
-  'font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+  'font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
   'font-serif': 'Georgia,serif',
   'font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
 } as const
@@ -596,9 +596,9 @@ export const cssVars = {
   '--z-toast': '800',
   '--z-tooltip': 'var(--z-popover)',
   '--z-notification': 'var(--z-toast)',
-  '--font-sans': '"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif',
+  '--font-sans': '"Zen",ui-sans-serif,system-ui,sans-serif',
   '--font-display': 'var(--font-sans)',
-  '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',
+  '--font-mono': '"Zen Mono",ui-monospace,SFMono-Regular,monospace',
   '--font-serif': 'Georgia,serif',
   '--font-feature-settings': '"ss01","ss02","cv01","cv02","cv03"',
   '--ring-offset': '-2px',

package/styles.css

@@ -838,44 +838,67 @@
 }
 
 /* ── tokens/fonts.css ─────────────────────────────────────── */
-/* Geist Sans + Geist Mono — the only two faces on Hanzo surfaces.
+/* Zen — the only family on Hanzo surfaces, sans and mono.
    SELF-HOSTED. The faces ship inside this package (assets/fonts/*.woff2, two
-   variable files, 141 KB total, SIL OFL-1.1 — see assets/fonts/LICENSE-Geist.txt).
-
-   Why self-hosted rather than @import from fonts.googleapis.com:
+   variable files, 141 KB total, SIL OFL-1.1 — see assets/fonts/LICENSE-Zen.txt).
+
+   Zen is our own family, under the SIL Open Font License. The licence file
+   beside the binaries carries every copyright the OFL requires; nothing else in
+   this repository restates them, which is the whole of what §2 asks for.
+
+   SHIPPED here rather than @import-ed from `@hanzo/font`, and that is load
+   bearing. `@hanzo/ui` composes this file into the MIDDLE of its theme.css, and
+   CSS drops an @import that does not precede every other rule — measured, in
+   Chromium, on the built sheet: zero faces loaded and not one woff2 requested.
+   An @font-face has no such ordering rule, so declaring the faces is the only
+   form that survives being flattened into a larger stylesheet. `@hanzo/font`
+   remains the one place the faces are AUTHORED; this is a copy of its output,
+   the same way the colour tokens are copied rather than fetched.
+
+   Why self-hosted rather than a third-party CDN:
    - A sign-in page must not make a third-party request. hanzoai/id refused to
      import this file for exactly that reason, which split the token layer: id
      took the colours and not the typeface. Self-hosting removes the reason, so
      every surface can import styles.css unchanged.
-   - The @import was a render-blocking request to a host we do not control, on
-     the critical path of every surface, and it broke offline/air-gapped dev.
+   - It was a render-blocking request to a host we do not control, on the
+     critical path of every surface, and it broke offline/air-gapped dev.
    - One variable file per family replaces nine static weights, and it is fewer
-     bytes than the CSS-then-woff2 round trip Google served.
+     bytes than the CSS-then-woff2 round trip.
 
    The url()s are relative to THIS file, so they resolve wherever the package is
-   mounted — node_modules, a CDN, a copied dist — with no configuration. */
+   mounted — node_modules, a CDN, a copied dist — with no configuration.
+
+   `font-display: block`, NOT swap, and the difference is the whole brand. `swap`
+   paints the fallback IMMEDIATELY and repaints when the face lands, so every first
+   visit shows the platform's own sans for as long as the download takes — on Ubuntu
+   that is DejaVu, which looks nothing like us and is the single most common way a
+   Hanzo surface renders wrong. `block` holds the text invisible for a short period
+   (~3s) and then paints Zen, so the fallback is only ever reached when the face
+   genuinely fails to arrive. A held word is a moment; the wrong typeface is the
+   brand. The generic tail below stays for exactly that real-failure case. */
 
 @font-face{
-  font-family:"Geist";
-  src:url("./assets/fonts/Geist-Variable.woff2") format("woff2");
+  font-family:"Zen";
+  src:url("./assets/fonts/Zen-Variable.woff2") format("woff2");
   font-weight:100 900;
   font-style:normal;
-  font-display:swap;
+  font-display:block;
 }
 @font-face{
-  font-family:"Geist Mono";
-  src:url("./assets/fonts/GeistMono-Variable.woff2") format("woff2");
+  font-family:"Zen Mono";
+  src:url("./assets/fonts/ZenMono-Variable.woff2") format("woff2");
   font-weight:100 900;
   font-style:normal;
-  font-display:swap;
+  font-display:block;
 }
 
 :root{
-  --font-sans:"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif;
+  --font-sans:"Zen",ui-sans-serif,system-ui,sans-serif;
   --font-display:var(--font-sans);
-  --font-mono:"Geist Mono",ui-monospace,SFMono-Regular,monospace;
+  --font-mono:"Zen Mono",ui-monospace,SFMono-Regular,monospace;
   --font-serif:Georgia,serif;
-  /* hanzo.ai sets these OpenType features on <body>. */
+  /* hanzo.ai sets these OpenType features on <body>. ss01 is Zen's
+     single-storey a — the neo-grotesque letterform. */
   --font-feature-settings:"ss01","ss02","cv01","cv02","cv03";
 }
 

package/tokens/fonts.css

@@ -1,40 +1,63 @@
-/* Geist Sans + Geist Mono — the only two faces on Hanzo surfaces.
+/* Zen — the only family on Hanzo surfaces, sans and mono.
    SELF-HOSTED. The faces ship inside this package (assets/fonts/*.woff2, two
-   variable files, 141 KB total, SIL OFL-1.1 — see assets/fonts/LICENSE-Geist.txt).
+   variable files, 141 KB total, SIL OFL-1.1 — see assets/fonts/LICENSE-Zen.txt).
 
-   Why self-hosted rather than @import from fonts.googleapis.com:
+   Zen is our own family, under the SIL Open Font License. The licence file
+   beside the binaries carries every copyright the OFL requires; nothing else in
+   this repository restates them, which is the whole of what §2 asks for.
+
+   SHIPPED here rather than @import-ed from `@hanzo/font`, and that is load
+   bearing. `@hanzo/ui` composes this file into the MIDDLE of its theme.css, and
+   CSS drops an @import that does not precede every other rule — measured, in
+   Chromium, on the built sheet: zero faces loaded and not one woff2 requested.
+   An @font-face has no such ordering rule, so declaring the faces is the only
+   form that survives being flattened into a larger stylesheet. `@hanzo/font`
+   remains the one place the faces are AUTHORED; this is a copy of its output,
+   the same way the colour tokens are copied rather than fetched.
+
+   Why self-hosted rather than a third-party CDN:
    - A sign-in page must not make a third-party request. hanzoai/id refused to
      import this file for exactly that reason, which split the token layer: id
      took the colours and not the typeface. Self-hosting removes the reason, so
      every surface can import styles.css unchanged.
-   - The @import was a render-blocking request to a host we do not control, on
-     the critical path of every surface, and it broke offline/air-gapped dev.
+   - It was a render-blocking request to a host we do not control, on the
+     critical path of every surface, and it broke offline/air-gapped dev.
    - One variable file per family replaces nine static weights, and it is fewer
-     bytes than the CSS-then-woff2 round trip Google served.
+     bytes than the CSS-then-woff2 round trip.
 
    The url()s are relative to THIS file, so they resolve wherever the package is
-   mounted — node_modules, a CDN, a copied dist — with no configuration. */
+   mounted — node_modules, a CDN, a copied dist — with no configuration.
+
+   `font-display: block`, NOT swap, and the difference is the whole brand. `swap`
+   paints the fallback IMMEDIATELY and repaints when the face lands, so every first
+   visit shows the platform's own sans for as long as the download takes — on Ubuntu
+   that is DejaVu, which looks nothing like us and is the single most common way a
+   Hanzo surface renders wrong. `block` holds the text invisible for a short period
+   (~3s) and then paints Zen, so the fallback is only ever reached when the face
+   genuinely fails to arrive. A held word is a moment; the wrong typeface is the
+   brand. The generic tail below stays for exactly that real-failure case. */
 
 @font-face{
-  font-family:"Geist";
-  src:url("../assets/fonts/Geist-Variable.woff2") format("woff2");
+  font-family:"Zen";
+  src:url("../assets/fonts/Zen-Variable.woff2") format("woff2");
   font-weight:100 900;
   font-style:normal;
-  font-display:swap;
+  font-display:block;
 }
 @font-face{
-  font-family:"Geist Mono";
-  src:url("../assets/fonts/GeistMono-Variable.woff2") format("woff2");
+  font-family:"Zen Mono";
+  src:url("../assets/fonts/ZenMono-Variable.woff2") format("woff2");
   font-weight:100 900;
   font-style:normal;
-  font-display:swap;
+  font-display:block;
 }
 
 :root{
-  --font-sans:"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif;
+  --font-sans:"Zen",ui-sans-serif,system-ui,sans-serif;
   --font-display:var(--font-sans);
-  --font-mono:"Geist Mono",ui-monospace,SFMono-Regular,monospace;
+  --font-mono:"Zen Mono",ui-monospace,SFMono-Regular,monospace;
   --font-serif:Georgia,serif;
-  /* hanzo.ai sets these OpenType features on <body>. */
+  /* hanzo.ai sets these OpenType features on <body>. ss01 is Zen's
+     single-storey a — the neo-grotesque letterform. */
   --font-feature-settings:"ss01","ss02","cv01","cv02","cv03";
 }