design-constraint-validator 2.0.1 → 2.1.0

package/cli/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,MAAM,WAAW,cAAc;IAAG,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE;AAChH,MAAM,MAAM,SAAS,GAAG,eAAe,CAAC;AACxC,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;AACrD,MAAM,WAAW,aAAa;IAAG,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;CAAE;AAClE,MAAM,MAAM,aAAa,GAAG;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAA;CAAE,GAAG,aAAa,CAAC;AAE3F,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;IAChC,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AACD,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AACD,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;CACrC;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;IACpD,SAAS,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,UAAW,SAAQ,aAAa;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AACD,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,iBAAkB,SAAQ,aAAa;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AACD,YAAY,EAAE,UAAU,EAAE,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":"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"}

package/cli/types.ts

@@ -38,6 +38,8 @@ export interface BuildOptions extends GlobalOptions {
 export interface ValidateOptions extends GlobalOptions {
   strict?: boolean;
   constraints?: string[];
+  'tokens-path'?: string;
+  'constraints-dir'?: string;
   perf?: boolean;
   budgetTotalMs?: number;
   budgetPerBpMs?: number;

package/cli/validate-api.d.ts

@@ -0,0 +1,40 @@
+import { type TokenNode } from '../core/flatten.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import { type ConstraintViolation } from './json-output.js';
+import type { DcvConfig } from './types.js';
+export interface ValidateInput {
+    /** Inline tokens object (DTCG-style `$value`/`$type`). Takes precedence over `tokensPath`. */
+    tokens?: TokenNode;
+    /** Path to a tokens file. Used when `tokens` is not provided. */
+    tokensPath?: string;
+    /** Inline constraints config (the `constraints` block of dcv.config.json). Takes precedence over `configPath`. */
+    constraints?: DcvConfig['constraints'];
+    /** Path to a config file. When neither `constraints` nor `configPath` is given, a dcv.config.* in cwd is discovered. */
+    configPath?: string;
+    /** Directory holding order / cross-axis constraint files. Defaults to `themes`. */
+    constraintsDir?: string;
+    /** Optional breakpoint, selecting `<axis>.<bp>.order.json` / cross-axis variants. */
+    breakpoint?: Breakpoint;
+}
+export interface ValidateResult {
+    /** True when there are no error-level violations. */
+    ok: boolean;
+    counts: {
+        checked: number;
+        violations: number;
+        warnings: number;
+    };
+    violations: ConstraintViolation[];
+    warnings: ConstraintViolation[];
+    /** Set when tokens were validated but no active constraint referenced any of them. */
+    note?: string;
+}
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export declare function validate(input?: ValidateInput): ValidateResult;
+//# sourceMappingURL=validate-api.d.ts.map

package/cli/validate-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-api.d.ts","sourceRoot":"","sources":["validate-api.ts"],"names":[],"mappings":"AAYA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AAEnF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGzD,OAAO,EAAmB,KAAK,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kHAAkH;IAClH,WAAW,CAAC,EAAE,SAAS,CAAC,aAAa,CAAC,CAAC;IACvC,wHAAwH;IACxH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qFAAqF;IACrF,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAClE,UAAU,EAAE,mBAAmB,EAAE,CAAC;IAClC,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAChC,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyBD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,KAAK,GAAE,aAAkB,GAAG,cAAc,CAkDlE"}

package/cli/validate-api.js

@@ -0,0 +1,85 @@
+/**
+ * Programmatic validation API.
+ *
+ * A thin convenience wrapper over the same flatten + engine + constraint-registry
+ * machinery the CLI uses, so library consumers (and the MCP server) get one call
+ * that takes tokens + constraints and returns structured violations — no argv, no
+ * process.exit, no prose.
+ *
+ * Re-exported from the package root (`design-constraint-validator`) via
+ * `core/index.ts`.
+ */
+import fs from 'node:fs';
+import { flattenTokens } from '../core/flatten.js';
+import { Engine } from '../core/engine.js';
+import { loadConfig } from './config.js';
+import { setupConstraints, collectReferencedIds } from './constraint-registry.js';
+import { formatViolation } from './json-output.js';
+function readTokensFile(p) {
+    if (!fs.existsSync(p)) {
+        throw new Error(`Tokens file not found: ${p}`);
+    }
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        throw new Error(`Tokens file is not valid JSON: ${p} (${detail})`);
+    }
+}
+function resolveConfig(input) {
+    if (input.constraints !== undefined) {
+        return { constraints: input.constraints };
+    }
+    const res = loadConfig(input.configPath);
+    if (!res.ok) {
+        throw new Error(res.error);
+    }
+    return res.value;
+}
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export function validate(input = {}) {
+    const tokens = input.tokens !== undefined
+        ? input.tokens
+        : input.tokensPath !== undefined
+            ? readTokensFile(input.tokensPath)
+            : {};
+    const config = resolveConfig(input);
+    const { flat, edges } = flattenTokens(tokens);
+    const init = {};
+    for (const t of Object.values(flat)) {
+        init[t.id] = t.value;
+    }
+    const engine = new Engine(init, edges);
+    const knownIds = new Set(Object.keys(init));
+    const sources = setupConstraints(engine, { config, bp: input.breakpoint, constraintsDir: input.constraintsDir ?? 'themes' }, { knownIds });
+    const issues = engine.evaluate(knownIds);
+    const errors = issues.filter((i) => i.level === 'error');
+    const warnings = issues.filter((i) => i.level !== 'error');
+    // No-match note: validated tokens that no active constraint references.
+    const coverage = collectReferencedIds(sources);
+    let matched = false;
+    for (const id of coverage.ids) {
+        if (knownIds.has(id)) {
+            matched = true;
+            break;
+        }
+    }
+    const note = knownIds.size > 0 && coverage.coverageKnown && !matched
+        ? `No active constraint references any of the ${knownIds.size} validated token(s) — nothing was checked. ` +
+            `Define constraints (constraints.wcag / constraints.thresholds) or point constraintsDir at your order/cross-axis files.`
+        : undefined;
+    return {
+        ok: errors.length === 0,
+        counts: { checked: issues.length, violations: errors.length, warnings: warnings.length },
+        violations: errors.map(formatViolation),
+        warnings: warnings.map(formatViolation),
+        note,
+    };
+}

package/cli/validate-api.ts

@@ -0,0 +1,126 @@
+/**
+ * Programmatic validation API.
+ *
+ * A thin convenience wrapper over the same flatten + engine + constraint-registry
+ * machinery the CLI uses, so library consumers (and the MCP server) get one call
+ * that takes tokens + constraints and returns structured violations — no argv, no
+ * process.exit, no prose.
+ *
+ * Re-exported from the package root (`design-constraint-validator`) via
+ * `core/index.ts`.
+ */
+import fs from 'node:fs';
+import { flattenTokens, type TokenNode, type FlatToken } from '../core/flatten.js';
+import { Engine, type ConstraintIssue } from '../core/engine.js';
+import type { Breakpoint } from '../core/breakpoints.js';
+import { loadConfig } from './config.js';
+import { setupConstraints, collectReferencedIds } from './constraint-registry.js';
+import { formatViolation, type ConstraintViolation } from './json-output.js';
+import type { DcvConfig } from './types.js';
+
+export interface ValidateInput {
+  /** Inline tokens object (DTCG-style `$value`/`$type`). Takes precedence over `tokensPath`. */
+  tokens?: TokenNode;
+  /** Path to a tokens file. Used when `tokens` is not provided. */
+  tokensPath?: string;
+  /** Inline constraints config (the `constraints` block of dcv.config.json). Takes precedence over `configPath`. */
+  constraints?: DcvConfig['constraints'];
+  /** Path to a config file. When neither `constraints` nor `configPath` is given, a dcv.config.* in cwd is discovered. */
+  configPath?: string;
+  /** Directory holding order / cross-axis constraint files. Defaults to `themes`. */
+  constraintsDir?: string;
+  /** Optional breakpoint, selecting `<axis>.<bp>.order.json` / cross-axis variants. */
+  breakpoint?: Breakpoint;
+}
+
+export interface ValidateResult {
+  /** True when there are no error-level violations. */
+  ok: boolean;
+  counts: { checked: number; violations: number; warnings: number };
+  violations: ConstraintViolation[];
+  warnings: ConstraintViolation[];
+  /** Set when tokens were validated but no active constraint referenced any of them. */
+  note?: string;
+}
+
+function readTokensFile(p: string): TokenNode {
+  if (!fs.existsSync(p)) {
+    throw new Error(`Tokens file not found: ${p}`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8')) as TokenNode;
+  } catch (e) {
+    const detail = e instanceof Error ? e.message : String(e);
+    throw new Error(`Tokens file is not valid JSON: ${p} (${detail})`);
+  }
+}
+
+function resolveConfig(input: ValidateInput): DcvConfig {
+  if (input.constraints !== undefined) {
+    return { constraints: input.constraints };
+  }
+  const res = loadConfig(input.configPath);
+  if (!res.ok) {
+    throw new Error(res.error);
+  }
+  return res.value;
+}
+
+/**
+ * Validate a token set against constraints and return structured results.
+ *
+ * Unlike the CLI, this treats `tokens` / `tokensPath` as the complete token set
+ * (no implicit cwd token overrides), so it is safe to call from a server that
+ * cannot share a filesystem with the caller.
+ */
+export function validate(input: ValidateInput = {}): ValidateResult {
+  const tokens: TokenNode =
+    input.tokens !== undefined
+      ? input.tokens
+      : input.tokensPath !== undefined
+        ? readTokensFile(input.tokensPath)
+        : {};
+
+  const config = resolveConfig(input);
+
+  const { flat, edges } = flattenTokens(tokens);
+  const init: Record<string, string | number> = {};
+  for (const t of Object.values(flat)) {
+    init[(t as FlatToken).id] = (t as FlatToken).value;
+  }
+  const engine = new Engine(init, edges);
+  const knownIds = new Set(Object.keys(init));
+
+  const sources = setupConstraints(
+    engine,
+    { config, bp: input.breakpoint, constraintsDir: input.constraintsDir ?? 'themes' },
+    { knownIds },
+  );
+
+  const issues = engine.evaluate(knownIds);
+  const errors = issues.filter((i: ConstraintIssue) => i.level === 'error');
+  const warnings = issues.filter((i: ConstraintIssue) => i.level !== 'error');
+
+  // No-match note: validated tokens that no active constraint references.
+  const coverage = collectReferencedIds(sources);
+  let matched = false;
+  for (const id of coverage.ids) {
+    if (knownIds.has(id)) {
+      matched = true;
+      break;
+    }
+  }
+  const note =
+    knownIds.size > 0 && coverage.coverageKnown && !matched
+      ? `No active constraint references any of the ${knownIds.size} validated token(s) — nothing was checked. ` +
+        `Define constraints (constraints.wcag / constraints.thresholds) or point constraintsDir at your order/cross-axis files.`
+      : undefined;
+
+  return {
+    ok: errors.length === 0,
+    counts: { checked: issues.length, violations: errors.length, warnings: warnings.length },
+    violations: errors.map(formatViolation),
+    warnings: warnings.map(formatViolation),
+    note,
+  };
+}

package/core/breakpoints.d.ts

@@ -6,7 +6,13 @@ export declare function loadOrders(axis: string, bp?: Breakpoint): [string, "<="
 export declare function mergeTokens(base: unknown, overlay: unknown): TokenNode;
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export declare function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode;
+export declare function loadTokensWithBreakpoint(bp?: Breakpoint, tokensPath?: string): TokenNode;
 //# sourceMappingURL=breakpoints.d.ts.map

package/core/breakpoints.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,GAAG,SAAS,CAKnE"}
+{"version":3,"file":"breakpoints.d.ts","sourceRoot":"","sources":["breakpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE5C,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,EAAE,CAM7D;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAOhE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,UAAU,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,EAAE,CAKzF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,SAAS,CAQtE;AAED,gFAAgF;AAChF;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,CAAC,EAAE,UAAU,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAkBxF"}

package/core/breakpoints.js

@@ -38,10 +38,31 @@ export function mergeTokens(base, overlay) {
 }
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export function loadTokensWithBreakpoint(bp) {
-    const base = loadJsonSafe("tokens/tokens.example.json") ?? {};
+export function loadTokensWithBreakpoint(bp, tokensPath) {
+    let base;
+    if (tokensPath !== undefined) {
+        if (!fs.existsSync(tokensPath)) {
+            throw new Error(`Tokens file not found: ${tokensPath}`);
+        }
+        try {
+            base = JSON.parse(fs.readFileSync(tokensPath, "utf8"));
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            throw new Error(`Tokens file is not valid JSON: ${tokensPath} (${detail})`);
+        }
+    }
+    else {
+        base = loadJsonSafe("tokens/tokens.example.json") ?? {};
+    }
     const local = loadJsonSafe("tokens/overrides/local.json");
     const ov = bp ? loadJsonSafe(`tokens/overrides/${bp}.json`) : null;
     return mergeTokens(mergeTokens(base, local), ov);

package/core/breakpoints.ts

@@ -40,10 +40,29 @@ export function mergeTokens(base: unknown, overlay: unknown): TokenNode {
 
 /** Load tokens with optional breakpoint override: base + overrides/<bp>.json */
 /**
- * Load tokens with override precedence: base < local < breakpoint
+ * Load tokens with override precedence: base < local < breakpoint.
+ *
+ * @param bp          optional breakpoint overlay (tokens/overrides/<bp>.json).
+ * @param tokensPath  explicit base tokens file. When provided, a missing or
+ *                    invalid file throws — callers must never silently validate
+ *                    an empty token set. When omitted, defaults to the repo
+ *                    example file and stays lenient (backward-compatible).
  */
-export function loadTokensWithBreakpoint(bp?: Breakpoint): TokenNode {
-  const base = loadJsonSafe<TokenNode>("tokens/tokens.example.json") ?? {};
+export function loadTokensWithBreakpoint(bp?: Breakpoint, tokensPath?: string): TokenNode {
+  let base: TokenNode;
+  if (tokensPath !== undefined) {
+    if (!fs.existsSync(tokensPath)) {
+      throw new Error(`Tokens file not found: ${tokensPath}`);
+    }
+    try {
+      base = JSON.parse(fs.readFileSync(tokensPath, "utf8")) as TokenNode;
+    } catch (e) {
+      const detail = e instanceof Error ? e.message : String(e);
+      throw new Error(`Tokens file is not valid JSON: ${tokensPath} (${detail})`);
+    }
+  } else {
+    base = loadJsonSafe<TokenNode>("tokens/tokens.example.json") ?? {};
+  }
   const local = loadJsonSafe<TokenNode>("tokens/overrides/local.json");
   const ov = bp ? loadJsonSafe<TokenNode>(`tokens/overrides/${bp}.json`) : null;
   return mergeTokens(mergeTokens(base, local), ov);

package/core/color.js

@@ -74,7 +74,7 @@ export function parseCssColor(input) {
         const C = Math.max(0, num(m[2]));
         const h = ((num(m[3]) % 360) + 360) % 360;
         const a = m[4] ? (m[4].includes("%") ? pct(m[4]) : num(m[4])) : 1;
-        const [r, g, b] = oklchToSrgb(L, C, h).map(v => clamp255(v * 255));
+        const [r, g, b] = oklchToLinearSrgb(L, C, h).map(v => linToSrgb(v));
         return { r, g, b, a: clamp01(a) };
     }
     // named "transparent"
@@ -103,8 +103,8 @@ function hslToRgb(H, S, L) {
     const m = L - C / 2;
     return { r: clamp255((r + m) * 255), g: clamp255((g + m) * 255), b: clamp255((b + m) * 255), a: 1 };
 }
-/* ---------- OKLCH → sRGB (0..1 channels) ---------- */
-function oklchToSrgb(L, C, hDeg) {
+/* ---------- OKLCH → linear sRGB (0..1 channels) ---------- */
+function oklchToLinearSrgb(L, C, hDeg) {
     const h = (hDeg * Math.PI) / 180;
     // OKLCH -> OKLab
     const a = C * Math.cos(h);
@@ -118,7 +118,7 @@ function oklchToSrgb(L, C, hDeg) {
     const R = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
     const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
     const B = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
-    // clamp to [0,1] (gamut clip)
+    // clamp to [0,1] (gamut clip). Callers gamma-encode to sRGB.
     return [clamp01(R), clamp01(G), clamp01(B)];
 }
 /* ---------- Alpha compositing (linear light) ---------- */

package/core/color.ts

@@ -87,7 +87,7 @@ export function parseCssColor(input: string | undefined | null): RGBA | null {
     const C = Math.max(0, num(m[2]));
     const h = ((num(m[3]) % 360) + 360) % 360;
     const a = m[4] ? (m[4].includes("%") ? pct(m[4]) : num(m[4])) : 1;
-    const [r, g, b] = oklchToSrgb(L, C, h).map(v => clamp255(v * 255));
+    const [r, g, b] = oklchToLinearSrgb(L, C, h).map(v => linToSrgb(v));
     return { r, g, b, a: clamp01(a) };
   }
 
@@ -113,8 +113,8 @@ function hslToRgb(H: number, S: number, L: number): RGBA {
   return { r: clamp255((r + m) * 255), g: clamp255((g + m) * 255), b: clamp255((b + m) * 255), a: 1 };
 }
 
-/* ---------- OKLCH → sRGB (0..1 channels) ---------- */
-function oklchToSrgb(L: number, C: number, hDeg: number): [number, number, number] {
+/* ---------- OKLCH → linear sRGB (0..1 channels) ---------- */
+function oklchToLinearSrgb(L: number, C: number, hDeg: number): [number, number, number] {
   const h = (hDeg * Math.PI) / 180;
   // OKLCH -> OKLab
   const a = C * Math.cos(h);
@@ -128,7 +128,7 @@ function oklchToSrgb(L: number, C: number, hDeg: number): [number, number, numbe
   const R = +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
   const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
   const B = -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s;
-  // clamp to [0,1] (gamut clip)
+  // clamp to [0,1] (gamut clip). Callers gamma-encode to sRGB.
   return [clamp01(R), clamp01(G), clamp01(B)];
 }
 

package/core/constraints/monotonic-lightness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"monotonic-lightness.d.ts","sourceRoot":"","sources":["monotonic-lightness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOxD;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAuBpE"}
+{"version":3,"file":"monotonic-lightness.d.ts","sourceRoot":"","sources":["monotonic-lightness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAGrD,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAYxD;AAED,MAAM,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;AAElD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,gBAAgB,CAuBpE"}

package/core/constraints/monotonic-lightness.js

@@ -2,11 +2,15 @@ import { parseCssColor, relativeLuminance } from "../color.js";
 export function parseLightness(v) {
     if (typeof v !== "string")
         return null;
-    const s = v.trim().toLowerCase();
-    const m = /^oklch\(\s*([0-9.]+%?)\s+/.exec(s);
-    if (m)
-        return m[1].includes("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
-    const rgba = parseCssColor(s);
+    // ONE consistent lightness scale for every format. parseCssColor handles
+    // hex / rgb / hsl / oklch (oklch→sRGB is the verified TASK-005 pipeline), so we
+    // always compare WCAG relative luminance.
+    //
+    // BUG FIXED (TASK-009): oklch() previously short-circuited to its raw perceptual
+    // L coordinate — a DIFFERENT scale from the relative luminance used for hex. A
+    // scale mixing the two formats then compared incomparable numbers (e.g. oklch L
+    // 0.60 vs hex luminance 0.216 for the same gray), yielding false pass/fail.
+    const rgba = parseCssColor(v.trim());
     return rgba ? relativeLuminance(rgba) : null;
 }
 export function MonotonicLightness(orders) {

package/core/constraints/monotonic-lightness.ts

@@ -3,10 +3,15 @@ import { parseCssColor, relativeLuminance } from "../color.js";
 
 export function parseLightness(v: unknown): number | null {
   if (typeof v !== "string") return null;
-  const s = v.trim().toLowerCase();
-  const m = /^oklch\(\s*([0-9.]+%?)\s+/.exec(s);
-  if (m) return m[1].includes("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
-  const rgba = parseCssColor(s);
+  // ONE consistent lightness scale for every format. parseCssColor handles
+  // hex / rgb / hsl / oklch (oklch→sRGB is the verified TASK-005 pipeline), so we
+  // always compare WCAG relative luminance.
+  //
+  // BUG FIXED (TASK-009): oklch() previously short-circuited to its raw perceptual
+  // L coordinate — a DIFFERENT scale from the relative luminance used for hex. A
+  // scale mixing the two formats then compared incomparable numbers (e.g. oklch L
+  // 0.60 vs hex luminance 0.216 for the same gray), yielding false pass/fail.
+  const rgba = parseCssColor(v.trim());
   return rgba ? relativeLuminance(rgba) : null;
 }
 

package/core/constraints/wcag.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wcag.d.ts","sourceRoot":"","sources":["wcag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC7B,CAAC;AASF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAiD1E"}
+{"version":3,"file":"wcag.d.ts","sourceRoot":"","sources":["wcag.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,MAAM,MAAM,YAAY,GAAG;IACzB,EAAE,EAAE,OAAO,CAAC;IACZ,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC7B,CAAC;AASF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,gBAAgB,CAuD1E"}

package/core/constraints/wcag.js

@@ -26,6 +26,7 @@ export function WcagContrastPlugin(pairs) {
                         rule: "wcag-contrast",
                         level: "warn",
                         where: p.where,
+                        involvedTokens: [p.fg, p.bg],
                         message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
                     });
                     continue;
@@ -43,6 +44,11 @@ export function WcagContrastPlugin(pairs) {
                         rule: "wcag-contrast",
                         level: "error",
                         where: p.where,
+                        involvedTokens: [p.fg, p.bg],
+                        metadata: {
+                            actual: Number(ratio.toFixed(2)),
+                            required: p.min
+                        },
                         message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
                     });
                 }

package/core/constraints/wcag.ts

@@ -40,6 +40,7 @@ export function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin {
             rule: "wcag-contrast",
             level: "warn" as const,
             where: p.where,
+            involvedTokens: [p.fg, p.bg],
             message: `Unparseable color(s): fg="${fgStr}" bg="${bgStr}" backdrop="${backdropStr}"`
           });
           continue;
@@ -60,6 +61,11 @@ export function WcagContrastPlugin(pairs: ContrastPair[]): ConstraintPlugin {
             rule: "wcag-contrast",
             level: "error" as const,
             where: p.where,
+            involvedTokens: [p.fg, p.bg],
+            metadata: {
+              actual: Number(ratio.toFixed(2)),
+              required: p.min
+            },
             message: `Contrast ${ratio.toFixed(2)}:1 < ${p.min}:1`
           });
         }

package/core/dtcg.d.ts

@@ -0,0 +1,38 @@
+/**
+ * DTCG 2025.10 stable-spec value normalization.
+ *
+ * The stable spec (2025-10-28) made color and dimension tokens **structured
+ * objects** rather than CSS strings — e.g. Figma's native export emits
+ *   { "colorSpace": "srgb", "components": [0.53, 0.53, 0.53], "alpha": 1, "hex": "#888888" }
+ * and
+ *   { "value": 16, "unit": "px" }.
+ *
+ * The engine and constraint plugins (WCAG, threshold, monotonic) consume the
+ * legacy string/number forms. We normalize structured values to those forms in
+ * ONE place — the flatten boundary — so `core/color.ts`'s verified math stays
+ * untouched and string aliases (`"{dot.path}"`) keep flowing through unchanged.
+ *
+ * Non-sRGB color spaces are deliberately NOT coerced into sRGB math: we refuse
+ * to treat e.g. display-p3 components as sRGB (that would silently corrupt
+ * contrast). Without a `hex` fallback they normalize to a sentinel string that
+ * the color parser rejects, producing an explicit "Unparseable color(s)"
+ * warning naming the color space — never a wrong-but-silent ratio.
+ */
+export type DtcgColorValue = {
+    colorSpace?: string;
+    components?: number[];
+    alpha?: number;
+    hex?: string;
+};
+export type DtcgDimensionValue = {
+    value?: number;
+    unit?: string;
+};
+/**
+ * Normalize a raw DTCG `$value` to the string/number form the engine expects.
+ * Strings (including `"{alias}"` references) and numbers pass through untouched.
+ * Structured objects are converted; unrecognized objects (composite types such
+ * as typography/shadow — out of scope) become a non-crashing sentinel string.
+ */
+export declare function normalizeDtcgValue(raw: unknown, type?: string): string | number;
+//# sourceMappingURL=dtcg.d.ts.map

package/core/dtcg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dtcg.d.ts","sourceRoot":"","sources":["dtcg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAsDF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAU/E"}