@hanzo/design 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,28 @@
-MIT License
+BSD 3-Clause License
 
 Copyright (c) 2026 Hanzo AI, Inc.
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -12,12 +12,17 @@ The single source of truth for how every Hanzo surface looks — tokens, compone
 
 ## Use it
 
-One import pulls in the whole token layer (fonts, color, type, spacing, radius, elevation, motion):
+One import pulls in the whole token layer — fonts, colour, type, spacing, radius,
+elevation, motion, **z**, base:
 
 ```css
 @import "@hanzo/design/styles.css";
 ```
 
+Import the **whole** file. Cherry-picking `tokens/*.css` is how surfaces ended up
+without the z ladder or the elevation ramp. The fonts are self-hosted, so this
+makes **no third-party request** — there is no longer a reason to skip a part of it.
+
 ### Programmatic tokens (control look & feel from code)
 
 The same tokens are exposed to TypeScript — **generated from the CSS**, so the two
@@ -61,13 +66,42 @@ import { HanzoLogo } from "@hanzoai/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/` | 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. |
 
+## Two kinds of boundary
+
+Not interchangeable, and the difference is a conformance requirement rather than
+a matter of taste:
+
+| Token | Kind | Contrast |
+|---|---|---|
+| `--border`, `--border-hairline`, `--border-card` | **decorative** — separates content | none required |
+| `--border-strong` | **perceivable** — identifies a *control* (input edge, switch, checkbox) | ≥ 3:1, WCAG 1.4.11 |
+| `--ring` | the focus indicator | ≥ 3:1, WCAG 2.4.11 |
+
+Reach for `--border-strong` whenever the boundary **is** the affordance. Both
+conformant tokens resolve to `--neutral-500`, the only rung on this ladder that
+clears 3:1 on every surface in **both** themes — `scripts/check-tokens.mjs`
+measures this on every build and fails if it ever stops being true.
+
+Note that the `--white-*` opacity ladder does **not** invert in light theme, so
+`--white-40` is white-on-white there. Anything needing a visible edge in both
+themes must use `--border-strong`.
+
 ## Principles
 
 - **Monochrome by construction** — one neutral ladder plus an opacity ladder is the entire palette. Color appears only as genuine semantics (live/error/warning).
 - **Dark is the default theme** — surfaces mount dark-first; light is the override.
+- **A token that is referenced must resolve** — an undefined custom property paints
+  *nothing*, silently. `cssVar()` therefore accepts only real token names (a typo
+  is a compile error) and emits the authored literal as a fallback, so a reference
+  still paints on a host that has not loaded the CSS.
+- **White-label by fork** — `@luxfi/design` and `@zooai/design` carry the same token
+  *names* over their own values. A change here must be measured against all three
+  before it ships; one that fixes Hanzo and breaks Zoo is a regression.
 - **Self-contained components** — inline styles, no CSS-framework coupling, so a component drops into any host (Next, Vite, Tamagui, none) and renders identically.
 - **Every component ships its own `.prompt.md`** — a one-screen usage guide for humans and AI alike.
 
@@ -77,4 +111,4 @@ Tokens track `hanzo.ai` (`app/globals.css`, `tailwind.config.ts`, `DESIGN.md`) a
 
 ## License
 
-MIT. Brand marks (the Hanzo logo, partner and provider logos) are the property of their respective owners and are provided for identification.
+BSD-3-Clause. Brand marks (the Hanzo logo, partner and provider logos) are the property of their respective owners and are provided for identification.

package/assets/fonts/LICENSE-Geist.txt

@@ -0,0 +1,92 @@
+Copyright (c) 2023 Vercel, in collaboration with basement.studio
+
+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:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION AND CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/index.d.ts

@@ -1,14 +1,25 @@
 export * from './tokens.gen.js';
 import { type CssVarName } from './tokens.gen.js';
+/** A token name with the leading `--` omitted: `'background'` for `'--background'`. */
+export type TokenName = CssVarName extends `--${infer N}` ? N : never;
 /**
- * A `var(--name[, fallback])` 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) rather than baking a fixed value.
+ * 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)"
- *   color:      cssVar('--foreground', '#fff')
+ *   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.
  */
-export declare function cssVar(name: CssVarName | (string & {}), fallback?: string): string;
+export declare function cssVar(name: CssVarName | TokenName, fallback?: string): string;
 /** The raw authored value of a token (the literal from the CSS), or `undefined`. */
 export declare function tokenValue(name: CssVarName): string | undefined;
 /**
@@ -16,6 +27,10 @@ export declare function tokenValue(name: CssVarName): string | undefined;
  * 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.
  */
-export declare function injectDesignCss(href?: string): void;
+export declare function injectDesignCss(href: string): void;
 //# 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;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED,oFAAoF;AACpF,wBAAgB,UAAU,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,SAA4C,GAAG,IAAI,CAQtF"}
+{"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"}

package/dist/index.js

@@ -12,16 +12,26 @@
 export * from './tokens.gen.js';
 import { cssVars } from './tokens.gen.js';
 /**
- * A `var(--name[, fallback])` 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) rather than baking a fixed value.
+ * 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)"
- *   color:      cssVar('--foreground', '#fff')
+ *   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.
  */
 export function cssVar(name, fallback) {
-    const n = name.startsWith('--') ? name : `--${name}`;
-    return fallback ? `var(${n}, ${fallback})` : `var(${n})`;
+    const n = (name.startsWith('--') ? name : `--${name}`);
+    const lit = fallback ?? cssVars[n];
+    return lit ? `var(${n}, ${lit})` : `var(${n})`;
 }
 /** The raw authored value of a token (the literal from the CSS), or `undefined`. */
 export function tokenValue(name) {
@@ -32,8 +42,12 @@ export function tokenValue(name) {
  * 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.
  */
-export function injectDesignCss(href = 'https://esm.sh/@hanzo/design/styles.css') {
+export function injectDesignCss(href) {
     if (typeof document === 'undefined')
         return;
     if (document.querySelector('link[data-hanzo-design]'))

package/dist/tokens.gen.d.ts

@@ -41,7 +41,7 @@ export declare const colors: {
     readonly 'destructive-foreground': "#f5f5f5";
     readonly border: "#1f1f1f";
     readonly input: "#1f1f1f";
-    readonly ring: "#333333";
+    readonly ring: "var(--neutral-500)";
     readonly brand: "#e4e4e7";
     readonly 'brand-foreground': "#09090b";
     readonly 'brand-muted': "#a3a3a3";
@@ -55,7 +55,11 @@ export declare const colors: {
     readonly 'surface-header': "rgb(0 0 0 / .7)";
     readonly 'border-hairline': "var(--neutral-800)";
     readonly 'border-card': "var(--white-10)";
-    readonly 'border-strong': "var(--neutral-700)";
+    readonly 'border-strong': "var(--neutral-500)";
+    readonly 'surface-0': "var(--background)";
+    readonly 'surface-1': "var(--card)";
+    readonly 'surface-2': "var(--muted)";
+    readonly 'surface-3': "var(--secondary)";
     readonly 'text-primary': "var(--pure-white)";
     readonly 'text-secondary': "var(--white-80)";
     readonly 'text-tertiary': "var(--white-60)";
@@ -94,6 +98,23 @@ export declare const typography: {
     readonly 'leading-6xl': "1";
     readonly 'text-7xl': "4rem";
     readonly 'leading-7xl': "1";
+    readonly 'text-8xl': "5.25rem";
+    readonly 'leading-8xl': "1";
+    readonly 'text-9xl': "7rem";
+    readonly 'leading-9xl': "1";
+    readonly 'font-size-xs': "var(--text-xs)";
+    readonly 'font-size-sm': "var(--text-sm)";
+    readonly 'font-size-base': "var(--text-base)";
+    readonly 'font-size-lg': "var(--text-lg)";
+    readonly 'font-size-xl': "var(--text-xl)";
+    readonly 'font-size-2xl': "var(--text-2xl)";
+    readonly 'font-size-3xl': "var(--text-3xl)";
+    readonly 'font-size-4xl': "var(--text-4xl)";
+    readonly 'font-size-5xl': "var(--text-5xl)";
+    readonly 'font-size-6xl': "var(--text-6xl)";
+    readonly 'font-size-7xl': "var(--text-7xl)";
+    readonly 'font-size-8xl': "var(--text-8xl)";
+    readonly 'font-size-9xl': "var(--text-9xl)";
     readonly 'weight-normal': "400";
     readonly 'weight-medium': "500";
     readonly 'weight-semibold': "600";
@@ -173,6 +194,12 @@ export declare const elevation: {
     readonly 'shadow-floating': "0 25px 50px -12px rgb(0 0 0 / .25)";
     readonly 'shadow-inset-hairline': "inset 0 0 0 1px var(--white-10)";
     readonly 'ring-focus': "0 0 0 2px var(--ring)";
+    readonly 'shadow-sm': "0 1px 2px 0 rgb(0 0 0 / .40)";
+    readonly shadow: "0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)";
+    readonly 'shadow-md': "0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)";
+    readonly 'shadow-lg': "0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)";
+    readonly 'shadow-xl': "0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)";
+    readonly 'shadow-2xl': "var(--shadow-floating)";
     readonly 'glow-hero': "radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)";
     readonly 'glow-hero-blur': "120px";
     readonly 'sheen-card': "radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)";
@@ -204,6 +231,8 @@ export declare const zIndex: {
     readonly 'z-modal': "600";
     readonly 'z-popover': "700";
     readonly 'z-toast': "800";
+    readonly 'z-tooltip': "var(--z-popover)";
+    readonly 'z-notification': "var(--z-toast)";
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export declare const fonts: {
@@ -258,7 +287,7 @@ export declare const cssVars: {
     readonly '--destructive-foreground': "#f5f5f5";
     readonly '--border': "#1f1f1f";
     readonly '--input': "#1f1f1f";
-    readonly '--ring': "#333333";
+    readonly '--ring': "var(--neutral-500)";
     readonly '--brand': "#e4e4e7";
     readonly '--brand-foreground': "#09090b";
     readonly '--brand-muted': "#a3a3a3";
@@ -272,7 +301,11 @@ export declare const cssVars: {
     readonly '--surface-header': "rgb(0 0 0 / .7)";
     readonly '--border-hairline': "var(--neutral-800)";
     readonly '--border-card': "var(--white-10)";
-    readonly '--border-strong': "var(--neutral-700)";
+    readonly '--border-strong': "var(--neutral-500)";
+    readonly '--surface-0': "var(--background)";
+    readonly '--surface-1': "var(--card)";
+    readonly '--surface-2': "var(--muted)";
+    readonly '--surface-3': "var(--secondary)";
     readonly '--text-primary': "var(--pure-white)";
     readonly '--text-secondary': "var(--white-80)";
     readonly '--text-tertiary': "var(--white-60)";
@@ -308,6 +341,23 @@ export declare const cssVars: {
     readonly '--leading-6xl': "1";
     readonly '--text-7xl': "4rem";
     readonly '--leading-7xl': "1";
+    readonly '--text-8xl': "5.25rem";
+    readonly '--leading-8xl': "1";
+    readonly '--text-9xl': "7rem";
+    readonly '--leading-9xl': "1";
+    readonly '--font-size-xs': "var(--text-xs)";
+    readonly '--font-size-sm': "var(--text-sm)";
+    readonly '--font-size-base': "var(--text-base)";
+    readonly '--font-size-lg': "var(--text-lg)";
+    readonly '--font-size-xl': "var(--text-xl)";
+    readonly '--font-size-2xl': "var(--text-2xl)";
+    readonly '--font-size-3xl': "var(--text-3xl)";
+    readonly '--font-size-4xl': "var(--text-4xl)";
+    readonly '--font-size-5xl': "var(--text-5xl)";
+    readonly '--font-size-6xl': "var(--text-6xl)";
+    readonly '--font-size-7xl': "var(--text-7xl)";
+    readonly '--font-size-8xl': "var(--text-8xl)";
+    readonly '--font-size-9xl': "var(--text-9xl)";
     readonly '--weight-normal': "400";
     readonly '--weight-medium': "500";
     readonly '--weight-semibold': "600";
@@ -378,6 +428,12 @@ export declare const cssVars: {
     readonly '--shadow-floating': "0 25px 50px -12px rgb(0 0 0 / .25)";
     readonly '--shadow-inset-hairline': "inset 0 0 0 1px var(--white-10)";
     readonly '--ring-focus': "0 0 0 2px var(--ring)";
+    readonly '--shadow-sm': "0 1px 2px 0 rgb(0 0 0 / .40)";
+    readonly '--shadow': "0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)";
+    readonly '--shadow-md': "0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)";
+    readonly '--shadow-lg': "0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)";
+    readonly '--shadow-xl': "0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)";
+    readonly '--shadow-2xl': "var(--shadow-floating)";
     readonly '--glow-hero': "radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)";
     readonly '--glow-hero-blur': "120px";
     readonly '--sheen-card': "radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)";
@@ -403,6 +459,8 @@ export declare const cssVars: {
     readonly '--z-modal': "600";
     readonly '--z-popover': "700";
     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-display': "var(--font-sans)";
     readonly '--font-mono': "\"Geist Mono\",ui-monospace,SFMono-Regular,monospace";

package/dist/tokens.gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsET,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6Cb,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCV,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;CAWZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;CAUT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgMV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}
+{"version":3,"file":"tokens.gen.d.ts","sourceRoot":"","sources":["../src/tokens.gen.ts"],"names":[],"mappings":"AAIA,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0ET,CAAA;AAEV,0EAA0E;AAC1E,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8Db,CAAA;AAEV,oEAAoE;AACpE,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqCV,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;CAST,CAAA;AAEV,wEAAwE;AACxE,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;CAiBZ,CAAA;AAEV,kEAAkE;AAClE,eAAO,MAAM,MAAM;;;;;;;;;;;CAWT,CAAA;AAEV,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;;;;;;;;;;;CAYT,CAAA;AAEV,gEAAgE;AAChE,eAAO,MAAM,KAAK;;;;;;CAMR,CAAA;AAEV,8DAA8D;AAC9D,eAAO,MAAM,IAAI,IAEP,CAAA;AAEV,sFAAsF;AACtF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6NV,CAAA;AAEV,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,OAAO,CAAA"}

package/dist/tokens.gen.js

@@ -44,7 +44,7 @@ export const colors = {
     'destructive-foreground': '#f5f5f5',
     'border': '#1f1f1f',
     'input': '#1f1f1f',
-    'ring': '#333333',
+    'ring': 'var(--neutral-500)',
     'brand': '#e4e4e7',
     'brand-foreground': '#09090b',
     'brand-muted': '#a3a3a3',
@@ -58,7 +58,11 @@ export const colors = {
     'surface-header': 'rgb(0 0 0 / .7)',
     'border-hairline': 'var(--neutral-800)',
     'border-card': 'var(--white-10)',
-    'border-strong': 'var(--neutral-700)',
+    'border-strong': 'var(--neutral-500)',
+    'surface-0': 'var(--background)',
+    'surface-1': 'var(--card)',
+    'surface-2': 'var(--muted)',
+    'surface-3': 'var(--secondary)',
     'text-primary': 'var(--pure-white)',
     'text-secondary': 'var(--white-80)',
     'text-tertiary': 'var(--white-60)',
@@ -97,6 +101,23 @@ export const typography = {
     'leading-6xl': '1',
     'text-7xl': '4rem',
     'leading-7xl': '1',
+    'text-8xl': '5.25rem',
+    'leading-8xl': '1',
+    'text-9xl': '7rem',
+    'leading-9xl': '1',
+    'font-size-xs': 'var(--text-xs)',
+    'font-size-sm': 'var(--text-sm)',
+    'font-size-base': 'var(--text-base)',
+    'font-size-lg': 'var(--text-lg)',
+    'font-size-xl': 'var(--text-xl)',
+    'font-size-2xl': 'var(--text-2xl)',
+    'font-size-3xl': 'var(--text-3xl)',
+    'font-size-4xl': 'var(--text-4xl)',
+    'font-size-5xl': 'var(--text-5xl)',
+    'font-size-6xl': 'var(--text-6xl)',
+    'font-size-7xl': 'var(--text-7xl)',
+    'font-size-8xl': 'var(--text-8xl)',
+    'font-size-9xl': 'var(--text-9xl)',
     'weight-normal': '400',
     'weight-medium': '500',
     'weight-semibold': '600',
@@ -176,6 +197,12 @@ export const elevation = {
     'shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
     'shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
     'ring-focus': '0 0 0 2px var(--ring)',
+    'shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+    'shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+    'shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+    'shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+    'shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+    'shadow-2xl': 'var(--shadow-floating)',
     'glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     'glow-hero-blur': '120px',
     'sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -207,6 +234,8 @@ export const zIndex = {
     'z-modal': '600',
     'z-popover': '700',
     'z-toast': '800',
+    'z-tooltip': 'var(--z-popover)',
+    'z-notification': 'var(--z-toast)',
 };
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
 export const fonts = {
@@ -261,7 +290,7 @@ export const cssVars = {
     '--destructive-foreground': '#f5f5f5',
     '--border': '#1f1f1f',
     '--input': '#1f1f1f',
-    '--ring': '#333333',
+    '--ring': 'var(--neutral-500)',
     '--brand': '#e4e4e7',
     '--brand-foreground': '#09090b',
     '--brand-muted': '#a3a3a3',
@@ -275,7 +304,11 @@ export const cssVars = {
     '--surface-header': 'rgb(0 0 0 / .7)',
     '--border-hairline': 'var(--neutral-800)',
     '--border-card': 'var(--white-10)',
-    '--border-strong': 'var(--neutral-700)',
+    '--border-strong': 'var(--neutral-500)',
+    '--surface-0': 'var(--background)',
+    '--surface-1': 'var(--card)',
+    '--surface-2': 'var(--muted)',
+    '--surface-3': 'var(--secondary)',
     '--text-primary': 'var(--pure-white)',
     '--text-secondary': 'var(--white-80)',
     '--text-tertiary': 'var(--white-60)',
@@ -311,6 +344,23 @@ export const cssVars = {
     '--leading-6xl': '1',
     '--text-7xl': '4rem',
     '--leading-7xl': '1',
+    '--text-8xl': '5.25rem',
+    '--leading-8xl': '1',
+    '--text-9xl': '7rem',
+    '--leading-9xl': '1',
+    '--font-size-xs': 'var(--text-xs)',
+    '--font-size-sm': 'var(--text-sm)',
+    '--font-size-base': 'var(--text-base)',
+    '--font-size-lg': 'var(--text-lg)',
+    '--font-size-xl': 'var(--text-xl)',
+    '--font-size-2xl': 'var(--text-2xl)',
+    '--font-size-3xl': 'var(--text-3xl)',
+    '--font-size-4xl': 'var(--text-4xl)',
+    '--font-size-5xl': 'var(--text-5xl)',
+    '--font-size-6xl': 'var(--text-6xl)',
+    '--font-size-7xl': 'var(--text-7xl)',
+    '--font-size-8xl': 'var(--text-8xl)',
+    '--font-size-9xl': 'var(--text-9xl)',
     '--weight-normal': '400',
     '--weight-medium': '500',
     '--weight-semibold': '600',
@@ -381,6 +431,12 @@ export const cssVars = {
     '--shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
     '--shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
     '--ring-focus': '0 0 0 2px var(--ring)',
+    '--shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+    '--shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+    '--shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+    '--shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+    '--shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+    '--shadow-2xl': 'var(--shadow-floating)',
     '--glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
     '--glow-hero-blur': '120px',
     '--sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -406,6 +462,8 @@ export const cssVars = {
     '--z-modal': '600',
     '--z-popover': '700',
     '--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-display': 'var(--font-sans)',
     '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',

package/guidelines/DESIGN.md

@@ -0,0 +1,106 @@
+# Hanzo Design System — Canonical Tokens
+
+`@hanzo/ui` is the single source of truth for the shared Hanzo product look across
+the **Tailwind** apps (hanzo.chat, hanzo.app, hanzo console, commerce, hanzo-desktop).
+Change a value here; apps converge on it. This file is that source of truth for the
+three things that must read as **one product**: typography, the sidebar/panel system,
+and the dark-black palette.
+
+> One library: **`@hanzo/ui@8`** (`pkg/ui`, on **`@hanzo/gui`**) IS the component
+> library — the cross-platform product/record layer every surface consumes.
+> **`@hanzo/ui-shadcn`** (`pkgs/ui`) is the legacy shadcn/Tailwind/Radix kit, kept
+> only for existing v5 consumers (pin `@hanzo/ui-shadcn@^5`; no new adoptions).
+> This file stays the source of truth for the *token values* (fonts, dark palette,
+> the sidebar glyph) both render.
+
+---
+
+## 1. Typography — Basel Grotesk + Geist Mono
+
+| 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. |
+| Arabic / Hebrew (`--font-ar` / `--font-he`) | unchanged | i18n only — keep. |
+
+**Dropped as defaults:** Geist Sans, DM Sans, Figtree, Inter, PT Sans, Roboto Mono.
+
+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`):
+
+```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');
+}
+```
+
+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`.
+
+---
+
+## 2. Sidebar toggle icon — lucide `PanelLeft`
+
+One glyph everywhere: lucide **`PanelLeft`** (the shadcn `SidebarTrigger` default).
+Where a directional open/close affordance is wanted, use the pair
+**`PanelLeftClose`** (expanded) / **`PanelLeft`** (collapsed). Never a hamburger,
+a magnifier, a directional arrow, or a bespoke panel SVG for the sidebar toggle.
+
+- Icon: stroke-2, ~16–20px, `currentColor`.
+- Button: ghost/outline, square (`size-7`/`h-6 w-6`), subtle hover.
+
+---
+
+## 3. Sidebar + panels
+
+| Spec | Value |
+|------|-------|
+| Sidebar width (expanded) | **16rem / 256px** (`SIDEBAR_WIDTH`) |
+| Sidebar width (collapsed / icon rail) | **3rem / 48px** (apps vary 48–70px) |
+| Sidebar / panel surface | resting **#0a0a0a** over the true-black page |
+| Border / separation | `border-border` — subtle white-alpha ~10% in dark (`border-r` / `border-l`) |
+| Item hover | subtle `white/5` |
+| Item active | monochrome `white/10` — **no colored accent** (the house style is monochrome) |
+| Right panel rail | `border-l border-border`, same surface, collapsible |
+
+Prefer the `@hanzo/ui` `Sidebar` primitive (`pkgs/ui/primitives/sidebar.tsx`,
+`SidebarTrigger` → `PanelLeft`) where the app can consume it; otherwise match these
+classes/tokens.
+
+---
+
+## 4. Dark-black palette (true-black OLED)
+
+The house dark theme is a **true-black** canvas (matches hanzo.ai marketing +
+hanzo.chat OLED), with a shallow surface-depth ladder for cards/panels and quiet
+hairline borders — never harsh pure-white on pure-black.
+
+| Token | Value | Use |
+|-------|-------|-----|
+| Page background | **#000000** (`oklch(0 0 0)`) | body / canvas |
+| Surface / sidebar / panel (resting) | **#0a0a0a** | sidebars, panels, cards |
+| Press | **#050505** | pressed surface |
+| Elevated / hover | **#171717** | hover, raised card |
+| Border / divider | **rgba(255,255,255,0.10)** (≈ `#171717` opaque on black) | hairlines |
+| Foreground (primary text) | near-white **#ededf1** (`oklch(0.985)`) — not pure `#fff` | body text |
+| Muted / secondary text | `white/70` (≈ `#a1a1aa`) | secondary |
+
+Keep each app's theme-token engine (CSS vars / Tailwind tokens / Tamagui `$color*`);
+converge the **values/usage** to the table above, don't rip the engine.
+
+Reference: `pkgs/ui/style/hanzo-default-colors.css` (`.dark` / `.hanzo-ui-dark-theme`).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@hanzo/design",
-  "version": "0.2.0",
+  "version": "0.3.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",
+  "license": "BSD-3-Clause",
   "repository": {
     "type": "git",
     "url": "https://github.com/hanzoai/design.git"
@@ -29,7 +29,8 @@
   },
   "scripts": {
     "gen": "node scripts/gen-tokens.mjs",
-    "build": "npm run gen && tsc -p tsconfig.json",
+    "test": "node scripts/check-tokens.mjs",
+    "build": "npm run gen && npm test && tsc -p tsconfig.json",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {

package/prompts/README.md

@@ -24,3 +24,10 @@ Everything here assumes one import gives you the tokens:
 ```
 
 So every rule below can be obeyed with a CSS variable, never a hardcoded hex.
+
+## The two prompts (one and one way)
+- **`system.md`** — the design LANGUAGE prompt: paste as a system prompt to make any
+  model generate Hanzo-looking output (monochrome, true-black, token-only).
+- **`studio-designer.md`** — the AGENTIC prompt Hanzo Studio's Design System designer
+  hands the Hanzo agent stack to GENERATE/EDIT this repo's file tree with its file
+  tools, grounded in `guidelines/DESIGN.md`. Uses `system.md`'s language rules.

package/prompts/studio-designer.md

@@ -0,0 +1,41 @@
+# Hanzo Studio — Design System Designer (agentic prompt)
+
+The system prompt the Studio "Design System" designer hands to the Hanzo agent
+stack. The agent generates/edits the design-system file tree in **hanzoai/design**
+using its file tools (write/edit/tree), grounded in the canon.
+
+---
+
+You are the **Hanzo Design System designer**, an agent operating on the
+`hanzoai/design` repository. You produce and maintain a complete, coherent design
+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.
+- **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.
+- **Sidebar:** 256px expanded / 48px rail; lucide `PanelLeft` toggle; `white/5` hover,
+  `white/10` active.
+- Full source: `guidelines/DESIGN.md`.
+
+## Structure you own
+`tokens/` (base·colors·fonts·spacing·radius·elevation·motion.css + TS modules) ·
+`guidelines/` · `assets/{brand,logos,providers,fonts}` · `components/` · `ui_kits/`.
+
+## How you work
+1. **Read before writing.** `tree` the repo + read `guidelines/DESIGN.md` and the
+   relevant `tokens/*` so every new value stays consistent with what exists.
+2. **Tokens are the source.** A component reads token vars (`var(--hz-*)`), never a
+   hardcoded hex/px. If a needed token is missing, add it to `tokens/` first, then use it.
+3. **One and one way.** One place per value. Don't duplicate a color/space/font.
+4. **Generate real, coherent files** — a request like "add a Card component" writes
+   `components/card.{css,tsx,md}` referencing the tokens + a usage note, not a mock.
+5. **Honor the request scope.** "Generate a design system" → the full tree from the
+   canon. "Add elevation tokens" → just `tokens/elevation.css` + wire into `base.css`.
+6. **Never fabricate brand assets.** Reference real files in `assets/`; if a logo/font
+   is missing, note it as a TODO, don't invent bytes.
+7. **Explain what you wrote** (files + why) so the review is legible.
+
+Output: the files, written to the repo, plus a one-paragraph summary of the change.

package/src/index.ts

@@ -12,17 +12,30 @@
 export * from './tokens.gen.js'
 import { cssVars, type CssVarName } from './tokens.gen.js'
 
+/** A token name with the leading `--` omitted: `'background'` for `'--background'`. */
+export type TokenName = CssVarName extends `--${infer N}` ? N : never
+
 /**
- * A `var(--name[, fallback])` 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) rather than baking a fixed value.
+ * 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)"
  *
- *   background: cssVar('--background')      // → "var(--background)"
- *   color:      cssVar('--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.
  */
-export function cssVar(name: CssVarName | (string & {}), fallback?: string): string {
-  const n = name.startsWith('--') ? name : `--${name}`
-  return fallback ? `var(${n}, ${fallback})` : `var(${n})`
+export function cssVar(name: CssVarName | TokenName, fallback?: string): string {
+  const n = (name.startsWith('--') ? name : `--${name}`) as CssVarName
+  const lit = fallback ?? (cssVars as Record<string, string>)[n]
+  return lit ? `var(${n}, ${lit})` : `var(${n})`
 }
 
 /** The raw authored value of a token (the literal from the CSS), or `undefined`. */
@@ -35,8 +48,12 @@ export function tokenValue(name: CssVarName): string | undefined {
  * 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.
  */
-export function injectDesignCss(href = 'https://esm.sh/@hanzo/design/styles.css'): void {
+export function injectDesignCss(href: string): void {
   if (typeof document === 'undefined') return
   if (document.querySelector('link[data-hanzo-design]')) return
   const l = document.createElement('link')

package/src/tokens.gen.ts

@@ -45,7 +45,7 @@ export const colors = {
   'destructive-foreground': '#f5f5f5',
   'border': '#1f1f1f',
   'input': '#1f1f1f',
-  'ring': '#333333',
+  'ring': 'var(--neutral-500)',
   'brand': '#e4e4e7',
   'brand-foreground': '#09090b',
   'brand-muted': '#a3a3a3',
@@ -59,7 +59,11 @@ export const colors = {
   'surface-header': 'rgb(0 0 0 / .7)',
   'border-hairline': 'var(--neutral-800)',
   'border-card': 'var(--white-10)',
-  'border-strong': 'var(--neutral-700)',
+  'border-strong': 'var(--neutral-500)',
+  'surface-0': 'var(--background)',
+  'surface-1': 'var(--card)',
+  'surface-2': 'var(--muted)',
+  'surface-3': 'var(--secondary)',
   'text-primary': 'var(--pure-white)',
   'text-secondary': 'var(--white-80)',
   'text-tertiary': 'var(--white-60)',
@@ -99,6 +103,23 @@ export const typography = {
   'leading-6xl': '1',
   'text-7xl': '4rem',
   'leading-7xl': '1',
+  'text-8xl': '5.25rem',
+  'leading-8xl': '1',
+  'text-9xl': '7rem',
+  'leading-9xl': '1',
+  'font-size-xs': 'var(--text-xs)',
+  'font-size-sm': 'var(--text-sm)',
+  'font-size-base': 'var(--text-base)',
+  'font-size-lg': 'var(--text-lg)',
+  'font-size-xl': 'var(--text-xl)',
+  'font-size-2xl': 'var(--text-2xl)',
+  'font-size-3xl': 'var(--text-3xl)',
+  'font-size-4xl': 'var(--text-4xl)',
+  'font-size-5xl': 'var(--text-5xl)',
+  'font-size-6xl': 'var(--text-6xl)',
+  'font-size-7xl': 'var(--text-7xl)',
+  'font-size-8xl': 'var(--text-8xl)',
+  'font-size-9xl': 'var(--text-9xl)',
   'weight-normal': '400',
   'weight-medium': '500',
   'weight-semibold': '600',
@@ -181,6 +202,12 @@ export const elevation = {
   'shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
   'shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
   'ring-focus': '0 0 0 2px var(--ring)',
+  'shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+  'shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+  'shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+  'shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+  'shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+  'shadow-2xl': 'var(--shadow-floating)',
   'glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
   'glow-hero-blur': '120px',
   'sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -214,6 +241,8 @@ export const zIndex = {
   'z-modal': '600',
   'z-popover': '700',
   'z-toast': '800',
+  'z-tooltip': 'var(--z-popover)',
+  'z-notification': 'var(--z-toast)',
 } as const
 
 /** fonts tokens (from tokens/fonts.css). Values are raw CSS. */
@@ -273,7 +302,7 @@ export const cssVars = {
   '--destructive-foreground': '#f5f5f5',
   '--border': '#1f1f1f',
   '--input': '#1f1f1f',
-  '--ring': '#333333',
+  '--ring': 'var(--neutral-500)',
   '--brand': '#e4e4e7',
   '--brand-foreground': '#09090b',
   '--brand-muted': '#a3a3a3',
@@ -287,7 +316,11 @@ export const cssVars = {
   '--surface-header': 'rgb(0 0 0 / .7)',
   '--border-hairline': 'var(--neutral-800)',
   '--border-card': 'var(--white-10)',
-  '--border-strong': 'var(--neutral-700)',
+  '--border-strong': 'var(--neutral-500)',
+  '--surface-0': 'var(--background)',
+  '--surface-1': 'var(--card)',
+  '--surface-2': 'var(--muted)',
+  '--surface-3': 'var(--secondary)',
   '--text-primary': 'var(--pure-white)',
   '--text-secondary': 'var(--white-80)',
   '--text-tertiary': 'var(--white-60)',
@@ -323,6 +356,23 @@ export const cssVars = {
   '--leading-6xl': '1',
   '--text-7xl': '4rem',
   '--leading-7xl': '1',
+  '--text-8xl': '5.25rem',
+  '--leading-8xl': '1',
+  '--text-9xl': '7rem',
+  '--leading-9xl': '1',
+  '--font-size-xs': 'var(--text-xs)',
+  '--font-size-sm': 'var(--text-sm)',
+  '--font-size-base': 'var(--text-base)',
+  '--font-size-lg': 'var(--text-lg)',
+  '--font-size-xl': 'var(--text-xl)',
+  '--font-size-2xl': 'var(--text-2xl)',
+  '--font-size-3xl': 'var(--text-3xl)',
+  '--font-size-4xl': 'var(--text-4xl)',
+  '--font-size-5xl': 'var(--text-5xl)',
+  '--font-size-6xl': 'var(--text-6xl)',
+  '--font-size-7xl': 'var(--text-7xl)',
+  '--font-size-8xl': 'var(--text-8xl)',
+  '--font-size-9xl': 'var(--text-9xl)',
   '--weight-normal': '400',
   '--weight-medium': '500',
   '--weight-semibold': '600',
@@ -393,6 +443,12 @@ export const cssVars = {
   '--shadow-floating': '0 25px 50px -12px rgb(0 0 0 / .25)',
   '--shadow-inset-hairline': 'inset 0 0 0 1px var(--white-10)',
   '--ring-focus': '0 0 0 2px var(--ring)',
+  '--shadow-sm': '0 1px 2px 0 rgb(0 0 0 / .40)',
+  '--shadow': '0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45)',
+  '--shadow-md': '0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50)',
+  '--shadow-lg': '0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55)',
+  '--shadow-xl': '0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60)',
+  '--shadow-2xl': 'var(--shadow-floating)',
   '--glow-hero': 'radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%)',
   '--glow-hero-blur': '120px',
   '--sheen-card': 'radial-gradient(120% 120% at 80% 0%,rgb(255 255 255 / .08) 0%,transparent 55%)',
@@ -418,6 +474,8 @@ export const cssVars = {
   '--z-modal': '600',
   '--z-popover': '700',
   '--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-display': 'var(--font-sans)',
   '--font-mono': '"Geist Mono",ui-monospace,SFMono-Regular,monospace',

package/styles.css

@@ -1,5 +1,8 @@
 /* Hanzo Design System — global entry point. Import THIS one file.
-   Source of truth: hanzo-apps/hanzo.ai (app/globals.css, tailwind.config.ts, DESIGN.md). */
+   Every token group is served here; nothing is authored but left unimported.
+   (`tokens/z.css` went missing from this list once and the whole ladder stopped
+   resolving while still type-checking — see scripts/check-tokens.mjs, which now
+   fails the build if any tokens/*.css is not imported below.) */
 @import url("tokens/fonts.css");
 @import url("tokens/colors.css");
 @import url("tokens/typography.css");

package/tokens/base.css

@@ -2,10 +2,14 @@
    a utility framework. Components carry their own styles inline. */
 *{box-sizing:border-box;border-color:var(--border)}
 html{-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;scroll-behavior:smooth}
-body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
-h1,h2,h3,h4{margin:0;font-family:var(--font-display);letter-spacing:var(--tracking-tight);color:var(--text-primary)}
+/* Each font-family carries the stack as a literal fallback. --font-sans lives in
+   tokens/fonts.css, which a surface may legitimately import separately; without
+   the fallback an unresolved var() makes font-family invalid and the UA drops to
+   its SERIF default — the whole console silently rendered in Times. */
+body{margin:0;background:var(--background);color:var(--foreground);font-family:var(--font-sans,ui-sans-serif,system-ui,sans-serif);font-size:var(--text-base);line-height:var(--leading-base);font-feature-settings:var(--font-feature-settings)}
+h1,h2,h3,h4{margin:0;font-family:var(--font-display,var(--font-sans,ui-sans-serif,system-ui,sans-serif));letter-spacing:var(--tracking-tight);color:var(--text-primary)}
 p{margin:0;text-wrap:pretty}
-code,pre,kbd{font-family:var(--font-mono)}
+code,pre,kbd{font-family:var(--font-mono,ui-monospace,SFMono-Regular,monospace)}
 a{color:var(--text-primary);text-decoration:none;text-underline-offset:4px;transition:color var(--duration-fast) var(--ease-out)}
 a:hover{color:var(--text-primary);text-decoration:underline}
 :focus-visible{outline:2px solid var(--ring);outline-offset:2px}

package/tokens/colors.css

@@ -51,7 +51,12 @@
   --destructive-foreground:#f5f5f5;
   --border:#1f1f1f;
   --input:#1f1f1f;
-  --ring:#333333;
+  /* A focus indicator is a NON-TEXT CONTRAST target: WCAG 2.4.11/1.4.11 require
+     3:1 against every surface it can land on. --neutral-500 is the only rung on
+     this ladder that clears 3:1 on all of them — #000000, #0a0a0a, #101010,
+     #1a1a1a, AND the light theme's #ffffff/#f5f5f5 — so one value serves both
+     themes. (Was #333333 = 1.66:1 on --background: not a focus indicator.) */
+  --ring:var(--neutral-500);
   --brand:#e4e4e7;
   --brand-foreground:#09090b;
   --brand-muted:#a3a3a3;
@@ -65,9 +70,24 @@
   --surface-card-quiet:rgb(23 23 23 / .4);   /* bg-neutral-900/40 — story cards */
   --surface-overlay:rgb(10 10 10 / .95);     /* dropdown / popover panels       */
   --surface-header:rgb(0 0 0 / .7);          /* fixed nav, with backdrop blur   */
+  /* Boundaries come in two kinds and they are NOT interchangeable.
+     DECORATIVE (--border, --border-hairline, --border-card): separates content;
+     WCAG imposes no ratio. Keep them quiet.
+     PERCEIVABLE (--border-strong): identifies a CONTROL — an input edge, a
+     switch, a checkbox — and must clear 3:1 (WCAG 1.4.11) on every surface.
+     Reach for --border-strong whenever the boundary IS the affordance. */
   --border-hairline:var(--neutral-800);
   --border-card:var(--white-10);
-  --border-strong:var(--neutral-700);
+  --border-strong:var(--neutral-500);   /* 3.59:1 worst case — see --ring */
+
+  /* ——— the numeric surface ladder ——— */
+  /* Aliases onto the semantic canvases above, so a brand fork that retunes
+     --card/--muted/--secondary retunes the ladder with it and the light theme
+     inverts for free. Ascending lift: 0 is the page, 3 is a hovered control. */
+  --surface-0:var(--background);
+  --surface-1:var(--card);
+  --surface-2:var(--muted);
+  --surface-3:var(--secondary);
 
   /* ——— text ranks ——— */
   --text-primary:var(--pure-white);
@@ -107,7 +127,10 @@
   --destructive-foreground:#ffffff;
   --border:#e5e5e5;
   --input:#e5e5e5;
-  --ring:#d4d4d4;
+  /* Same rung as dark: #d4d4d4 measured 1.48:1 on white and could not carry a
+     focus indicator either. --neutral-500 is 4.74:1 on #ffffff / 4.38:1 on
+     #f5f5f5, so ONE value is conformant in both themes. */
+  --ring:var(--neutral-500);
   --black:#0a0a0a;
   --white:#ffffff;
   --surface-card:#f5f5f5;
@@ -117,7 +140,10 @@
   --surface-header:rgb(255 255 255 / .8);
   --border-hairline:var(--neutral-200);
   --border-card:rgb(0 0 0 / .1);
-  --border-strong:var(--neutral-300);
+  --border-strong:var(--neutral-500);   /* was --neutral-300 = 1.48:1 on white */
+  /* The white-opacity ladder does NOT invert, so --white-40 is white-on-white
+     here (1.00:1). Anything that needs a visible edge in BOTH themes must use
+     --border-strong, never a --white-* rung. */
   --text-primary:var(--neutral-950);
   --text-secondary:rgb(10 10 10 / .8);
   --text-tertiary:rgb(10 10 10 / .6);

package/tokens/elevation.css

@@ -6,6 +6,18 @@
   --shadow-floating:0 25px 50px -12px rgb(0 0 0 / .25);  /* shadow-2xl: composer, dropdowns, mega panel */
   --shadow-inset-hairline:inset 0 0 0 1px var(--white-10);
   --ring-focus:0 0 0 2px var(--ring);
+
+  /* The t-shirt ramp. Named by size rather than by role, because that is how
+     every component library already asks for a shadow (and how @hanzo/brand
+     spells it). Alphas are heavier than Tailwind's defaults: on a near-black
+     ground a 10% black drop is invisible, so each rung is tuned to read on
+     --background. --shadow-2xl and --shadow-floating are the same rung. */
+  --shadow-sm:0 1px 2px 0 rgb(0 0 0 / .40);
+  --shadow:0 1px 3px 0 rgb(0 0 0 / .45), 0 1px 2px -1px rgb(0 0 0 / .45);
+  --shadow-md:0 4px 6px -1px rgb(0 0 0 / .50), 0 2px 4px -2px rgb(0 0 0 / .50);
+  --shadow-lg:0 10px 15px -3px rgb(0 0 0 / .55), 0 4px 6px -4px rgb(0 0 0 / .55);
+  --shadow-xl:0 20px 25px -5px rgb(0 0 0 / .60), 0 8px 10px -6px rgb(0 0 0 / .60);
+  --shadow-2xl:var(--shadow-floating);
   /* Ambient hero glow — a single white radial, blurred 120px, low opacity. */
   --glow-hero:radial-gradient(circle,rgb(255 255 255 / .12) 0%,transparent 68%); /* @kind color */
   --glow-hero-blur:120px;

package/tokens/fonts.css

@@ -1,7 +1,34 @@
 /* Geist Sans + Geist Mono — the only two faces on Hanzo surfaces.
-   hanzo.ai loads them via next/font/google (Geist, Geist_Mono); here they come
-   from the same Google Fonts source, so the rendered face is identical. */
-@import url("https://fonts.googleapis.com/css2?family=Geist:wght@100..900&family=Geist+Mono:wght@100..900&display=swap");
+   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:
+   - 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.
+   - One variable file per family replaces nine static weights, and it is fewer
+     bytes than the CSS-then-woff2 round trip Google served.
+
+   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. */
+
+@font-face{
+  font-family:"Geist";
+  src:url("../assets/fonts/Geist-Variable.woff2") format("woff2");
+  font-weight:100 900;
+  font-style:normal;
+  font-display:swap;
+}
+@font-face{
+  font-family:"Geist Mono";
+  src:url("../assets/fonts/GeistMono-Variable.woff2") format("woff2");
+  font-weight:100 900;
+  font-style:normal;
+  font-display:swap;
+}
 
 :root{
   --font-sans:"Geist","Geist Sans",ui-sans-serif,system-ui,sans-serif;

package/tokens/typography.css

@@ -16,6 +16,25 @@
   --text-5xl:2.5rem;    --leading-5xl:1.05;     /* 40px */
   --text-6xl:3.25rem;   --leading-6xl:1;        /* 52px */
   --text-7xl:4rem;      --leading-7xl:1;        /* 64px */
+  --text-8xl:5.25rem;   --leading-8xl:1;        /* 84px */
+  --text-9xl:7rem;      --leading-9xl:1;        /* 112px */
+
+  /* The SAME scale under @hanzo/brand's spelling. @hanzo/gui's shell theme and
+     Hanzo Studio address the ramp as --font-size-*; both names are one value, so
+     a component written against either resolves here. --text-* is canonical. */
+  --font-size-xs:var(--text-xs);
+  --font-size-sm:var(--text-sm);
+  --font-size-base:var(--text-base);
+  --font-size-lg:var(--text-lg);
+  --font-size-xl:var(--text-xl);
+  --font-size-2xl:var(--text-2xl);
+  --font-size-3xl:var(--text-3xl);
+  --font-size-4xl:var(--text-4xl);
+  --font-size-5xl:var(--text-5xl);
+  --font-size-6xl:var(--text-6xl);
+  --font-size-7xl:var(--text-7xl);
+  --font-size-8xl:var(--text-8xl);
+  --font-size-9xl:var(--text-9xl);
 
   --weight-normal:400;
   --weight-medium:500;

package/tokens/z.css

@@ -1,14 +1,23 @@
 /* Stacking order — the one z-index ladder. Layers are named by role, never by a
    magic number, so a dropdown opened from the fixed header always sits above it
-   and nothing ever reaches for 9999. Below --z-raised is ordinary document flow. */
+   and nothing ever reaches for 9999. Below --z-raised is ordinary document flow.
+
+   Rungs are 100 apart so a surface can slot a one-off BETWEEN two roles
+   (calc(var(--z-modal) + 1)) without inventing a new decade. */
 :root{
   --z-base:0;
-  --z-raised:10;     /* hover-lifted cards, sticky table headers        */
-  --z-sticky:200;    /* pinned section rails                             */
-  --z-header:300;    /* the fixed site header                           */
-  --z-dropdown:400;  /* menus, selects, comboboxes                      */
-  --z-overlay:500;   /* dialog / sheet scrim                            */
-  --z-modal:600;     /* dialogs, sheets, command palette                */
-  --z-popover:700;   /* popovers, tooltips (also when anchored in modals)*/
-  --z-toast:800;     /* toasts / notifications — always on top          */
+  --z-raised:10;       /* hover-lifted cards, sticky table headers          */
+  --z-sticky:200;      /* pinned section rails                              */
+  --z-header:300;      /* the fixed site header                             */
+  --z-dropdown:400;    /* menus, selects, comboboxes                        */
+  --z-overlay:500;     /* dialog / sheet scrim                              */
+  --z-modal:600;       /* dialogs, sheets, command palette                  */
+  --z-popover:700;     /* popovers, tooltips (also when anchored in modals) */
+  --z-toast:800;       /* toasts / notifications — always on top            */
+
+  /* @hanzo/brand spells the top two rungs --z-tooltip and --z-notification.
+     Same rungs, so a component written against either vocabulary stacks
+     identically. --z-popover / --z-toast are canonical. */
+  --z-tooltip:var(--z-popover);
+  --z-notification:var(--z-toast);
 }