@handamade/psi-tokens 0.19.0 → 0.21.0

package/dist/resolved/dark.json

@@ -157,7 +157,8 @@
       "hex": "#00cf77",
       "formula": "slot(success) → L set(0.75), C cap(0.23)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#e79d00",
       "formula": "slot(warning) → L set(0.75), C cap(0.1582)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/resolved/ember.json

@@ -157,7 +157,8 @@
       "hex": "#00cf77",
       "formula": "slot(success) → L set(0.75), C cap(0.23)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#e79d00",
       "formula": "slot(warning) → L set(0.75), C cap(0.1582)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/resolved/light.json

@@ -157,7 +157,8 @@
       "hex": "#00703e",
       "formula": "slot(success) → L set(0.48), C cap(0.1187)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgWarning": {
@@ -170,7 +171,8 @@
       "hex": "#7e5400",
       "formula": "slot(warning) → L set(0.48), C cap(0.1013)",
       "scopes": [
-        "text"
+        "text",
+        "border"
       ]
     },
     "fgDanger": {
@@ -574,6 +576,11 @@
         "tooltip": 1100
       }
     },
+    "focusRing": {
+      "width": 2,
+      "offset": 2,
+      "offsetInset": -2
+    },
     "scopes": {
       "space": [
         "gap"

package/dist/scope-gate.d.ts

@@ -0,0 +1,15 @@
+import type { ThemeDef } from "./dsl/types.js";
+export interface ScopeViolation {
+    component: string;
+    key: string;
+    group: string;
+    token: string;
+    scopes: readonly string[];
+}
+/** D46 primary gate: every component token whose key declares a property
+ * group (-bg/-fg/-border) may only bind semantic tokens scoped to it. */
+export declare function checkScopes(componentVars: Record<string, Record<string, string>>, theme: ThemeDef): ScopeViolation[];
+/** Same gate for brand componentOverrides ("button-accent-bg": "..."):
+ * component resolved by longest known prefix; unknown prefixes are skipped
+ * (non-color overrides like media-tint carry no component token shape). */
+export declare function checkOverrideScopes(overrides: Record<string, string>, componentVars: Record<string, Record<string, string>>, theme: ThemeDef): ScopeViolation[];

package/dist/scope-gate.js

@@ -0,0 +1,87 @@
+import { PROPERTY_GROUPS, expandScopes, keyGroup } from "./scopes.js";
+const VAR_RE = /var\((--psi-[a-z0-9-]+)/g;
+const SCALE_RE = /^--psi-(space|size|radius|text|font|duration|ease|z)-/;
+const camelToKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/** Collect the semantic token names (camelCase) a component-token value
+ * ultimately binds, following component-token chains across the whole
+ * registry (own family and cross-family, e.g. dialog-bg → surface-bg).
+ * Unresolvable --psi- refs are returned as raw var names (prefixed "!")
+ * for the caller to flag. */
+function semanticRefs(component, value, all, kebabToName, seen = new Set()) {
+    const out = [];
+    for (const m of value.matchAll(VAR_RE)) {
+        const varName = m[1];
+        const bare = varName.slice("--psi-".length);
+        if (SCALE_RE.test(varName))
+            continue;
+        // Component refs resolve through the registry; longest prefix wins.
+        const owner = Object.keys(all)
+            .filter((c) => bare.startsWith(`${c}-`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (owner !== undefined) {
+            const key = bare.slice(owner.length + 1);
+            const guard = `${owner}:${key}`;
+            if (seen.has(guard))
+                continue;
+            seen.add(guard);
+            const ownerValue = all[owner][key];
+            if (ownerValue === undefined) {
+                out.push(`!${varName}`);
+                continue;
+            }
+            out.push(...semanticRefs(owner, ownerValue, all, kebabToName, seen));
+            continue;
+        }
+        const name = kebabToName.get(bare);
+        out.push(name ?? `!${varName}`);
+    }
+    return out;
+}
+function checkOne(component, key, value, all, theme, kebabToName) {
+    const group = keyGroup(key);
+    if (!group)
+        return [];
+    const groupProps = new Set(PROPERTY_GROUPS[group]);
+    const violations = [];
+    for (const name of semanticRefs(component, value, all, kebabToName)) {
+        if (name.startsWith("!")) {
+            violations.push({ component, key, group, token: name.slice(1), scopes: [] });
+            continue;
+        }
+        const scopes = theme[name]?.scopes;
+        if (scopes === undefined)
+            continue; // unscoped tokens are valid everywhere
+        const allowed = scopes.includes(group) || expandScopes(scopes).some((p) => groupProps.has(p));
+        if (!allowed)
+            violations.push({ component, key, group, token: name, scopes });
+    }
+    return violations;
+}
+/** D46 primary gate: every component token whose key declares a property
+ * group (-bg/-fg/-border) may only bind semantic tokens scoped to it. */
+export function checkScopes(componentVars, theme) {
+    const kebabToName = new Map(Object.keys(theme).map((n) => [camelToKebab(n), n]));
+    const violations = [];
+    for (const [component, vars] of Object.entries(componentVars)) {
+        for (const [key, value] of Object.entries(vars)) {
+            violations.push(...checkOne(component, key, value, componentVars, theme, kebabToName));
+        }
+    }
+    return violations;
+}
+/** Same gate for brand componentOverrides ("button-accent-bg": "..."):
+ * component resolved by longest known prefix; unknown prefixes are skipped
+ * (non-color overrides like media-tint carry no component token shape). */
+export function checkOverrideScopes(overrides, componentVars, theme) {
+    const kebabToName = new Map(Object.keys(theme).map((n) => [camelToKebab(n), n]));
+    const components = Object.keys(componentVars).sort((a, b) => b.length - a.length);
+    const violations = [];
+    for (const [fullKey, value] of Object.entries(overrides)) {
+        const component = components.find((c) => fullKey.startsWith(`${c}-`));
+        if (!component)
+            continue;
+        const key = fullKey.slice(component.length + 1);
+        violations.push(...checkOne(component, key, value, componentVars, theme, kebabToName));
+    }
+    return violations;
+}

package/dist/scope-map.json

@@ -5,7 +5,8 @@
       "fill",
       "stroke",
       "caret-color",
-      "text-decoration-color"
+      "text-decoration-color",
+      "background-image"
     ],
     "surface": [
       "background",
@@ -106,10 +107,12 @@
       "text"
     ],
     "fg-success": [
-      "text"
+      "text",
+      "border"
     ],
     "fg-warning": [
-      "text"
+      "text",
+      "border"
     ],
     "fg-danger": [
       "text",
@@ -190,6 +193,39 @@
     ]
   },
   "component": {
+    "app-shell-sidebar-bg": [
+      "surface"
+    ],
+    "app-shell-sidebar-fg": [
+      "text"
+    ],
+    "banner-bg-neutral": [
+      "surface"
+    ],
+    "banner-bg-success": [
+      "surface"
+    ],
+    "banner-bg-warning": [
+      "surface"
+    ],
+    "banner-bg-danger": [
+      "surface"
+    ],
+    "banner-fg": [
+      "text"
+    ],
+    "banner-icon-fg-neutral": [
+      "text"
+    ],
+    "banner-icon-fg-success": [
+      "text"
+    ],
+    "banner-icon-fg-warning": [
+      "text"
+    ],
+    "banner-icon-fg-danger": [
+      "text"
+    ],
     "button-accent-bg": [
       "surface"
     ],
@@ -340,6 +376,9 @@
     "field-marker-fg": [
       "text"
     ],
+    "field-required-text-fg": [
+      "text"
+    ],
     "input-bg": [
       "surface"
     ],
@@ -355,6 +394,45 @@
     "input-border-error": [
       "border"
     ],
+    "inline-alert-bg-neutral": [
+      "surface"
+    ],
+    "inline-alert-bg-success": [
+      "surface"
+    ],
+    "inline-alert-bg-warning": [
+      "surface"
+    ],
+    "inline-alert-bg-danger": [
+      "surface"
+    ],
+    "inline-alert-fg": [
+      "text"
+    ],
+    "inline-alert-icon-fg-neutral": [
+      "text"
+    ],
+    "inline-alert-icon-fg-success": [
+      "text"
+    ],
+    "inline-alert-icon-fg-warning": [
+      "text"
+    ],
+    "inline-alert-icon-fg-danger": [
+      "text"
+    ],
+    "inline-alert-border-neutral": [
+      "border"
+    ],
+    "inline-alert-border-success": [
+      "border"
+    ],
+    "inline-alert-border-warning": [
+      "border"
+    ],
+    "inline-alert-border-danger": [
+      "border"
+    ],
     "menu-bg": [
       "surface"
     ],
@@ -421,6 +499,33 @@
     "select-chevron-fg": [
       "text"
     ],
+    "skeleton-bg": [
+      "surface"
+    ],
+    "nav-tree-item-fg": [
+      "text"
+    ],
+    "nav-tree-item-fg-current": [
+      "text"
+    ],
+    "nav-tree-item-bg-hover": [
+      "surface"
+    ],
+    "nav-tree-item-bg-current": [
+      "surface"
+    ],
+    "nav-tree-group-fg": [
+      "text"
+    ],
+    "skip-link-bg": [
+      "surface"
+    ],
+    "skip-link-fg": [
+      "text"
+    ],
+    "skip-link-border": [
+      "border"
+    ],
     "surface-bg": [
       "surface"
     ],

package/dist/scopes.d.ts

@@ -0,0 +1,6 @@
+export declare const PROPERTY_GROUPS: Record<string, readonly string[]>;
+export declare const SUFFIX_GROUPS: Record<string, string>;
+export declare const SCALE_SCOPES: Record<string, readonly string[]>;
+export declare function isKnownScopeEntry(entry: string): boolean;
+export declare function expandScopes(scopes: readonly string[]): readonly string[];
+export declare function keyGroup(key: string): string | undefined;

package/dist/scopes.js

@@ -0,0 +1,88 @@
+// D46 — token scope vocabulary. Scope entries on a token are either a
+// property-group name (key of PROPERTY_GROUPS) or a concrete CSS property
+// listed in one of the groups. The -bg/-fg/-border suffix convention on
+// component-token keys is normative: SUFFIX_GROUPS is the shipped map.
+// ── Property groups ──────────────────────────────────────────────────
+export const PROPERTY_GROUPS = {
+    // background-image (D81): a glyph drawn with CSS gradients — the Select
+    // chevron, which a strict CSP forbids as a data: SVG — is foreground ink,
+    // the same role fill/stroke play on an SVG glyph.
+    text: ["color", "fill", "stroke", "caret-color", "text-decoration-color", "background-image"],
+    surface: ["background", "background-color", "accent-color"],
+    border: [
+        "border", "border-color", "border-top-color", "border-right-color",
+        "border-bottom-color", "border-left-color", "outline", "outline-color",
+        "box-shadow",
+        "border-top", "border-right", "border-bottom", "border-left",
+        "border-inline", "border-block",
+        // Logical longhands. The group already carried every physical longhand and
+        // both logical shorthands, so their absence was an omission rather than a
+        // rule: a vertical Tabs list binding --psi-tabs-list-border to
+        // border-inline-start is exactly the case the group exists to allow, and
+        // the logical form is the one that survives RTL. Found by the D46 gate
+        // itself during D67.
+        "border-inline-start", "border-inline-end",
+        "border-block-start", "border-block-end",
+    ],
+    gap: [
+        "gap", "row-gap", "column-gap",
+        "padding", "padding-top", "padding-right", "padding-bottom", "padding-left",
+        "padding-inline", "padding-block",
+        "padding-inline-start", "padding-inline-end", "padding-block-start", "padding-block-end",
+        "margin", "margin-top", "margin-right", "margin-bottom", "margin-left",
+        "margin-inline", "margin-block",
+        "margin-inline-start", "margin-inline-end", "margin-block-start", "margin-block-end",
+        "inset", "top", "right", "bottom", "left",
+        "scroll-margin", "scroll-padding", "translate",
+        // edge-distance uses: icon offsets (background-position) and viewport-inset sizing (max-width in calc) are gap-family intent
+        "background-position", "max-width",
+    ],
+};
+// ── Normative suffix groups ──────────────────────────────────────────
+// Normative component-token suffix → property group (D46).
+export const SUFFIX_GROUPS = {
+    fg: "text",
+    bg: "surface",
+    border: "border",
+};
+// ── Scale scopes ─────────────────────────────────────────────────────
+// Scale-family scopes (D46 "gaps" family). Families not listed are unscoped.
+export const SCALE_SCOPES = {
+    space: ["gap"],
+};
+// ── Internal lookup ──────────────────────────────────────────────────
+const KNOWN_PROPERTIES = new Set(Object.values(PROPERTY_GROUPS).flat());
+// ── Query functions ─────────────────────────────────────────────────
+export function isKnownScopeEntry(entry) {
+    return entry in PROPERTY_GROUPS || KNOWN_PROPERTIES.has(entry);
+}
+// Expand scope entries (group names or property names) to a deduped
+// property list. Throws on unknown entries (D48 posture).
+export function expandScopes(scopes) {
+    const out = new Set();
+    for (const entry of scopes) {
+        if (entry in PROPERTY_GROUPS) {
+            for (const p of PROPERTY_GROUPS[entry])
+                out.add(p);
+        }
+        else if (KNOWN_PROPERTIES.has(entry)) {
+            out.add(entry);
+        }
+        else {
+            throw new Error(`unknown scope entry "${entry}" — not a known CSS property or declared group`);
+        }
+    }
+    return [...out];
+}
+// Property group a component-token key declares via its last bg/fg/border
+// segment ("accent-bg-hover" → surface). Undefined for unsuffixed keys
+// ("focus-ring", "radius", "backdrop") — those are not scope-checked.
+export function keyGroup(key) {
+    const segments = key.split("-");
+    for (let i = segments.length - 1; i >= 0; i--) {
+        const group = SUFFIX_GROUPS[segments[i]];
+        if (group)
+            return group;
+    }
+    return undefined;
+}

package/dist/theme/gate.d.ts

@@ -0,0 +1,19 @@
+import type { Palette, SlotMap, ThemeDef } from "../dsl/types.js";
+import { type ResolvedTheme } from "../dsl/resolver.js";
+import { type ContrastResult } from "../contrast-matrix.js";
+import { type ScopeViolation } from "../scope-gate.js";
+/** Thrown when a theme fails the WCAG AA contrast gate or the D46 scope gate. */
+export declare class ThemeGateError extends Error {
+    readonly theme: string;
+    readonly contrastFailures: readonly ContrastResult[];
+    readonly scopeViolations: readonly ScopeViolation[];
+    constructor(theme: string, contrastFailures: readonly ContrastResult[], scopeViolations: readonly ScopeViolation[]);
+}
+export interface GatedTheme {
+    resolved: ResolvedTheme;
+    /** Non-fatal gamut warnings. */
+    warnings: string[];
+}
+/** Validate, resolve and gate one theme. Throws ValidationError on a malformed
+ * definition and ThemeGateError on any contrast or scope failure. */
+export declare function gateTheme(name: string, theme: ThemeDef, palette: Palette, slots: SlotMap, componentOverrides?: Record<string, string>): GatedTheme;

package/dist/theme/gate.js

@@ -0,0 +1,44 @@
+import { validate } from "../dsl/validator.js";
+import { resolve } from "../dsl/resolver.js";
+import { gamutWarnings } from "../gamut.js";
+import { checkContrast, wcagAAPairs, componentLabelPairs } from "../contrast-matrix.js";
+import { checkScopes, checkOverrideScopes } from "../scope-gate.js";
+import { componentVars } from "../components/registry.js";
+/** Thrown when a theme fails the WCAG AA contrast gate or the D46 scope gate. */
+export class ThemeGateError extends Error {
+    theme;
+    contrastFailures;
+    scopeViolations;
+    constructor(theme, contrastFailures, scopeViolations) {
+        const parts = [];
+        if (contrastFailures.length > 0) {
+            parts.push(`${contrastFailures.length} contrast failures: ` +
+                contrastFailures.map((f) => `${f.fg} on ${f.bg} ${f.ratio} (need ${f.minRatio})`).join("; "));
+        }
+        if (scopeViolations.length > 0) {
+            parts.push(`${scopeViolations.length} scope violations: ` +
+                scopeViolations.map((v) => `--psi-${v.component}-${v.key} (${v.group}) binds ${v.token}`).join("; "));
+        }
+        super(`${theme} theme failed its gates — ${parts.join(" · ")}`);
+        this.theme = theme;
+        this.contrastFailures = contrastFailures;
+        this.scopeViolations = scopeViolations;
+        this.name = "ThemeGateError";
+    }
+}
+/** Validate, resolve and gate one theme. Throws ValidationError on a malformed
+ * definition and ThemeGateError on any contrast or scope failure. */
+export function gateTheme(name, theme, palette, slots, componentOverrides = {}) {
+    validate(theme, slots);
+    const resolved = resolve(theme, palette, slots);
+    const warnings = gamutWarnings(resolved, theme, palette, slots);
+    const contrastFailures = checkContrast(resolved, [...wcagAAPairs, ...componentLabelPairs]).filter((r) => !r.pass);
+    const scopeViolations = [
+        ...checkScopes(componentVars, theme),
+        ...checkOverrideScopes(componentOverrides, componentVars, theme),
+    ];
+    if (contrastFailures.length > 0 || scopeViolations.length > 0) {
+        throw new ThemeGateError(name, contrastFailures, scopeViolations);
+    }
+    return { resolved, warnings };
+}

package/dist/theme/index.d.ts

@@ -0,0 +1,16 @@
+import { type CustomerTheme } from "../themes/customers/index.js";
+export { ThemeGateError } from "./gate.js";
+export type { CustomerTheme, BrandFonts } from "../themes/customers/index.js";
+export type { Palette, PaletteEntry, SlotMap, ThemeDef, TokenDef } from "../dsl/types.js";
+export { token, set, delta, cap, slot, ref } from "../dsl/builders.js";
+export interface ThemeBuild {
+    /** The theme's CSS, scoped to `[data-psi-theme="<name>"]`. Load it after
+     * `base.css`; apply it with the attribute on any element. */
+    css: string;
+    /** Non-fatal gamut warnings. */
+    warnings: string[];
+}
+/** Build one theme through the same gates as Psi's shipped themes: the
+ * definition is validated, then refused with a ThemeGateError if any WCAG AA
+ * contrast pair or D46 token scope fails. */
+export declare function buildThemeCss(name: string, theme: CustomerTheme): ThemeBuild;

package/dist/theme/index.js

@@ -0,0 +1,23 @@
+// D81 — @handamade/psi-tokens/theme: build a gated theme outside the Psi repo.
+// A consumer keeps its brand's definition in its own repository; nothing
+// client-named has to ship in this package.
+import { assembleCustomerTheme } from "../themes/customers/index.js";
+import { emitThemeCSS } from "../emit/css.js";
+import { gateTheme } from "./gate.js";
+export { ThemeGateError } from "./gate.js";
+export { token, set, delta, cap, slot, ref } from "../dsl/builders.js";
+/** Build one theme through the same gates as Psi's shipped themes: the
+ * definition is validated, then refused with a ThemeGateError if any WCAG AA
+ * contrast pair or D46 token scope fails. */
+export function buildThemeCss(name, theme) {
+    if (name === "light" || name === "dark") {
+        throw new Error(`"${name}" is a built-in theme name; choose another`);
+    }
+    const def = assembleCustomerTheme(theme);
+    const { warnings } = gateTheme(name, def, theme.palette, theme.slots, theme.componentOverrides);
+    const css = emitThemeCSS(name, def, theme.palette, theme.slots, {
+        fonts: theme.fonts,
+        componentOverrides: theme.componentOverrides,
+    });
+    return { css, warnings };
+}

package/dist/themes/dark.js

@@ -17,8 +17,8 @@ export const darkTheme = {
     // tokens were already clamping to, so rendered hex is unchanged. fgSuccess
     // keeps the loose cap: emerald at l 0.75 is already in-gamut.
     fgAccent: token({ from: slot.accent, l: set(0.75), c: cap(0.1286), scopes: ["text"] }),
-    fgSuccess: token({ from: slot.success, l: set(0.75), c: cap(0.23), scopes: ["text"] }),
-    fgWarning: token({ from: slot.warning, l: set(0.75), c: cap(0.1582), scopes: ["text"] }),
+    fgSuccess: token({ from: slot.success, l: set(0.75), c: cap(0.23), scopes: ["text", "border"] }),
+    fgWarning: token({ from: slot.warning, l: set(0.75), c: cap(0.1582), scopes: ["text", "border"] }),
     fgDanger: token({ from: slot.danger, l: set(0.75), c: cap(0.1505), scopes: ["text", "border"] }),
     fillNeutral1: token({ from: slot.ink, l: set(0.18), c: set(0.012), scopes: ["surface"] }),
     fillNeutral2: token({ from: slot.ink, l: set(0.2), c: set(0.015), scopes: ["surface"] }),

package/dist/themes/light.js

@@ -16,8 +16,10 @@ export const lightTheme = {
     fgAccent: token({ from: slot.accent, l: set(0.48), c: cap(0.23), scopes: ["text"] }),
     // D39: status-fg caps lowered to each hue's in-gamut max at l 0.48 — the
     // values these tokens were already clamping to, so rendered hex is unchanged.
-    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1187), scopes: ["text"] }),
-    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.1013), scopes: ["text"] }),
+    // text + border on all three status foregrounds: fgDanger for Input's error
+    // border (D46), fgSuccess and fgWarning for InlineAlert's (D86).
+    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1187), scopes: ["text", "border"] }),
+    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.1013), scopes: ["text", "border"] }),
     fgDanger: token({ from: slot.danger, l: set(0.48), c: cap(0.1946), scopes: ["text", "border"] }),
     fillNeutral1: token({ from: slot.canvas, l: delta(+0.016), c: delta(-0.001), scopes: ["surface"] }),
     fillNeutral2: token({ from: slot.canvas, scopes: ["surface"] }),

package/llms.txt

@@ -26,6 +26,11 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 - --psi-z-sticky (1), --psi-z-nav (100), --psi-z-overlay (1000), --psi-z-tooltip (1100). sticky is for elements that stack within their own local scroll container (e.g. a sticky table header), not above page chrome.
 - Breakpoints (sm 560 / md 960) are build-time constants (D31), not CSS vars: `import { breakpoints } from "@handamade/psi-tokens/types"` for any @media-driven JS/CSS-in-JS.
 
+## Focus ring (--psi-focus-ring-*)
+- One ring for every focusable part (D82): `outline: var(--psi-focus-ring-width) solid <colour>` on `:focus-visible`, never on `:focus`, never a literal width or offset.
+- --psi-focus-ring-width (2px). --psi-focus-ring-offset (2px) draws the ring outside the control. --psi-focus-ring-offset-inset (-2px) draws it inside, for a control whose outside ring would be clipped or would land on a neighbour: a text field, a tab, a menu item, a row in a list, a panel against the viewport edge.
+- The colour is the component's own --psi-{component}-focus-ring in component CSS, and --psi-border-focus in app CSS. The three geometry tokens are independent px values, so an override on any sub-tree takes effect there; the inset offset is not derived from the width, so override both together.
+
 ## Typography: display, serif, mono
 - Fluid display tier: --psi-display-{min}-{max}-{weight} (e.g. --psi-display-56-128-black), clamp-based and pixel-true at both endpoints; pair with the matching .psi-display-* utility class for tracking/uppercase.
 - Serif and mono are first-class combo roles alongside sans: --psi-text-serif-{size}-{lh}-{weight} and --psi-text-mono-{size}-{lh}-{weight}, same naming shape as the sans scale.
@@ -61,4 +66,11 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 - Lower-level helpers are also exported for callers that need one step in isolation: `fnv1a`, `seededRandom`, `buildBrandPalette`, `hexFor`, `contrastOf`, `solveL`, `isBrandVector`, and the `BrandVector`/`ChromaWord`/`RadiusRung` types plus `CHROMA_WORDS`/`RADIUS_RUNGS` constants.
 - `isBrandVector` is the runtime guard for untrusted input (e.g. the `api/theme.ts` Vercel Function) — narrow before calling `deriveTheme`, never trust a client-supplied vector shape directly.
 
+## Building a theme outside this repo (`./theme`, D81)
+- `import { buildThemeCss, ThemeGateError } from "@handamade/psi-tokens/theme"` — `buildThemeCss(name, definition)` returns `{ css, warnings }` for a definition shaped like `customers/<name>.ts` (`palette`, `slots`, optional `base: "light" | "dark"`, `overrides`, `fonts`, `componentOverrides`). It runs the same gates as Psi's own build, through the same code (`src/theme/gate.ts`), and throws `ThemeGateError` (`contrastFailures`, `scopeViolations`) instead of returning a failing theme. The names `light` and `dark` are refused.
+- Use it to keep a client brand in the client's repository: nothing client-named has to ship in this public package.
+- The CSS is scoped to `[data-psi-theme="<name>"]`, never `:root`, so a `base: "dark"` theme can style a sub-tree such as a dark sidebar.
+- `psi-theme <definition-module> --name <name> [--out <file.css>]` is the same build as a bin, for a consumer's build script. The module default-exports the definition. Exit codes: 0 built · 1 refused by a gate · 2 usage error.
+- The token builders (`token`, `set`, `delta`, `cap`, `slot`, `ref`) and the definition types are re-exported from `./theme` for writing `overrides`.
+
 Live MCP access to this data: see packages/mcp/llms.txt (hosted: https://psi.kurkin.de/mcp).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@handamade/psi-tokens",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -16,8 +16,15 @@
       "types": "./dist/generate/index.d.ts",
       "import": "./dist/generate/index.js"
     },
+    "./theme": {
+      "types": "./dist/theme/index.d.ts",
+      "import": "./dist/theme/index.js"
+    },
     "./guidance.json": "./dist/guidance.json"
   },
+  "bin": {
+    "psi-theme": "./dist/cli/psi-theme.js"
+  },
   "files": [
     "dist",
     "README.md",
@@ -27,6 +34,7 @@
     "culori": "^4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^24.19.0",
     "tsx": "^4.19.0"
   },
   "scripts": {