@handamade/psi-tokens 0.18.0 → 0.20.0

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/customers/acme.d.ts

@@ -0,0 +1,8 @@
+import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+export declare const acmePalette: Palette;
+export declare const acmeSlots: SlotMap;
+/** D39: acme's status hues (160/85/15) have lower in-gamut chroma maxima at
+ * l 0.48 than light.ts's default caps, so the fg formulas carry acme's own
+ * clamp targets. Values are the rendered chromas from dist/resolved/acme.json
+ * — hex output is unchanged. */
+export declare const acmeOverrides: ThemeDef;

package/dist/themes/customers/acme.js

@@ -0,0 +1,31 @@
+import { token, set, cap, slot } from "../../dsl/builders.js";
+export const acmePalette = {
+    charcoal: { l: 0.22, c: 0.015, h: 30 },
+    cream: { l: 0.96, c: 0.01, h: 80 },
+    coral: { l: 0.55, c: 0.2, h: 30 },
+    // D39: c retuned to the anchor's own in-gamut max at l 0.52 (was 0.15, out
+    // of sRGB gamut) — fillSuccess reads this anchor unmodified and was already
+    // clamping to exactly this value.
+    mint: { l: 0.52, c: 0.1176, h: 160 },
+    gold: { l: 0.78, c: 0.15, h: 85 },
+    crimson: { l: 0.55, c: 0.22, h: 15 },
+    white: { l: 1.0, c: 0, h: 0 },
+    black: { l: 0.0, c: 0, h: 0 },
+};
+export const acmeSlots = {
+    ink: "charcoal",
+    canvas: "cream",
+    accent: "coral",
+    success: "mint",
+    warning: "gold",
+    danger: "crimson",
+};
+/** D39: acme's status hues (160/85/15) have lower in-gamut chroma maxima at
+ * l 0.48 than light.ts's default caps, so the fg formulas carry acme's own
+ * clamp targets. Values are the rendered chromas from dist/resolved/acme.json
+ * — hex output is unchanged. */
+export const acmeOverrides = {
+    fgSuccess: token({ from: slot.success, l: set(0.48), c: cap(0.1086) }),
+    fgWarning: token({ from: slot.warning, l: set(0.48), c: cap(0.0984) }),
+    fgDanger: token({ from: slot.danger, l: set(0.48), c: cap(0.1919) }),
+};

package/dist/themes/customers/ember.d.ts

@@ -0,0 +1,13 @@
+import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+import type { BrandFonts } from "./index.js";
+/** Dark-first brand (D27) — the portfolio's ember-field identity.
+ * Anchors are culori-derived from the shipped portfolio hexes. */
+export declare const emberPalette: Palette;
+export declare const emberSlots: SlotMap;
+/** Brand-level font stacks (D29): Archivo for display/sans, IBM Plex for
+ * serif/mono. The DS ships no font files — the portfolio site loads these
+ * webfonts itself. */
+export declare const emberFonts: BrandFonts;
+/** D34 component-token overrides — emitted at [data-psi-theme="ember"] in psi.components. */
+export declare const emberComponentOverrides: Record<string, string>;
+export declare const emberOverrides: ThemeDef;

package/dist/themes/customers/ember.js

@@ -0,0 +1,52 @@
+import { token, set, delta, cap, slot, ref } from "../../dsl/builders.js";
+/** Dark-first brand (D27) — the portfolio's ember-field identity.
+ * Anchors are culori-derived from the shipped portfolio hexes. */
+export const emberPalette = {
+    emberCanvas: { l: 0.147, c: 0.004, h: 49 }, // #0c0a09 page
+    emberInk: { l: 0.949, c: 0.011, h: 72 }, // #f3ede6 text
+    emberAccent: { l: 0.724, c: 0.177, h: 40 }, // #ff7847
+    emberEmerald: { l: 0.52, c: 0.19, h: 155 }, // default success anchor values
+    emberAmber: { l: 0.75, c: 0.1582, h: 75 }, // default warning anchor values (c retuned in-gamut, D39)
+    emberRuby: { l: 0.55, c: 0.22, h: 25 }, // default danger anchor values
+    white: { l: 1.0, c: 0, h: 0 },
+    black: { l: 0.0, c: 0, h: 0 },
+};
+export const emberSlots = {
+    ink: "emberInk",
+    canvas: "emberCanvas",
+    accent: "emberAccent",
+    success: "emberEmerald",
+    warning: "emberAmber",
+    danger: "emberRuby",
+};
+/** Brand-level font stacks (D29): Archivo for display/sans, IBM Plex for
+ * serif/mono. The DS ships no font files — the portfolio site loads these
+ * webfonts itself. */
+export const emberFonts = {
+    sans: '"Archivo", system-ui, sans-serif',
+    serif: '"IBM Plex Serif", Georgia, serif',
+    mono: '"IBM Plex Mono", "Courier New", monospace',
+    display: '"Archivo", system-ui, sans-serif',
+};
+/** D34 component-token overrides — emitted at [data-psi-theme="ember"] in psi.components. */
+export const emberComponentOverrides = {
+    "button-font": "var(--psi-text-mono-15-24-regular)",
+    "card-radius": "0",
+    "media-tint": "grayscale(1) sepia(0.65) saturate(1.6) hue-rotate(-12deg) brightness(0.88) contrast(1.05)",
+};
+export const emberOverrides = {
+    // Inherited dark formulas land off-target (#0e0b07 / #1a150f / #eee6e2);
+    // canvas/ink-anchor overrides hit the shipped hexes exactly.
+    bgPrimary: token({ from: slot.canvas }), // #0c0a09
+    bgSecondary: token({ from: slot.canvas, l: delta(+0.015), c: delta(+0.003) }), // #100d0b
+    fgPrimary: token({ from: slot.ink }), // #f3ede6
+    // Dark label on the ember accent (D37): white is 2.62:1 on #ff7847. The
+    // brand's warm black (l 0.25) scored 6.12:1 — AA-passing but visibly weak
+    // on the saturated orange with the mono button face (field report,
+    // 2026-07-19). Deepened to l 0.14 → 7.5:1, AAA for normal text; scoped
+    // here so fgStaticBlack stays warm everywhere else.
+    fgOnAccent: token({ from: ref.fgStaticBlack, l: set(0.14) }),
+    // D39: ember's accent hue (40) allows more chroma at l 0.75 than dark.ts's
+    // sapphire-tuned cap(0.1286) — carry ember's own in-gamut max.  // #ff885d
+    fgAccent: token({ from: slot.accent, l: set(0.75), c: cap(0.156) }),
+};

package/dist/themes/customers/index.d.ts

@@ -0,0 +1,28 @@
+import type { Palette, SlotMap, ThemeDef } from "../../dsl/types.js";
+/** Brand-level font role assignment (D29). Emitted inside the brand's theme
+ * block; the DS never ships font files — consumers load the webfonts. */
+export interface BrandFonts {
+    sans?: string;
+    serif?: string;
+    mono?: string;
+    display?: string;
+}
+export interface CustomerTheme {
+    palette: Palette;
+    slots: SlotMap;
+    /** Which default theme the brand's formulas build on (D27). Default: "light". */
+    base?: "light" | "dark";
+    /** Optional semantic-token formula overrides, merged over the base theme. */
+    overrides?: ThemeDef;
+    /** Optional brand-level font role assignment (D29). */
+    fonts?: BrandFonts;
+    /** Component-token overrides (D34) — part of the themeable surface. Keys
+     * omit the --psi- prefix, e.g. "card-radius": "0". Must not break a11y,
+     * sizing contracts, or interaction states. */
+    componentOverrides?: Record<string, string>;
+}
+/** Assemble the full semantic ThemeDef for a customer brand (D27). D46: an
+ * override inherits the base token's scopes unless it declares its own — a
+ * brand retuning fgOnAccent's formula must not silently unscope it. */
+export declare function assembleCustomerTheme(c: CustomerTheme): ThemeDef;
+export declare const customerThemes: Record<string, CustomerTheme>;

package/dist/themes/customers/index.js

@@ -0,0 +1,23 @@
+import { lightTheme } from "../light.js";
+import { darkTheme } from "../dark.js";
+import { acmePalette, acmeSlots, acmeOverrides } from "./acme.js";
+import { emberPalette, emberSlots, emberOverrides, emberFonts, emberComponentOverrides } from "./ember.js";
+/** Assemble the full semantic ThemeDef for a customer brand (D27). D46: an
+ * override inherits the base token's scopes unless it declares its own — a
+ * brand retuning fgOnAccent's formula must not silently unscope it. */
+export function assembleCustomerTheme(c) {
+    const base = c.base === "dark" ? darkTheme : lightTheme;
+    const merged = { ...base };
+    for (const [name, def] of Object.entries(c.overrides ?? {})) {
+        const baseScopes = base[name]?.scopes;
+        merged[name] = def.scopes === undefined && baseScopes !== undefined
+            ? { ...def, scopes: baseScopes }
+            : def;
+    }
+    return merged;
+}
+export const customerThemes = {
+    acme: { palette: acmePalette, slots: acmeSlots, overrides: acmeOverrides },
+    ember: { palette: emberPalette, slots: emberSlots, base: "dark", overrides: emberOverrides, fonts: emberFonts, componentOverrides: emberComponentOverrides },
+    // <ds:register — new-theme inserts here, do not remove>
+};

package/dist/themes/dark.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeDef } from "../dsl/types.js";
+export declare const darkTheme: ThemeDef;

package/dist/themes/dark.js

@@ -0,0 +1,55 @@
+import { token, set, cap, slot, ref } from "../dsl/builders.js";
+export const darkTheme = {
+    bgPrimary: token({ from: slot.ink, l: set(0.15), c: set(0.01), scopes: ["surface"] }),
+    bgSecondary: token({ from: slot.ink, l: set(0.2), c: set(0.015), scopes: ["surface"] }),
+    fgPrimary: token({ from: slot.canvas, l: set(0.93), c: set(0.01), scopes: ["text"] }),
+    fgSecondary: token({ from: ref.fgPrimary, alpha: 0.7, scopes: ["text"] }),
+    fgTertiary: token({ from: ref.fgPrimary, alpha: 0.5, scopes: ["text"] }),
+    fgQuaternary: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["text"] }),
+    fgPrimaryInverted: token({ from: slot.ink, l: set(0.15), scopes: ["text"] }),
+    fgStaticWhite: token({ from: slot.canvas, l: set(1.0), c: set(0), scopes: ["text"] }),
+    fgStaticBlack: token({ from: slot.ink, l: set(0.25), c: cap(0.03), scopes: ["text"] }),
+    /** Label ink on fillAccent (D37). Brands whose accent can't carry white
+     * (e.g. ember #ff7847, white = 2.62:1) override this instead of mangling
+     * their anchor. */
+    fgOnAccent: token({ from: ref.fgStaticWhite, scopes: ["text"] }),
+    // D39: caps lowered to each hue's in-gamut max at l 0.75 — the values these
+    // 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"] }),
+    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"] }),
+    fillNeutral3: token({ from: slot.ink, l: set(0.23), c: set(0.018), scopes: ["surface"] }),
+    fillNeutral4: token({ from: slot.ink, l: set(0.26), c: set(0.02), scopes: ["surface"] }),
+    fillNeutral5: token({ from: slot.ink, l: set(0.29), c: set(0.022), scopes: ["surface"] }),
+    fillNeutral6: token({ from: slot.ink, l: set(0.32), c: set(0.025), scopes: ["surface"] }),
+    fillAccent: token({ from: slot.accent, scopes: ["surface", "border"] }),
+    // D39: capped at the formula, not the emerald anchor (see light.ts).
+    fillSuccess: token({ from: slot.success, c: cap(0.1285), scopes: ["surface"] }),
+    fillWarning: token({ from: slot.warning, scopes: ["surface"] }),
+    fillDanger: token({ from: slot.danger, scopes: ["surface"] }),
+    fillTintAccent: token({ from: ref.fgAccent, alpha: 0.15, scopes: ["surface"] }),
+    fillTintSuccess: token({ from: ref.fgSuccess, alpha: 0.15, scopes: ["surface"] }),
+    fillTintWarning: token({ from: ref.fgWarning, alpha: 0.15, scopes: ["surface"] }),
+    fillTintDanger: token({ from: ref.fgDanger, alpha: 0.15, scopes: ["surface"] }),
+    /** D46: the static-white SURFACE (switch thumb) — pure ref, byte-identical
+     * with fgStaticWhite; scoped for what it is. */
+    fillStaticWhite: token({ from: ref.fgStaticWhite, scopes: ["surface"] }),
+    borderFaint: token({ from: ref.fgPrimary, alpha: 0.08, scopes: ["border"] }),
+    borderNeutral: token({ from: ref.fgPrimary, alpha: 0.15, scopes: ["border"] }),
+    borderStrong: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["border"] }),
+    borderFocus: token({ from: ref.fgAccent, scopes: ["border"] }),
+    // Scrims (D32): page-canvas surfaces at alpha — never text pairs, so they
+    // carry no AA gate entries.
+    scrimSoft: token({ from: ref.bgPrimary, alpha: 0.25, scopes: ["surface"] }),
+    scrimMedium: token({ from: ref.bgPrimary, alpha: 0.35, scopes: ["surface"] }),
+    scrimHeavy: token({ from: ref.bgPrimary, alpha: 0.82, scopes: ["surface"] }),
+    /** D46: the deliberate inversion pair (tooltip). Pure refs — always
+     * byte-identical with fgPrimary/bgPrimary in every theme — but scoped
+     * for what they ARE: an inverted surface and the label on it. */
+    bgInverted: token({ from: ref.fgPrimary, scopes: ["surface"] }),
+    fgOnInverted: token({ from: ref.bgPrimary, scopes: ["text"] }),
+};

package/dist/themes/light.d.ts

@@ -0,0 +1,2 @@
+import type { ThemeDef } from "../dsl/types.js";
+export declare const lightTheme: ThemeDef;

package/dist/themes/light.js

@@ -0,0 +1,56 @@
+import { token, set, delta, cap, slot, ref } from "../dsl/builders.js";
+export const lightTheme = {
+    bgPrimary: token({ from: slot.canvas, scopes: ["surface"] }),
+    bgSecondary: token({ from: slot.canvas, l: delta(+0.03), scopes: ["surface"] }),
+    fgPrimary: token({ from: slot.ink, l: set(0.3), c: set(0.03), scopes: ["text"] }),
+    fgSecondary: token({ from: ref.fgPrimary, alpha: 0.7, scopes: ["text"] }),
+    fgTertiary: token({ from: ref.fgPrimary, alpha: 0.5, scopes: ["text"] }),
+    fgQuaternary: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["text"] }),
+    fgPrimaryInverted: token({ from: slot.canvas, scopes: ["text"] }),
+    fgStaticWhite: token({ from: slot.canvas, l: set(1.0), c: set(0), scopes: ["text"] }),
+    fgStaticBlack: token({ from: slot.ink, l: set(0.25), c: cap(0.03), scopes: ["text"] }),
+    /** Label ink on fillAccent (D37). Brands whose accent can't carry white
+     * (e.g. ember #ff7847, white = 2.62:1) override this instead of mangling
+     * their anchor. */
+    fgOnAccent: token({ from: ref.fgStaticWhite, scopes: ["text"] }),
+    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"] }),
+    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"] }),
+    fillNeutral3: token({ from: slot.canvas, l: delta(-0.017), c: delta(+0.001), scopes: ["surface"] }),
+    fillNeutral4: token({ from: slot.canvas, l: delta(-0.034), c: delta(+0.002), scopes: ["surface"] }),
+    fillNeutral5: token({ from: slot.canvas, l: delta(-0.032), c: delta(+0.003), scopes: ["surface"] }),
+    fillNeutral6: token({ from: slot.canvas, l: delta(-0.048), c: delta(+0.004), scopes: ["surface"] }),
+    fillAccent: token({ from: slot.accent, scopes: ["surface", "border"] }),
+    // D39: capped at the formula, not the emerald anchor — dark fgSuccess reads
+    // the same anchor at a different lightness where it IS in-gamut (see
+    // default.ts comment on emerald).
+    fillSuccess: token({ from: slot.success, c: cap(0.1285), scopes: ["surface"] }),
+    fillWarning: token({ from: slot.warning, scopes: ["surface"] }),
+    fillDanger: token({ from: slot.danger, scopes: ["surface"] }),
+    fillTintAccent: token({ from: ref.fgAccent, alpha: 0.12, scopes: ["surface"] }),
+    fillTintSuccess: token({ from: ref.fgSuccess, alpha: 0.12, scopes: ["surface"] }),
+    fillTintWarning: token({ from: ref.fgWarning, alpha: 0.12, scopes: ["surface"] }),
+    fillTintDanger: token({ from: ref.fgDanger, alpha: 0.12, scopes: ["surface"] }),
+    /** D46: the static-white SURFACE (switch thumb) — pure ref, byte-identical
+     * with fgStaticWhite; scoped for what it is. */
+    fillStaticWhite: token({ from: ref.fgStaticWhite, scopes: ["surface"] }),
+    borderFaint: token({ from: ref.fgPrimary, alpha: 0.08, scopes: ["border"] }),
+    borderNeutral: token({ from: ref.fgPrimary, alpha: 0.15, scopes: ["border"] }),
+    borderStrong: token({ from: ref.fgPrimary, alpha: 0.3, scopes: ["border"] }),
+    borderFocus: token({ from: ref.fgAccent, scopes: ["border"] }),
+    // Scrims (D32): page-canvas surfaces at alpha — never text pairs, so they
+    // carry no AA gate entries.
+    scrimSoft: token({ from: ref.bgPrimary, alpha: 0.25, scopes: ["surface"] }),
+    scrimMedium: token({ from: ref.bgPrimary, alpha: 0.35, scopes: ["surface"] }),
+    scrimHeavy: token({ from: ref.bgPrimary, alpha: 0.82, scopes: ["surface"] }),
+    /** D46: the deliberate inversion pair (tooltip). Pure refs — always
+     * byte-identical with fgPrimary/bgPrimary in every theme — but scoped
+     * for what they ARE: an inverted surface and the label on it. */
+    bgInverted: token({ from: ref.fgPrimary, scopes: ["surface"] }),
+    fgOnInverted: token({ from: ref.bgPrimary, scopes: ["text"] }),
+};

package/llms.txt

@@ -53,4 +53,19 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 ## Component overrides (D34)
 - A brand's theme file may declare `componentOverrides: Record<string, string>` (e.g. ember: button-font → mono, card-radius → 0, media-tint → its filter chain), emitted in the brand's own theme file (e.g. dist/ember.css) inside `@layer psi.components`. Prefer this over forking a component's CSS Module for brand-specific token values.
 
+## Deriving a brand from a prompt (`./generate`, D57)
+- `import { parsePrompt, deriveTheme, serializeCustomerTheme } from "@handamade/psi-tokens/generate"` — a runtime subpath (`dist/generate`, compiled from `src/generate` via `tsc`), not a build-time script.
+- `parsePrompt(prompt)` turns free text into a `BrandVector` (hue, chroma word, mode, radius rung, optional fonts, slug name). It is deterministic: an FNV-1a hash of the normalized prompt seeds a PRNG, so an unrecognised prompt still derives a coherent, repeatable vector instead of failing.
+- `deriveTheme(vector)` returns a `DerivedPair` — light and dark members solved independently by binary-searching each text token's lightness until the full WCAG AA matrix (`wcagAAPairs`) passes. The guarantee is about the return value: `deriveTheme` never returns a theme that renders below AA, because it throws instead — when a token can't clear its target at any chroma, when a failure can't be traced to any of the four tokens it solves, when 40 escalation attempts are exhausted, and as a belt-and-braces residual check on the resolved pair.
+- `serializeCustomerTheme(pair)` emits real `customers/<name>.ts` source (a `Palette`, two `SlotMap`s, solved `ThemeDef` overrides for each member, a control-radius `componentOverrides` entry) plus the two registry lines that add it to the customer theme map — `pnpm new-theme`'s single-mode, override-free scaffold extended to a pair, with the solved overrides `acmeOverrides` (`customers/acme.ts`) carries by hand.
+- 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.18.0",
+  "version": "0.20.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -12,8 +12,19 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.js"
     },
+    "./generate": {
+      "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",
@@ -23,10 +34,11 @@
     "culori": "^4.0.0"
   },
   "devDependencies": {
+    "@types/node": "^24.19.0",
     "tsx": "^4.19.0"
   },
   "scripts": {
-    "build": "tsx scripts/build.ts",
+    "build": "tsc -p tsconfig.build.json && tsx scripts/build.ts",
     "dev": "tsx --watch scripts/build.ts --watch",
     "new-theme": "tsx scripts/new-theme.ts"
   }