@handamade/psi-tokens 0.18.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/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/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;