@handamade/psi-tokens 0.18.0 → 0.19.0

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.18.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"
   }