@handamade/psi-tokens 0.19.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/llms.txt

@@ -61,4 +61,11 @@ OKLCH formula-based design tokens. Code is the source of truth; all artifacts ge
 - Lower-level helpers are also exported for callers that need one step in isolation: `fnv1a`, `seededRandom`, `buildBrandPalette`, `hexFor`, `contrastOf`, `solveL`, `isBrandVector`, and the `BrandVector`/`ChromaWord`/`RadiusRung` types plus `CHROMA_WORDS`/`RADIUS_RUNGS` constants.
 - `isBrandVector` is the runtime guard for untrusted input (e.g. the `api/theme.ts` Vercel Function) — narrow before calling `deriveTheme`, never trust a client-supplied vector shape directly.
 
+## Building a theme outside this repo (`./theme`, D81)
+- `import { buildThemeCss, ThemeGateError } from "@handamade/psi-tokens/theme"` — `buildThemeCss(name, definition)` returns `{ css, warnings }` for a definition shaped like `customers/<name>.ts` (`palette`, `slots`, optional `base: "light" | "dark"`, `overrides`, `fonts`, `componentOverrides`). It runs the same gates as Psi's own build, through the same code (`src/theme/gate.ts`), and throws `ThemeGateError` (`contrastFailures`, `scopeViolations`) instead of returning a failing theme. The names `light` and `dark` are refused.
+- Use it to keep a client brand in the client's repository: nothing client-named has to ship in this public package.
+- The CSS is scoped to `[data-psi-theme="<name>"]`, never `:root`, so a `base: "dark"` theme can style a sub-tree such as a dark sidebar.
+- `psi-theme <definition-module> --name <name> [--out <file.css>]` is the same build as a bin, for a consumer's build script. The module default-exports the definition. Exit codes: 0 built · 1 refused by a gate · 2 usage error.
+- The token builders (`token`, `set`, `delta`, `cap`, `slot`, `ref`) and the definition types are re-exported from `./theme` for writing `overrides`.
+
 Live MCP access to this data: see packages/mcp/llms.txt (hosted: https://psi.kurkin.de/mcp).

package/package.json

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