@hanzo/design 0.1.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,40 @@ 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 "@hanzoai/design/styles.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
+can never drift. Edit a token in `tokens/*.css`, run `npm run build`, and both the
+stylesheet and the code API update together. This is the one place to drive Hanzo's
+look & feel programmatically (the `@hanzogui/shell` theme, Tamagui, any TS surface):
+
+```ts
+import { colors, spacing, radius, zIndex, cssVar } from '@hanzo/design'
+
+spacing['space-4']    // "1rem"
+radius['radius-full'] // "9999px"
+zIndex['z-header']    // 300
+
+// Prefer cssVar() so a value resolves through the live cascade (honors light/dark):
+element.style.background = cssVar('--background')          // "var(--background)"
+element.style.color      = cssVar('--foreground', '#fff')  // with a fallback
+```
+
+Groups: `colors`, `typography`, `spacing`, `radius`, `elevation`, `motion`, `zIndex`,
+`fonts`, `base` (semantic aliases), plus `cssVars` (every token by its literal
+`--name`). All authored **once** in the token CSS — the single source of truth.
+
 Everything below is expressed as CSS custom properties, so code copies over 1:1 — the semantic names match `hanzo.ai`'s variables exactly.
 
 ```jsx
@@ -38,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.
 
@@ -54,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

@@ -0,0 +1,36 @@
+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, <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.
+ */
+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;
+/**
+ * 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.
+ */
+export declare function injectDesignCss(href: string): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,60 @@
+// @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
+//
+export * from './tokens.gen.js';
+import { cssVars } from './tokens.gen.js';
+/**
+ * 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.
+ */
+export function cssVar(name, fallback) {
+    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) {
+    return 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.
+ */
+export 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);
+}