@handamade/psi-tokens 0.19.0 → 0.20.0

package/dist/components/table.js

@@ -0,0 +1,30 @@
+/** Table component tokens (--psi-table-*) — D62. Pure indirection, same
+ * posture as menu.ts (D53) and panel.ts: the container aliases the shared
+ * surface family, row states reuse Menu's item recipe, and per-size geometry
+ * aliases the D54/D55 control ramp so a 32px row and a 32px Button are the
+ * same 32px from one source. A brand retuning --psi-surface-* or the control
+ * ramp gets Table for free.
+ *
+ * row-bg-selected is --psi-fill-tint-accent, the same wash Button and Tag use
+ * for accent-subtle. Note --psi-fill-accent2 does NOT exist; do not write it.
+ * Geometry keys carry no bg/fg/border segment, so keyGroup() returns undefined
+ * and they stay out of scope-map.json and both D46 gates. */
+export const tableVars = {
+    bg: "var(--psi-surface-bg)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-surface-radius)",
+    fg: "var(--psi-fg-primary)",
+    "header-fg": "var(--psi-fg-secondary)",
+    "cell-border": "var(--psi-border-faint)",
+    "row-bg": "transparent",
+    "row-bg-hover": "var(--psi-fill-neutral3)",
+    "row-bg-selected": "var(--psi-fill-tint-accent)",
+    "sort-indicator-fg": "var(--psi-fg-accent)",
+    "focus-ring": "var(--psi-border-focus)",
+    "32-row-height": "var(--psi-control-32-height)",
+    "40-row-height": "var(--psi-control-40-height)",
+    "48-row-height": "var(--psi-control-48-height)",
+    "32-cell-padding-x": "var(--psi-control-32-padding-inline)",
+    "40-cell-padding-x": "var(--psi-control-40-padding-inline)",
+    "48-cell-padding-x": "var(--psi-control-48-padding-inline)",
+};

package/dist/components/tabs.d.ts

@@ -0,0 +1,14 @@
+/** Tabs component tokens (--psi-tabs-*) — D67. Pure indirection, same posture
+ * as menu.ts (D53), table.ts (D62) and toast.ts (D64): colour aliases the
+ * semantic layer, geometry aliases the D54/D55 control ramp so a 32px tab and
+ * a 32px Button are the same 32px from one source.
+ *
+ * No new contrast pairs: fgAccent and fgSecondary on bgPrimary are already in
+ * wcagAAPairs, and the geometry keys carry no bg/fg/border segment so
+ * keyGroup() returns undefined and they stay out of both D46 gates.
+ *
+ * fg-disabled is deliberately NOT contrast-gated. Disabled text is exempt from
+ * WCAG 1.4.3, and gating it would force a contrast that defeats the
+ * affordance — the same reasoning behind Menu's item-fg-disabled, which binds
+ * the same token. */
+export declare const tabsVars: Record<string, string>;

package/dist/components/tabs.js

@@ -0,0 +1,26 @@
+/** Tabs component tokens (--psi-tabs-*) — D67. Pure indirection, same posture
+ * as menu.ts (D53), table.ts (D62) and toast.ts (D64): colour aliases the
+ * semantic layer, geometry aliases the D54/D55 control ramp so a 32px tab and
+ * a 32px Button are the same 32px from one source.
+ *
+ * No new contrast pairs: fgAccent and fgSecondary on bgPrimary are already in
+ * wcagAAPairs, and the geometry keys carry no bg/fg/border segment so
+ * keyGroup() returns undefined and they stay out of both D46 gates.
+ *
+ * fg-disabled is deliberately NOT contrast-gated. Disabled text is exempt from
+ * WCAG 1.4.3, and gating it would force a contrast that defeats the
+ * affordance — the same reasoning behind Menu's item-fg-disabled, which binds
+ * the same token. */
+export const tabsVars = {
+    fg: "var(--psi-fg-secondary)",
+    "fg-selected": "var(--psi-fg-accent)",
+    "fg-disabled": "var(--psi-fg-quaternary)",
+    "bg-hover": "var(--psi-fill-neutral3)",
+    indicator: "var(--psi-fill-accent)",
+    "list-border": "var(--psi-border-faint)",
+    "focus-ring": "var(--psi-border-focus)",
+    "32-height": "var(--psi-control-32-height)",
+    "40-height": "var(--psi-control-40-height)",
+    "32-padding-x": "var(--psi-control-32-padding-inline)",
+    "40-padding-x": "var(--psi-control-40-padding-inline)",
+};

package/dist/components/tag.d.ts

@@ -0,0 +1,4 @@
+/** Tag component tokens (--psi-tag-*). Solid variants map to fill + foreground
+ * pairs; subtle variants add tint fills. Warning label uses fg-static-black
+ * (D22) instead of fg-primary for contrast and visual emphasis. */
+export declare const tagVars: Record<string, string>;

package/dist/components/tag.js

@@ -0,0 +1,26 @@
+/** Tag component tokens (--psi-tag-*). Solid variants map to fill + foreground
+ * pairs; subtle variants add tint fills. Warning label uses fg-static-black
+ * (D22) instead of fg-primary for contrast and visual emphasis. */
+export const tagVars = {
+    "neutral-bg": "var(--psi-fill-neutral3)",
+    "neutral-fg": "var(--psi-fg-primary)",
+    "accent-bg": "var(--psi-fill-accent)",
+    "accent-fg": "var(--psi-fg-on-accent)",
+    "success-bg": "var(--psi-fill-success)",
+    "success-fg": "var(--psi-fg-static-white)",
+    "warning-bg": "var(--psi-fill-warning)",
+    "warning-fg": "var(--psi-fg-static-black)",
+    "danger-bg": "var(--psi-fill-danger)",
+    "danger-fg": "var(--psi-fg-static-white)",
+    "neutral-subtle-bg": "var(--psi-fill-neutral2)",
+    "neutral-subtle-fg": "var(--psi-fg-secondary)",
+    "accent-subtle-bg": "var(--psi-fill-tint-accent)",
+    "accent-subtle-fg": "var(--psi-fg-accent)",
+    "success-subtle-bg": "var(--psi-fill-tint-success)",
+    "success-subtle-fg": "var(--psi-fg-success)",
+    "warning-subtle-bg": "var(--psi-fill-tint-warning)",
+    "warning-subtle-fg": "var(--psi-fg-warning)",
+    "danger-subtle-bg": "var(--psi-fill-tint-danger)",
+    "danger-subtle-fg": "var(--psi-fg-danger)",
+    "focus-ring": "var(--psi-border-focus)",
+};

package/dist/components/toast.d.ts

@@ -0,0 +1,19 @@
+/** Toast component tokens (--psi-toast-*) — D64/D65. Pure indirection, same
+ * posture as menu.ts (D53) and table.ts (D62): the card aliases the shared
+ * surface family, so a brand retuning --psi-surface-* gets Toast for free.
+ *
+ * The variant lives in the status icon's colour only — Toast is an elevated
+ * surface card, not a tinted one (a stack of three saturated cards is the
+ * loudest thing on the screen, and a tint fights the elevated-surface language
+ * every other overlay speaks). The tinted alternative was measured and also
+ * passes contrast; it is rejected on design grounds, not on the gate.
+ *
+ * Note there is NO shadow key: --psi-shadow-* does not exist in any form, and
+ * neither Menu nor Dialog declares a box-shadow. Psi's elevated surfaces are
+ * border + background. Do not write --psi-shadow-overlay.
+ *
+ * The three semantic icon foregrounds sit on bgSecondary (what --psi-surface-bg
+ * resolves to), so contrast-matrix.ts gates fgSuccess/fgWarning/fgDanger there
+ * as well as on bgPrimary. Tightest measured margin is 5.87 (light) against a
+ * 4.5 floor. */
+export declare const toastVars: Record<string, string>;

package/dist/components/toast.js

@@ -0,0 +1,28 @@
+/** Toast component tokens (--psi-toast-*) — D64/D65. Pure indirection, same
+ * posture as menu.ts (D53) and table.ts (D62): the card aliases the shared
+ * surface family, so a brand retuning --psi-surface-* gets Toast for free.
+ *
+ * The variant lives in the status icon's colour only — Toast is an elevated
+ * surface card, not a tinted one (a stack of three saturated cards is the
+ * loudest thing on the screen, and a tint fights the elevated-surface language
+ * every other overlay speaks). The tinted alternative was measured and also
+ * passes contrast; it is rejected on design grounds, not on the gate.
+ *
+ * Note there is NO shadow key: --psi-shadow-* does not exist in any form, and
+ * neither Menu nor Dialog declares a box-shadow. Psi's elevated surfaces are
+ * border + background. Do not write --psi-shadow-overlay.
+ *
+ * The three semantic icon foregrounds sit on bgSecondary (what --psi-surface-bg
+ * resolves to), so contrast-matrix.ts gates fgSuccess/fgWarning/fgDanger there
+ * as well as on bgPrimary. Tightest measured margin is 5.87 (light) against a
+ * 4.5 floor. */
+export const toastVars = {
+    bg: "var(--psi-surface-bg)",
+    border: "var(--psi-surface-border)",
+    radius: "var(--psi-surface-radius)",
+    fg: "var(--psi-fg-primary)",
+    "icon-fg-neutral": "var(--psi-fg-secondary)",
+    "icon-fg-success": "var(--psi-fg-success)",
+    "icon-fg-warning": "var(--psi-fg-warning)",
+    "icon-fg-danger": "var(--psi-fg-danger)",
+};

package/dist/components/toolbar.d.ts

@@ -0,0 +1,13 @@
+/** Toolbar component tokens (--psi-toolbar-*) — D77.
+ *
+ * A deliberate default width for Toolbar's direct, unwrapped form-control
+ * children (Input/Select used bare, as the filter-toolbar preset does) —
+ * without it, their own width:100% resolves as their flex-basis and the
+ * row stacks vertically instead of reading as a toolbar. Field-wrapped
+ * controls are unaffected: Field has no width of its own, so its flex-basis
+ * already comes from content. 200px is a standalone literal, matching
+ * Dialog's width={400|560|720} precedent — no shared scale reaches this
+ * range (sizeScale tops at 48, spacingScale at 144, both for heights/gaps
+ * not component widths).
+ */
+export declare const toolbarVars: Record<string, string>;

package/dist/components/toolbar.js

@@ -0,0 +1,15 @@
+/** Toolbar component tokens (--psi-toolbar-*) — D77.
+ *
+ * A deliberate default width for Toolbar's direct, unwrapped form-control
+ * children (Input/Select used bare, as the filter-toolbar preset does) —
+ * without it, their own width:100% resolves as their flex-basis and the
+ * row stacks vertically instead of reading as a toolbar. Field-wrapped
+ * controls are unaffected: Field has no width of its own, so its flex-basis
+ * already comes from content. 200px is a standalone literal, matching
+ * Dialog's width={400|560|720} precedent — no shared scale reaches this
+ * range (sizeScale tops at 48, spacingScale at 144, both for heights/gaps
+ * not component widths).
+ */
+export const toolbarVars = {
+    "control-width": "200px",
+};

package/dist/components/tooltip.d.ts

@@ -0,0 +1,2 @@
+/** Tooltip component tokens (--psi-tooltip-*). Inverted colors: dark bg, light fg. */
+export declare const tooltipVars: Record<string, string>;

package/dist/components/tooltip.js

@@ -0,0 +1,7 @@
+/** Tooltip component tokens (--psi-tooltip-*). Inverted colors: dark bg, light fg. */
+export const tooltipVars = {
+    bg: "var(--psi-bg-inverted)",
+    fg: "var(--psi-fg-on-inverted)",
+    // D56: tracks a sharper theme down, never rounder than radius-6.
+    radius: "min(var(--psi-control-radius), var(--psi-radius-6))",
+};

package/dist/dsl/validator.d.ts

@@ -0,0 +1,12 @@
+import type { SlotMap, ThemeDef } from "./types.js";
+export declare class ValidationError extends Error {
+    readonly path: string[];
+    constructor(message: string, path?: string[]);
+}
+export declare function validate(theme: ThemeDef, slots: SlotMap, existingNames?: string[]): void;
+/** D46: the same token name must carry identical scopes in every theme —
+ * scopes are a property of the token's meaning, not of a theme. */
+export declare function validateScopeConsistency(themes: Record<string, ThemeDef>): void;
+/** D46 follow-up (HAN-21): reject semantic token kebab names that a
+ * scale-family lookup would shadow before the semantic lookup runs. */
+export declare function validateNoScalePrefixShadow(kebabNames: readonly string[]): void;

package/dist/dsl/validator.js

@@ -0,0 +1,97 @@
+import { isKnownScopeEntry } from "../scopes.js";
+// ── Validation error ───────────────────────────────────────────────
+export class ValidationError extends Error {
+    path;
+    constructor(message, path = []) {
+        super(message);
+        this.name = "ValidationError";
+        this.path = path;
+    }
+}
+// ── Cycle detection ────────────────────────────────────────────────
+function detectCycles(theme) {
+    const visited = new Set();
+    const inStack = new Set();
+    function dfs(name, chain) {
+        if (inStack.has(name)) {
+            const cycleStart = chain.indexOf(name);
+            const cycle = chain.slice(cycleStart).concat(name);
+            throw new ValidationError(`Circular reference detected: ${cycle.join(" → ")}`, cycle);
+        }
+        if (visited.has(name))
+            return;
+        inStack.add(name);
+        chain.push(name);
+        const token = theme[name];
+        if (token?.from.type === "ref") {
+            dfs(token.from.name, chain);
+        }
+        chain.pop();
+        inStack.delete(name);
+        visited.add(name);
+    }
+    for (const name of Object.keys(theme)) {
+        dfs(name, []);
+    }
+}
+// ── Main validator ─────────────────────────────────────────────────
+export function validate(theme, slots, existingNames = []) {
+    const slotNames = new Set(Object.keys(slots));
+    const tokenNames = new Set(Object.keys(theme));
+    // Check for duplicate names against existingNames
+    for (const name of tokenNames) {
+        if (existingNames.includes(name)) {
+            throw new ValidationError(`Duplicate token name: "${name}" already exists`, [name]);
+        }
+    }
+    // Validate each token's source
+    for (const [name, token] of Object.entries(theme)) {
+        const { from } = token;
+        if (from.type === "slot") {
+            if (!slotNames.has(from.name)) {
+                throw new ValidationError(`Unknown slot "${from.name}" in token "${name}"`, [name]);
+            }
+        }
+        else if (from.type === "ref") {
+            if (!tokenNames.has(from.name)) {
+                throw new ValidationError(`Unknown ref "${from.name}" in token "${name}"`, [name]);
+            }
+        }
+        for (const entry of token.scopes ?? []) {
+            if (!isKnownScopeEntry(entry)) {
+                throw new ValidationError(`Unknown scope entry "${entry}" in token "${name}" — not a known CSS property or declared group`, [name]);
+            }
+        }
+    }
+    // Detect cycles in ref chains
+    detectCycles(theme);
+}
+/** D46: the same token name must carry identical scopes in every theme —
+ * scopes are a property of the token's meaning, not of a theme. */
+export function validateScopeConsistency(themes) {
+    const seen = new Map();
+    for (const [themeName, theme] of Object.entries(themes)) {
+        for (const [name, def] of Object.entries(theme)) {
+            const key = JSON.stringify(def.scopes ?? null);
+            const prior = seen.get(name);
+            if (prior === undefined) {
+                seen.set(name, { theme: themeName, scopes: key });
+            }
+            else if (prior.scopes !== key) {
+                throw new ValidationError(`Scope drift for token "${name}": ${prior.theme} declares ${prior.scopes}, ${themeName} declares ${key}`, [name]);
+            }
+        }
+    }
+}
+// Both gates resolve --psi-* names scale-first, so a semantic token whose
+// kebab name starts with a scale-family prefix would be silently shadowed.
+const SCALE_FAMILY_PREFIX = /^(space|size|radius|text|font|duration|ease|z)-/;
+/** D46 follow-up (HAN-21): reject semantic token kebab names that a
+ * scale-family lookup would shadow before the semantic lookup runs. */
+export function validateNoScalePrefixShadow(kebabNames) {
+    for (const name of kebabNames) {
+        if (SCALE_FAMILY_PREFIX.test(name)) {
+            throw new ValidationError(`Semantic token "${name}" starts with a scale-family prefix — it would be shadowed by the scale lookup in the build and stylelint gates`, [name]);
+        }
+    }
+}

package/dist/emit/css.d.ts

@@ -0,0 +1,30 @@
+import type { ChannelOp, Palette, SlotMap, ThemeDef, TokenDef } from "../dsl/types.js";
+import type { BrandFonts } from "../themes/customers/index.js";
+export declare function camelToKebab(str: string): string;
+export declare function tokenVar(name: string): string;
+export declare function paletteVar(name: string): string;
+/**
+ * Convert a ChannelOp to its CSS representation within oklch(from ...).
+ * - set  → literal value
+ * - delta → calc(channel +/- value)
+ * - cap  → min(channel, value)
+ */
+export declare function opToCSS(channel: string, op: ChannelOp): string;
+/**
+ * Assemble the full oklch(from var(...) ...) expression for a token.
+ *
+ * Slot-sourced token with ops:
+ *   oklch(from var(--psi-palette-sapphire) 0.65 min(c, 0.23) h)
+ *
+ * Ref-sourced token with alpha:
+ *   oklch(from var(--psi-fg-primary) l c h / 0.7)
+ *
+ * No-op (just a slot reference, no ops, no alpha):
+ *   var(--psi-palette-platinum)
+ */
+export declare function tokenToLiveCSS(def: TokenDef, slots: SlotMap): string;
+export declare function emitBaseCSS(palette: Palette): string;
+export declare function emitThemeCSS(themeName: string, theme: ThemeDef, palette: Palette, slots: SlotMap, opts?: {
+    fonts?: BrandFonts;
+    componentOverrides?: Record<string, string>;
+}): string;

package/dist/emit/css.js

@@ -0,0 +1,120 @@
+// ── Helpers ────────────────────────────────────────────────────────
+export function camelToKebab(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+export function tokenVar(name) {
+    return `--psi-${camelToKebab(name)}`;
+}
+export function paletteVar(name) {
+    return `--psi-palette-${name}`;
+}
+/**
+ * Convert a ChannelOp to its CSS representation within oklch(from ...).
+ * - set  → literal value
+ * - delta → calc(channel +/- value)
+ * - cap  → min(channel, value)
+ */
+export function opToCSS(channel, op) {
+    switch (op.op) {
+        case "set":
+            return `${op.value}`;
+        case "delta": {
+            const sign = op.value >= 0 ? "+" : "-";
+            const abs = Math.abs(op.value);
+            return `calc(${channel} ${sign} ${abs})`;
+        }
+        case "cap":
+            return `min(${channel}, ${op.value})`;
+    }
+}
+/**
+ * Assemble the full oklch(from var(...) ...) expression for a token.
+ *
+ * Slot-sourced token with ops:
+ *   oklch(from var(--psi-palette-sapphire) 0.65 min(c, 0.23) h)
+ *
+ * Ref-sourced token with alpha:
+ *   oklch(from var(--psi-fg-primary) l c h / 0.7)
+ *
+ * No-op (just a slot reference, no ops, no alpha):
+ *   var(--psi-palette-platinum)
+ */
+export function tokenToLiveCSS(def, slots) {
+    const hasOps = def.l || def.c || def.h;
+    const hasAlpha = def.alpha !== undefined;
+    // Determine the source CSS var
+    let sourceVar;
+    if (def.from.type === "slot") {
+        const paletteName = slots[def.from.name];
+        sourceVar = `var(${paletteVar(paletteName)})`;
+    }
+    else {
+        sourceVar = `var(${tokenVar(def.from.name)})`;
+    }
+    // If no operations and no alpha, just reference the var directly
+    if (!hasOps && !hasAlpha) {
+        return sourceVar;
+    }
+    // Build oklch(from ...) expression
+    const lPart = def.l ? opToCSS("l", def.l) : "l";
+    const cPart = def.c ? opToCSS("c", def.c) : "c";
+    const hPart = def.h ? opToCSS("h", def.h) : "h";
+    let expr = `oklch(from ${sourceVar} ${lPart} ${cPart} ${hPart}`;
+    if (hasAlpha) {
+        expr += ` / ${def.alpha}`;
+    }
+    expr += `)`;
+    return expr;
+}
+// ── Base CSS (palette) ────────────────────────────────────────────
+export function emitBaseCSS(palette) {
+    const lines = [];
+    lines.push("@layer psi.base, psi.theme, psi.components, psi.utilities;");
+    lines.push("");
+    lines.push("@layer psi.base {");
+    lines.push("  :root {");
+    for (const [name, entry] of Object.entries(palette)) {
+        lines.push(`    ${paletteVar(name)}: oklch(${entry.l} ${entry.c} ${entry.h});`);
+    }
+    lines.push("  }");
+    lines.push("}");
+    return lines.join("\n") + "\n";
+}
+// ── Theme CSS (semantic tokens) ───────────────────────────────────
+export function emitThemeCSS(themeName, theme, palette, slots, opts) {
+    const lines = [];
+    // Determine selector
+    const selector = themeName === "light"
+        ? `:root, [data-psi-theme="light"]`
+        : `[data-psi-theme="${themeName}"]`;
+    lines.push("@layer psi.theme {");
+    lines.push(`  ${selector} {`);
+    // Scope this theme's own palette vars inside its selector block so a
+    // customer brand's colors ship only with that theme, and two customers
+    // that happen to reuse an anchor name can't collide in a shared :root.
+    for (const [name, entry] of Object.entries(palette)) {
+        lines.push(`    ${paletteVar(name)}: oklch(${entry.l} ${entry.c} ${entry.h});`);
+    }
+    for (const [name, def] of Object.entries(theme)) {
+        const cssVar = tokenVar(name);
+        const value = tokenToLiveCSS(def, slots);
+        lines.push(`    ${cssVar}: ${value};`);
+    }
+    if (opts?.fonts) {
+        for (const [role, stack] of Object.entries(opts.fonts)) {
+            lines.push(`    --psi-font-${role}: ${stack};`);
+        }
+    }
+    lines.push("  }");
+    lines.push("}");
+    if (opts?.componentOverrides && Object.keys(opts.componentOverrides).length > 0) {
+        lines.push("@layer psi.components {");
+        lines.push(`  [data-psi-theme="${themeName}"] {`);
+        for (const [name, value] of Object.entries(opts.componentOverrides)) {
+            lines.push(`    --psi-${name}: ${value};`);
+        }
+        lines.push("  }");
+        lines.push("}");
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/gamut.d.ts

@@ -0,0 +1,4 @@
+import type { Palette, SlotMap, ThemeDef } from "./dsl/types.js";
+import type { ResolvedTheme } from "./dsl/resolver.js";
+/** Warn when sRGB clamping moved a resolved value by ΔE2000 > 2 (D19). */
+export declare function gamutWarnings(resolved: ResolvedTheme, theme: ThemeDef, palette: Palette, slots: SlotMap): string[];

package/dist/gamut.js

@@ -0,0 +1,44 @@
+import { differenceCiede2000 } from "culori";
+const dE = differenceCiede2000();
+function applyOp(base, op) {
+    if (!op)
+        return base;
+    if (op.op === "set")
+        return op.value;
+    if (op.op === "delta")
+        return base + op.value;
+    return Math.min(base, op.value); // cap
+}
+/** Warn when sRGB clamping moved a resolved value by ΔE2000 > 2 (D19). */
+export function gamutWarnings(resolved, theme, palette, slots) {
+    const warnings = [];
+    const raw = new Map();
+    // Recomputes pre-clamp OKLCH values by replaying token operations WITHOUT sRGB clamping.
+    // Unlike the resolver (which clamps at each step), this intentionally propagates unclamped values
+    // through ref chains so the warning reflects cumulative drift from authored intent. Do not "fix" this
+    // to match the resolver's clamping behavior — the unclamped result is required to diagnose palette issues.
+    function rawOf(name) {
+        const hit = raw.get(name);
+        if (hit)
+            return hit;
+        const def = theme[name];
+        const base = def.from.type === "slot"
+            ? palette[slots[def.from.name]]
+            : rawOf(def.from.name);
+        const val = {
+            l: applyOp(base.l, def.l),
+            c: applyOp(base.c, def.c),
+            h: applyOp(base.h, def.h),
+        };
+        raw.set(name, val);
+        return val;
+    }
+    for (const name of Object.keys(theme)) {
+        const pre = { mode: "oklch", ...rawOf(name) };
+        const post = { mode: "oklch", ...resolved[name].oklch };
+        const d = dE(pre, post);
+        if (d > 2)
+            warnings.push(`${name}: clamped ΔE ${d.toFixed(1)} (${JSON.stringify(rawOf(name))} → hex ${resolved[name].hex}) — adjust the palette anchor`);
+    }
+    return warnings;
+}

package/dist/scope-gate.d.ts

@@ -0,0 +1,15 @@
+import type { ThemeDef } from "./dsl/types.js";
+export interface ScopeViolation {
+    component: string;
+    key: string;
+    group: string;
+    token: string;
+    scopes: readonly string[];
+}
+/** D46 primary gate: every component token whose key declares a property
+ * group (-bg/-fg/-border) may only bind semantic tokens scoped to it. */
+export declare function checkScopes(componentVars: Record<string, Record<string, string>>, theme: ThemeDef): ScopeViolation[];
+/** Same gate for brand componentOverrides ("button-accent-bg": "..."):
+ * component resolved by longest known prefix; unknown prefixes are skipped
+ * (non-color overrides like media-tint carry no component token shape). */
+export declare function checkOverrideScopes(overrides: Record<string, string>, componentVars: Record<string, Record<string, string>>, theme: ThemeDef): ScopeViolation[];

package/dist/scope-gate.js

@@ -0,0 +1,87 @@
+import { PROPERTY_GROUPS, expandScopes, keyGroup } from "./scopes.js";
+const VAR_RE = /var\((--psi-[a-z0-9-]+)/g;
+const SCALE_RE = /^--psi-(space|size|radius|text|font|duration|ease|z)-/;
+const camelToKebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+/** Collect the semantic token names (camelCase) a component-token value
+ * ultimately binds, following component-token chains across the whole
+ * registry (own family and cross-family, e.g. dialog-bg → surface-bg).
+ * Unresolvable --psi- refs are returned as raw var names (prefixed "!")
+ * for the caller to flag. */
+function semanticRefs(component, value, all, kebabToName, seen = new Set()) {
+    const out = [];
+    for (const m of value.matchAll(VAR_RE)) {
+        const varName = m[1];
+        const bare = varName.slice("--psi-".length);
+        if (SCALE_RE.test(varName))
+            continue;
+        // Component refs resolve through the registry; longest prefix wins.
+        const owner = Object.keys(all)
+            .filter((c) => bare.startsWith(`${c}-`))
+            .sort((a, b) => b.length - a.length)[0];
+        if (owner !== undefined) {
+            const key = bare.slice(owner.length + 1);
+            const guard = `${owner}:${key}`;
+            if (seen.has(guard))
+                continue;
+            seen.add(guard);
+            const ownerValue = all[owner][key];
+            if (ownerValue === undefined) {
+                out.push(`!${varName}`);
+                continue;
+            }
+            out.push(...semanticRefs(owner, ownerValue, all, kebabToName, seen));
+            continue;
+        }
+        const name = kebabToName.get(bare);
+        out.push(name ?? `!${varName}`);
+    }
+    return out;
+}
+function checkOne(component, key, value, all, theme, kebabToName) {
+    const group = keyGroup(key);
+    if (!group)
+        return [];
+    const groupProps = new Set(PROPERTY_GROUPS[group]);
+    const violations = [];
+    for (const name of semanticRefs(component, value, all, kebabToName)) {
+        if (name.startsWith("!")) {
+            violations.push({ component, key, group, token: name.slice(1), scopes: [] });
+            continue;
+        }
+        const scopes = theme[name]?.scopes;
+        if (scopes === undefined)
+            continue; // unscoped tokens are valid everywhere
+        const allowed = scopes.includes(group) || expandScopes(scopes).some((p) => groupProps.has(p));
+        if (!allowed)
+            violations.push({ component, key, group, token: name, scopes });
+    }
+    return violations;
+}
+/** D46 primary gate: every component token whose key declares a property
+ * group (-bg/-fg/-border) may only bind semantic tokens scoped to it. */
+export function checkScopes(componentVars, theme) {
+    const kebabToName = new Map(Object.keys(theme).map((n) => [camelToKebab(n), n]));
+    const violations = [];
+    for (const [component, vars] of Object.entries(componentVars)) {
+        for (const [key, value] of Object.entries(vars)) {
+            violations.push(...checkOne(component, key, value, componentVars, theme, kebabToName));
+        }
+    }
+    return violations;
+}
+/** Same gate for brand componentOverrides ("button-accent-bg": "..."):
+ * component resolved by longest known prefix; unknown prefixes are skipped
+ * (non-color overrides like media-tint carry no component token shape). */
+export function checkOverrideScopes(overrides, componentVars, theme) {
+    const kebabToName = new Map(Object.keys(theme).map((n) => [camelToKebab(n), n]));
+    const components = Object.keys(componentVars).sort((a, b) => b.length - a.length);
+    const violations = [];
+    for (const [fullKey, value] of Object.entries(overrides)) {
+        const component = components.find((c) => fullKey.startsWith(`${c}-`));
+        if (!component)
+            continue;
+        const key = fullKey.slice(component.length + 1);
+        violations.push(...checkOne(component, key, value, componentVars, theme, kebabToName));
+    }
+    return violations;
+}

package/dist/scope-map.json

@@ -5,7 +5,8 @@
       "fill",
       "stroke",
       "caret-color",
-      "text-decoration-color"
+      "text-decoration-color",
+      "background-image"
     ],
     "surface": [
       "background",

package/dist/scopes.d.ts

@@ -0,0 +1,6 @@
+export declare const PROPERTY_GROUPS: Record<string, readonly string[]>;
+export declare const SUFFIX_GROUPS: Record<string, string>;
+export declare const SCALE_SCOPES: Record<string, readonly string[]>;
+export declare function isKnownScopeEntry(entry: string): boolean;
+export declare function expandScopes(scopes: readonly string[]): readonly string[];
+export declare function keyGroup(key: string): string | undefined;