@handamade/psi-tokens 0.17.0 → 0.19.0

package/README.md

@@ -35,6 +35,22 @@ All tokens are CSS custom properties: `--psi-bg-primary`, `--psi-fg-secondary`,
 
 Run `pnpm new-theme` to scaffold a customer brand theme (palette + slot mapping).
 
+## Deriving a brand from a prompt
+
+`@handamade/psi-tokens/generate` (D57) derives a brand at runtime instead of scaffolding one by hand:
+
+```ts
+import { parsePrompt, deriveTheme, serializeCustomerTheme } from "@handamade/psi-tokens/generate";
+
+const vector = parsePrompt("a calm dark fintech brand");   // deterministic BrandVector
+const pair = deriveTheme(vector);                          // AA-solved light + dark DerivedTheme pair
+const { filename, source, registration } = serializeCustomerTheme(pair); // customers/<name>.ts
+```
+
+- `parsePrompt` is deterministic — an FNV-1a hash seeds a PRNG, so an unrecognised prompt still derives a coherent brand.
+- `deriveTheme` solves both members of the pair independently to WCAG AA by binary-searching lightness; it never returns a below-AA theme, because it throws instead of returning one if the solver can't clear the matrix.
+- `serializeCustomerTheme` emits `customers/<name>.ts` source in the CLI's own layout (`pnpm new-theme`'s `Palette` + `SlotMap`), extended to a pair: two `SlotMap`s (light and dark) and, unlike the CLI's override-free scaffold, the solved `ThemeDef` overrides each member needs to clear AA — the same kind of hand-tuned correction `acmeOverrides` carries in `customers/acme.ts`, but derived rather than hand-tuned.
+
 ## Machine-readable artifacts
 
 For AI and tooling, see [llms.txt](./llms.txt):
@@ -42,6 +58,7 @@ For AI and tooling, see [llms.txt](./llms.txt):
 - `dist/guidance.json` — Variant intent, usage rules, state derivation
 - `dist/dtcg/{theme}.json` — W3C DTCG format export
 - `dist/components/{name}.vars.css` — Component-specific token declarations
+- `dist/generate/` — Compiled `./generate` subpath (`parsePrompt`, `deriveTheme`, `serializeCustomerTheme`, and lower-level helpers)
 
 ## Note
 

package/dist/components/toolbar.vars.css

@@ -0,0 +1,5 @@
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-toolbar-control-width: 200px;
+  }
+}

package/dist/components.css

@@ -328,6 +328,12 @@
   }
 }
 
+@layer psi.components {
+  :where(:root, [data-psi-theme]) {
+    --psi-toolbar-control-width: 200px;
+  }
+}
+
 @layer psi.components {
   :where(:root, [data-psi-theme]) {
     --psi-toast-bg: var(--psi-surface-bg);

package/dist/contrast-matrix.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedTheme } from "./dsl/resolver.js";
+export interface ContrastPair {
+    fg: string;
+    bg: string;
+    minRatio: number;
+}
+export interface ContrastResult extends ContrastPair {
+    ratio: number;
+    pass: boolean;
+}
+/**
+ * Composite a foreground hex color with alpha onto an opaque background hex.
+ * Uses sRGB blending (gamma-encoded): mixed = fg * alpha + bg * (1 - alpha).
+ * Returns an opaque hex color matching browser rendering.
+ */
+export declare function compositeHex(fgHex: string, alpha: number, bgHex: string): string;
+/**
+ * Check contrast ratios for a set of fg/bg pairs in a resolved theme.
+ *
+ * Alpha handling:
+ * - bg with alpha (e.g. fillTint*) is composited onto bgPrimary
+ * - fg with alpha (e.g. fgSecondary) is composited onto the bg token
+ *
+ * bgPrimary is used as the base surface for alpha-bg compositing.
+ */
+export declare function checkContrast(resolved: ResolvedTheme, pairs: ContrastPair[]): ContrastResult[];
+/**
+ * Standard WCAG AA contrast pairs that every theme must pass.
+ */
+export declare const wcagAAPairs: ContrastPair[];
+/** Solid component-variant labels on their variant backgrounds (spec: "every
+ * button/tag label on its variant background ≥ 4.5"). Tint-variant labels are
+ * already covered by the fg-on-tint pairs in wcagAAPairs. */
+export declare const componentLabelPairs: ContrastPair[];

package/dist/contrast-matrix.js

@@ -0,0 +1,130 @@
+import { wcagContrast, formatHex, rgb } from "culori";
+// ── Alpha compositing ─────────────────────────────────────────────
+/**
+ * Composite a foreground hex color with alpha onto an opaque background hex.
+ * Uses sRGB blending (gamma-encoded): mixed = fg * alpha + bg * (1 - alpha).
+ * Returns an opaque hex color matching browser rendering.
+ */
+export function compositeHex(fgHex, alpha, bgHex) {
+    const f = rgb(fgHex);
+    const b = rgb(bgHex);
+    if (!f)
+        throw new Error(`compositeHex: unparseable color "${fgHex}"`);
+    if (!b)
+        throw new Error(`compositeHex: unparseable color "${bgHex}"`);
+    const hex = formatHex({
+        mode: "rgb",
+        r: f.r * alpha + b.r * (1 - alpha),
+        g: f.g * alpha + b.g * (1 - alpha),
+        b: f.b * alpha + b.b * (1 - alpha),
+    });
+    if (!hex)
+        throw new Error(`compositeHex: could not format the blend of "${fgHex}" and "${bgHex}"`);
+    return hex;
+}
+/**
+ * Composite a foreground color with alpha onto an opaque background.
+ * Delegates to compositeHex for sRGB blending.
+ */
+function compositeOnBackground(fg, bg) {
+    const alpha = fg.oklch.alpha ?? 1;
+    if (alpha >= 1) {
+        return fg.hex;
+    }
+    return compositeHex(fg.hex, alpha, bg.hex);
+}
+// ── Contrast checker ──────────────────────────────────────────────
+/**
+ * Check contrast ratios for a set of fg/bg pairs in a resolved theme.
+ *
+ * Alpha handling:
+ * - bg with alpha (e.g. fillTint*) is composited onto bgPrimary
+ * - fg with alpha (e.g. fgSecondary) is composited onto the bg token
+ *
+ * bgPrimary is used as the base surface for alpha-bg compositing.
+ */
+export function checkContrast(resolved, pairs) {
+    const bgPrimary = resolved.bgPrimary;
+    if (!bgPrimary) {
+        throw new Error("Theme must include bgPrimary for contrast checking");
+    }
+    return pairs.map((pair) => {
+        const fgToken = resolved[pair.fg];
+        const bgToken = resolved[pair.bg];
+        if (!fgToken) {
+            throw new Error(`Unknown foreground token: "${pair.fg}"`);
+        }
+        if (!bgToken) {
+            throw new Error(`Unknown background token: "${pair.bg}"`);
+        }
+        // Resolve effective bg: if bg has alpha, composite onto bgPrimary
+        const bgAlpha = bgToken.oklch.alpha ?? 1;
+        const effectiveBgHex = bgAlpha < 1
+            ? compositeOnBackground(bgToken, bgPrimary)
+            : bgToken.hex;
+        // Resolve effective fg: if fg has alpha, composite onto the bg
+        const fgAlpha = fgToken.oklch.alpha ?? 1;
+        const effectiveFgHex = fgAlpha < 1
+            ? compositeOnBackground(fgToken, bgToken)
+            : fgToken.hex;
+        const ratio = wcagContrast(effectiveFgHex, effectiveBgHex);
+        return {
+            ...pair,
+            ratio: Math.round(ratio * 100) / 100,
+            pass: ratio >= pair.minRatio,
+        };
+    });
+}
+// ── Default contrast pairs ────────────────────────────────────────
+const bgSurfaces = [
+    "bgPrimary",
+    "bgSecondary",
+    "fillNeutral1",
+    "fillNeutral2",
+    "fillNeutral3",
+    "fillNeutral4",
+    "fillNeutral5",
+    "fillNeutral6",
+];
+/**
+ * Standard WCAG AA contrast pairs that every theme must pass.
+ */
+export const wcagAAPairs = [
+    // fgPrimary on all surfaces
+    ...bgSurfaces.map((bg) => ({ fg: "fgPrimary", bg, minRatio: 4.5 })),
+    // fgSecondary on all surfaces
+    ...bgSurfaces.map((bg) => ({ fg: "fgSecondary", bg, minRatio: 4.5 })),
+    // Semantic fg on primary background
+    { fg: "fgAccent", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgSuccess", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "bgPrimary", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "bgPrimary", minRatio: 4.5 },
+    // Semantic fg on their tint backgrounds
+    { fg: "fgAccent", bg: "fillTintAccent", minRatio: 4.5 },
+    { fg: "fgSuccess", bg: "fillTintSuccess", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "fillTintWarning", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "fillTintDanger", minRatio: 4.5 },
+    // Primary text on a selected table row's accent wash (D62). Distinct from
+    // the fgAccent/fillTintAccent pair above: a selected row keeps ordinary
+    // body text, it does not recolor it to the accent.
+    { fg: "fgPrimary", bg: "fillTintAccent", minRatio: 4.5 },
+    // Toast's status icon on the elevated surface (D64/D65). The three pairs
+    // above gate these foregrounds on bgPrimary; --psi-surface-bg — what Toast,
+    // Menu and Dialog all alias — resolves to bgSecondary, which was ungated for
+    // the semantic foregrounds until Toast put an icon there. Held at 4.5 even
+    // though an icon is non-text content (WCAG 1.4.11 would allow 3.0): the
+    // colours clear 4.5 anyway, and the matrix's posture is a single floor.
+    { fg: "fgSuccess", bg: "bgSecondary", minRatio: 4.5 },
+    { fg: "fgWarning", bg: "bgSecondary", minRatio: 4.5 },
+    { fg: "fgDanger", bg: "bgSecondary", minRatio: 4.5 },
+];
+/** Solid component-variant labels on their variant backgrounds (spec: "every
+ * button/tag label on its variant background ≥ 4.5"). Tint-variant labels are
+ * already covered by the fg-on-tint pairs in wcagAAPairs. */
+export const componentLabelPairs = [
+    { fg: "fgOnAccent", bg: "fillAccent", minRatio: 4.5 }, // Button/IconButton/Tag accent label, Checkbox check, outline hover (D37)
+    { fg: "fgStaticWhite", bg: "fillDanger", minRatio: 4.5 }, // Button/IconButton/Tag danger
+    { fg: "fgStaticWhite", bg: "fillSuccess", minRatio: 4.5 }, // Tag success
+    { fg: "fgStaticBlack", bg: "fillWarning", minRatio: 4.5 }, // Tag warning (D22)
+    { fg: "fgOnInverted", bg: "bgInverted", minRatio: 4.5 }, // Tooltip label (D46 inversion pair)
+];

package/dist/dsl/builders.d.ts

@@ -0,0 +1,7 @@
+import type { CapOp, DeltaOp, SetOp, SlotRef, TokenDef, TokenRef } from "./types.js";
+export declare function set(value: number): SetOp;
+export declare function delta(value: number): DeltaOp;
+export declare function cap(value: number): CapOp;
+export declare const slot: Record<string, SlotRef>;
+export declare const ref: Record<string, TokenRef>;
+export declare function token(def: TokenDef): TokenDef;

package/dist/dsl/builders.js

@@ -0,0 +1,25 @@
+// ── Channel operation builders ──────────────────────────────────────
+export function set(value) {
+    return { op: "set", value };
+}
+export function delta(value) {
+    return { op: "delta", value };
+}
+export function cap(value) {
+    return { op: "cap", value };
+}
+// ── Source proxies ──────────────────────────────────────────────────
+export const slot = new Proxy({}, {
+    get(_target, prop) {
+        return { type: "slot", name: prop };
+    },
+});
+export const ref = new Proxy({}, {
+    get(_target, prop) {
+        return { type: "ref", name: prop };
+    },
+});
+// ── Token builder ───────────────────────────────────────────────────
+export function token(def) {
+    return { ...def };
+}

package/dist/dsl/resolver.d.ts

@@ -0,0 +1,3 @@
+import type { Palette, ResolvedToken, SlotMap, ThemeDef } from "./types.js";
+export type ResolvedTheme = Record<string, ResolvedToken>;
+export declare function resolve(theme: ThemeDef, palette: Palette, slots: SlotMap): ResolvedTheme;

package/dist/dsl/resolver.js

@@ -0,0 +1,114 @@
+import { formatHex, clampChroma } from "culori";
+// ── Channel operation application ──────────────────────────────────
+function applyOp(base, op) {
+    if (!op)
+        return base;
+    switch (op.op) {
+        case "set":
+            return op.value;
+        case "delta":
+            return base + op.value;
+        case "cap":
+            return Math.min(base, op.value);
+    }
+}
+// ── Formula string generation ──────────────────────────────────────
+function formatOp(channel, op) {
+    return `${channel} ${op.op}(${op.value})`;
+}
+function formatFormula(def) {
+    const source = def.from.type === "slot"
+        ? `slot(${def.from.name})`
+        : `ref(${def.from.name})`;
+    const ops = [];
+    if (def.l)
+        ops.push(formatOp("L", def.l));
+    if (def.c)
+        ops.push(formatOp("C", def.c));
+    if (def.h)
+        ops.push(formatOp("H", def.h));
+    if (def.alpha !== undefined)
+        ops.push(`alpha(${def.alpha})`);
+    return ops.length > 0 ? `${source} → ${ops.join(", ")}` : source;
+}
+// ── Resolver ───────────────────────────────────────────────────────
+export function resolve(theme, palette, slots) {
+    const cache = new Map();
+    function resolveToken(name) {
+        const cached = cache.get(name);
+        if (cached)
+            return cached;
+        const def = theme[name];
+        if (!def) {
+            throw new Error(`Unknown token: "${name}"`);
+        }
+        // Resolve base L/C/H from source
+        let baseL;
+        let baseC;
+        let baseH;
+        let baseAlpha;
+        if (def.from.type === "slot") {
+            const paletteName = slots[def.from.name];
+            if (!paletteName) {
+                throw new Error(`Unknown slot: "${def.from.name}"`);
+            }
+            const entry = palette[paletteName];
+            if (!entry) {
+                throw new Error(`Unknown palette entry: "${paletteName}" (from slot "${def.from.name}")`);
+            }
+            baseL = entry.l;
+            baseC = entry.c;
+            baseH = entry.h;
+        }
+        else {
+            // ref — recursively resolve the referenced token
+            const refToken = resolveToken(def.from.name);
+            baseL = refToken.oklch.l;
+            baseC = refToken.oklch.c;
+            baseH = refToken.oklch.h;
+            baseAlpha = refToken.oklch.alpha;
+        }
+        // Apply channel operations
+        const l = applyOp(baseL, def.l);
+        const c = applyOp(baseC, def.c);
+        const h = applyOp(baseH, def.h);
+        const alpha = def.alpha ?? baseAlpha;
+        // Build OKLCH color for culori
+        const oklchColor = {
+            mode: "oklch",
+            l,
+            c,
+            h,
+        };
+        if (alpha !== undefined) {
+            oklchColor.alpha = alpha;
+        }
+        // Gamut-map to sRGB via chroma clamping
+        const clamped = clampChroma(oklchColor, "oklch", "rgb");
+        // Extract the gamut-mapped OKLCH values
+        const clampedL = clamped?.l ?? l;
+        const clampedC = clamped?.c ?? 0;
+        const clampedH = clamped?.h ?? h;
+        // Generate hex (always 6-digit sRGB)
+        const hex = formatHex(clamped ?? oklchColor) ?? "#000000";
+        const resolved = {
+            name,
+            oklch: {
+                l: clampedL,
+                c: clampedC,
+                h: clampedH,
+                ...(alpha !== undefined ? { alpha } : {}),
+            },
+            hex,
+            formula: formatFormula(def),
+            ...(def.scopes !== undefined ? { scopes: def.scopes } : {}),
+        };
+        cache.set(name, resolved);
+        return resolved;
+    }
+    const result = {};
+    for (const name of Object.keys(theme)) {
+        result[name] = resolveToken(name);
+    }
+    return result;
+}

package/dist/dsl/types.d.ts

@@ -0,0 +1,59 @@
+export interface SetOp {
+    readonly op: "set";
+    readonly value: number;
+}
+export interface DeltaOp {
+    readonly op: "delta";
+    readonly value: number;
+}
+export interface CapOp {
+    readonly op: "cap";
+    readonly value: number;
+}
+export type ChannelOp = SetOp | DeltaOp | CapOp;
+export interface SlotRef {
+    readonly type: "slot";
+    readonly name: string;
+}
+export interface TokenRef {
+    readonly type: "ref";
+    readonly name: string;
+}
+export type TokenSource = SlotRef | TokenRef;
+export interface TokenDef {
+    readonly from: TokenSource;
+    readonly l?: ChannelOp;
+    readonly c?: ChannelOp;
+    readonly h?: ChannelOp;
+    readonly alpha?: number;
+    /** D46: property groups / CSS properties this token may bind to
+     * (see src/scopes.ts). Unscoped tokens are valid everywhere. */
+    readonly scopes?: readonly string[];
+}
+export interface PaletteEntry {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+}
+export type Palette = Record<string, PaletteEntry>;
+export interface SlotMap {
+    readonly ink: string;
+    readonly canvas: string;
+    readonly accent: string;
+    readonly success: string;
+    readonly warning: string;
+    readonly danger: string;
+}
+export type ThemeDef = Record<string, TokenDef>;
+export interface ResolvedToken {
+    readonly name: string;
+    readonly oklch: {
+        readonly l: number;
+        readonly c: number;
+        readonly h: number;
+        readonly alpha?: number;
+    };
+    readonly hex: string;
+    readonly formula: string;
+    readonly scopes?: readonly string[];
+}

package/dist/dsl/types.js

@@ -0,0 +1,2 @@
+// ── Channel operations ──────────────────────────────────────────────
+export {};

package/dist/generate/derive.d.ts

@@ -0,0 +1,20 @@
+import { type ResolvedTheme } from "../dsl/resolver.js";
+import { type CustomerTheme } from "../themes/customers/index.js";
+import type { BrandVector } from "./types.js";
+export interface DerivedTheme {
+    mode: "light" | "dark";
+    customerTheme: CustomerTheme;
+    resolved: ResolvedTheme;
+    customProperties: Record<string, string>;
+}
+export interface DerivedPair {
+    vector: BrandVector;
+    light: DerivedTheme;
+    dark: DerivedTheme;
+}
+/**
+ * Derive both members of a brand from one vector, each solved to AA
+ * independently (D57). The header toggle then selects between them — there is
+ * nothing left to recompute.
+ */
+export declare function deriveTheme(v: BrandVector): DerivedPair;