@handamade/psi-tokens 0.17.0 → 0.19.0

package/dist/generate/solve.d.ts

@@ -0,0 +1,36 @@
+/** OKLCH → gamut-clamped sRGB hex. Mirrors what the resolver emits, so a
+ * solved value renders as the same colour the token build would produce. */
+export declare function hexFor(l: number, c: number, h: number): string;
+/** The repo's one WCAG implementation, shared with contrast-matrix.ts. */
+export declare function contrastOf(aHex: string, bHex: string): number;
+export interface SolvedL {
+    /** The chosen lightness. */
+    l: number;
+    /** True when `l` genuinely clears `target`. False means the target was
+     * unreachable at this chroma and hue, and `l` is merely the most legible
+     * value available — the caller MUST reduce chroma and try again. */
+    cleared: boolean;
+}
+/**
+ * Binary-search lightness until a colour clears `target` against `against`.
+ *
+ * `direction` says which way legibility lies: "darker" for ink on a light
+ * canvas, "lighter" for ink on a dark one. The search runs between the
+ * canvas-side bound and the far extreme, converging on the *least* extreme
+ * lightness that still clears the ratio — so a solved colour stays as close
+ * to the brand's intent as the target allows.
+ *
+ * If the target is unreachable at this chroma and hue, `cleared: false` is
+ * returned along with the extreme: the most legible value available rather
+ * than a thrown error. Callers pair this with a chroma reduction, which is
+ * what makes the target reachable for saturated hues — but they must check
+ * `cleared` to know when that retry is required, since a below-AA `l` looks
+ * identical to a solved one otherwise.
+ */
+export declare function solveL(opts: {
+    c: number;
+    h: number;
+    against: string;
+    target: number;
+    direction: "darker" | "lighter";
+}): SolvedL;

package/dist/generate/solve.js

@@ -0,0 +1,56 @@
+import { clampChroma, formatHex, wcagContrast } from "culori";
+/** OKLCH → gamut-clamped sRGB hex. Mirrors what the resolver emits, so a
+ * solved value renders as the same colour the token build would produce. */
+export function hexFor(l, c, h) {
+    if (!Number.isFinite(l) || !Number.isFinite(c) || !Number.isFinite(h)) {
+        // culori coerces NaN to 0, which yields #000000 — a colour that trivially
+        // clears contrast against any light canvas. Failing loudly here keeps a
+        // bug upstream from masquerading as a passing theme.
+        throw new Error(`hexFor: non-finite OKLCH (l=${l}, c=${c}, h=${h})`);
+    }
+    const clamped = clampChroma({ mode: "oklch", l, c, h }, "oklch");
+    return formatHex(clamped) ?? "#000000";
+}
+/** The repo's one WCAG implementation, shared with contrast-matrix.ts. */
+export function contrastOf(aHex, bHex) {
+    return wcagContrast(aHex, bHex);
+}
+const ITERATIONS = 28;
+/**
+ * Binary-search lightness until a colour clears `target` against `against`.
+ *
+ * `direction` says which way legibility lies: "darker" for ink on a light
+ * canvas, "lighter" for ink on a dark one. The search runs between the
+ * canvas-side bound and the far extreme, converging on the *least* extreme
+ * lightness that still clears the ratio — so a solved colour stays as close
+ * to the brand's intent as the target allows.
+ *
+ * If the target is unreachable at this chroma and hue, `cleared: false` is
+ * returned along with the extreme: the most legible value available rather
+ * than a thrown error. Callers pair this with a chroma reduction, which is
+ * what makes the target reachable for saturated hues — but they must check
+ * `cleared` to know when that retry is required, since a below-AA `l` looks
+ * identical to a solved one otherwise.
+ */
+export function solveL(opts) {
+    const { c, h, against, target, direction } = opts;
+    const extreme = direction === "darker" ? 0 : 1;
+    if (contrastOf(hexFor(extreme, c, h), against) < target) {
+        // Unreachable at this chroma — hand back the best available, flagged.
+        return { l: extreme, cleared: false };
+    }
+    let lo = direction === "darker" ? 0 : 1; // known to clear
+    let hi = direction === "darker" ? 1 : 0; // known to fail (or nearly)
+    let best = extreme;
+    for (let i = 0; i < ITERATIONS; i++) {
+        const mid = (lo + hi) / 2;
+        if (contrastOf(hexFor(mid, c, h), against) >= target) {
+            best = mid;
+            lo = mid;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return { l: best, cleared: true };
+}

package/dist/generate/types.d.ts

@@ -0,0 +1,24 @@
+import type { BrandFonts } from "../themes/customers/index.js";
+export type ChromaWord = "muted" | "calm" | "balanced" | "vivid" | "electric";
+export type RadiusRung = 4 | 6 | 8 | 12;
+export declare const RADIUS_RUNGS: readonly RadiusRung[];
+export declare const CHROMA_WORDS: readonly ChromaWord[];
+/**
+ * The whole contract between a prompt and a theme (D57). Every producer of one
+ * is untrusted — the model behind /api/theme returns this, never colours, so
+ * nothing can reach a rendered colour without passing through the AA solver.
+ *
+ * `mode` is a presentation hint, not a derivation input: both members of the
+ * pair are always derived, and `mode` only decides which is shown first.
+ */
+export interface BrandVector {
+    hue: number;
+    chroma: ChromaWord;
+    mode: "light" | "dark";
+    radius: RadiusRung;
+    fonts?: BrandFonts;
+    name: string;
+}
+/** Schema check over a closed set. Anything failing this is discarded and the
+ * local derivation stands — see api/theme.ts and the promo boot script. */
+export declare function isBrandVector(value: unknown): value is BrandVector;

package/dist/generate/types.js

@@ -0,0 +1,48 @@
+export const RADIUS_RUNGS = [4, 6, 8, 12];
+export const CHROMA_WORDS = [
+    "muted",
+    "calm",
+    "balanced",
+    "vivid",
+    "electric",
+];
+const FONT_ROLES = ["sans", "serif", "mono", "display"];
+function isFonts(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    return Object.entries(value).every(([k, v]) => FONT_ROLES.includes(k) && typeof v === "string");
+}
+/** Schema check over a closed set. Anything failing this is discarded and the
+ * local derivation stands — see api/theme.ts and the promo boot script. */
+export function isBrandVector(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    if (typeof v.hue !== "number" || !Number.isFinite(v.hue))
+        return false;
+    if (v.hue < 0 || v.hue >= 360)
+        return false;
+    if (!CHROMA_WORDS.includes(v.chroma))
+        return false;
+    if (v.mode !== "light" && v.mode !== "dark")
+        return false;
+    if (!RADIUS_RUNGS.includes(v.radius))
+        return false;
+    // The length bound is not cosmetic: `name` becomes a filename and a
+    // TypeScript identifier, and this guard is the only thing between an
+    // untrusted producer and both. parsePrompt's own slugify caps at 48.
+    if (typeof v.name !== "string" || v.name.length > 64)
+        return false;
+    // Single interior hyphens only — no consecutive, no trailing. The looser
+    // `^[a-z][a-z0-9-]*$` admitted `a--b` and `ab-`, which `serialize.ts`'s
+    // `ident()` turned into `a-B` and `ab-`: literal hyphens inside a TypeScript
+    // identifier, i.e. an emitted `customers/<name>.ts` that does not parse.
+    // parsePrompt's slugify already collapses runs and strips trailing hyphens,
+    // so nothing it produces is affected — this closes the untrusted path (the
+    // model-supplied name in api/theme.ts, and stored brands).
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(v.name))
+        return false;
+    if (v.fonts !== undefined && !isFonts(v.fonts))
+        return false;
+    return true;
+}

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,12 @@ 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.
+
 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.17.0",
+  "version": "0.19.0",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -12,6 +12,10 @@
       "types": "./dist/types/index.d.ts",
       "import": "./dist/types/index.js"
     },
+    "./generate": {
+      "types": "./dist/generate/index.d.ts",
+      "import": "./dist/generate/index.js"
+    },
     "./guidance.json": "./dist/guidance.json"
   },
   "files": [
@@ -26,7 +30,7 @@
     "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"
   }