design-constraint-validator 1.1.0 → 2.1.0

package/cli/version-banner.ts

@@ -0,0 +1,61 @@
+/**
+ * Version banner utility
+ * Displays DCV version info when validation runs
+ */
+
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+interface PackageJson {
+  name: string;
+  version: string;
+  homepage?: string;
+}
+
+let cachedPkg: PackageJson | null = null;
+
+function getPackageInfo(): PackageJson {
+  if (cachedPkg) return cachedPkg;
+
+  try {
+    const pkgPath = join(__dirname, '../package.json');
+    const pkgContent = readFileSync(pkgPath, 'utf-8');
+    cachedPkg = JSON.parse(pkgContent);
+    return cachedPkg!;
+  } catch {
+    // Fallback if package.json not found
+    return {
+      name: 'design-constraint-validator',
+      version: '2.0.0',
+      homepage: 'https://github.com/CseperkePapp/design-constraint-validator'
+    };
+  }
+}
+
+/**
+ * Print DCV version banner
+ * Shows: DCV v{version} | {repo_url}
+ */
+export function printVersionBanner(options?: { quiet?: boolean }): void {
+  if (options?.quiet) return;
+
+  const pkg = getPackageInfo();
+  const repoUrl = pkg.homepage || 'https://github.com/CseperkePapp/design-constraint-validator';
+
+  console.log(`\x1b[2m${pkg.name} v${pkg.version} | ${repoUrl}\x1b[0m`);
+}
+
+/**
+ * Get version string for JSON output
+ */
+export function getVersionInfo(): { name: string; version: string; repository: string } {
+  const pkg = getPackageInfo();
+  return {
+    name: pkg.name,
+    version: pkg.version,
+    repository: pkg.homepage || 'https://github.com/CseperkePapp/design-constraint-validator'
+  };
+}

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

package/core/dtcg.js

@@ -0,0 +1,88 @@
+/**
+ * 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.
+ */
+function toByte(c) {
+    return Math.max(0, Math.min(255, Math.round(c * 255)));
+}
+function srgbComponentsToCss(c) {
+    if (!Array.isArray(c.components) || c.components.length < 3)
+        return null;
+    const [r, g, b] = c.components;
+    if (![r, g, b].every((n) => typeof n === 'number' && Number.isFinite(n)))
+        return null;
+    const a = typeof c.alpha === 'number' ? c.alpha : 1;
+    const R = toByte(r);
+    const G = toByte(g);
+    const B = toByte(b);
+    if (a >= 1) {
+        const hx = (n) => n.toString(16).padStart(2, '0');
+        return `#${hx(R)}${hx(G)}${hx(B)}`;
+    }
+    return `rgba(${R}, ${G}, ${B}, ${a})`;
+}
+function normalizeColor(v) {
+    // Prefer the spec's `hex` convenience field when present (works for any space).
+    if (typeof v.hex === 'string' && v.hex.trim())
+        return v.hex.trim();
+    // Only gamma-encoded sRGB components map 1:1 to the existing color math.
+    if ((v.colorSpace ?? '').toLowerCase() === 'srgb') {
+        const css = srgbComponentsToCss(v);
+        if (css)
+            return css;
+    }
+    // Unsupported space with no hex fallback → sentinel the parser rejects.
+    return `<unsupported colorSpace: ${v.colorSpace ?? 'unknown'}>`;
+}
+function normalizeDimension(v) {
+    if (typeof v.value !== 'number' || !Number.isFinite(v.value)) {
+        return '<invalid dimension>';
+    }
+    const unit = typeof v.unit === 'string' && v.unit ? v.unit : 'px';
+    return `${v.value}${unit}`;
+}
+function isColorObject(obj, type) {
+    return ((type ?? '').toLowerCase() === 'color' ||
+        'colorSpace' in obj ||
+        'components' in obj ||
+        'hex' in obj);
+}
+function isDimensionObject(obj, type) {
+    return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+}
+/**
+ * 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 function normalizeDtcgValue(raw, type) {
+    if (typeof raw === 'string' || typeof raw === 'number')
+        return raw;
+    if (raw && typeof raw === 'object') {
+        const obj = raw;
+        if (isColorObject(obj, type))
+            return normalizeColor(obj);
+        if (isDimensionObject(obj, type))
+            return normalizeDimension(obj);
+        return `<unsupported $value: ${(type ?? 'object').toLowerCase()}>`;
+    }
+    // null / undefined / boolean — return an empty string so nothing downstream crashes.
+    return '';
+}

package/core/dtcg.ts

@@ -0,0 +1,102 @@
+/**
+ * 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;
+};
+
+function toByte(c: number): number {
+  return Math.max(0, Math.min(255, Math.round(c * 255)));
+}
+
+function srgbComponentsToCss(c: DtcgColorValue): string | null {
+  if (!Array.isArray(c.components) || c.components.length < 3) return null;
+  const [r, g, b] = c.components;
+  if (![r, g, b].every((n) => typeof n === 'number' && Number.isFinite(n))) return null;
+  const a = typeof c.alpha === 'number' ? c.alpha : 1;
+  const R = toByte(r);
+  const G = toByte(g);
+  const B = toByte(b);
+  if (a >= 1) {
+    const hx = (n: number) => n.toString(16).padStart(2, '0');
+    return `#${hx(R)}${hx(G)}${hx(B)}`;
+  }
+  return `rgba(${R}, ${G}, ${B}, ${a})`;
+}
+
+function normalizeColor(v: DtcgColorValue): string {
+  // Prefer the spec's `hex` convenience field when present (works for any space).
+  if (typeof v.hex === 'string' && v.hex.trim()) return v.hex.trim();
+  // Only gamma-encoded sRGB components map 1:1 to the existing color math.
+  if ((v.colorSpace ?? '').toLowerCase() === 'srgb') {
+    const css = srgbComponentsToCss(v);
+    if (css) return css;
+  }
+  // Unsupported space with no hex fallback → sentinel the parser rejects.
+  return `<unsupported colorSpace: ${v.colorSpace ?? 'unknown'}>`;
+}
+
+function normalizeDimension(v: DtcgDimensionValue): string {
+  if (typeof v.value !== 'number' || !Number.isFinite(v.value)) {
+    return '<invalid dimension>';
+  }
+  const unit = typeof v.unit === 'string' && v.unit ? v.unit : 'px';
+  return `${v.value}${unit}`;
+}
+
+function isColorObject(obj: Record<string, unknown>, type?: string): boolean {
+  return (
+    (type ?? '').toLowerCase() === 'color' ||
+    'colorSpace' in obj ||
+    'components' in obj ||
+    'hex' in obj
+  );
+}
+
+function isDimensionObject(obj: Record<string, unknown>, type?: string): boolean {
+  return (type ?? '').toLowerCase() === 'dimension' || ('value' in obj && 'unit' in obj);
+}
+
+/**
+ * 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 function normalizeDtcgValue(raw: unknown, type?: string): string | number {
+  if (typeof raw === 'string' || typeof raw === 'number') return raw;
+  if (raw && typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>;
+    if (isColorObject(obj, type)) return normalizeColor(obj as DtcgColorValue);
+    if (isDimensionObject(obj, type)) return normalizeDimension(obj as DtcgDimensionValue);
+    return `<unsupported $value: ${(type ?? 'object').toLowerCase()}>`;
+  }
+  // null / undefined / boolean — return an empty string so nothing downstream crashes.
+  return '';
+}

package/core/engine.d.ts

@@ -26,6 +26,12 @@ export type ConstraintIssue = {
      * this captures that reference edge.
      */
     involvedEdges?: Array<[TokenId, TokenId]>;
+    /**
+     * Structured, rule-specific data for JSON consumers.
+     * For example, WCAG contrast issues can expose actual/required ratios here
+     * without forcing callers to parse human-readable messages.
+     */
+    metadata?: Record<string, unknown>;
 };
 /**
  * Constraint plugin interface.

package/core/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,EAAE;IAItB;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;IAI5C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;IAE1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,eAAe,EAAE,CAAC;CACvE,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;AAE/C,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAAkC;IAChD,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,OAAO,CAA0B;gBAE7B,UAAU,EAAE,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IASrF,GAAG,CAAC,MAAM,EAAE,gBAAgB;IAE5B,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IACxC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;IAElC;;;;;;;OAOG;IACH,SAAS,IAAI,OAAO,EAAE;IAItB;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC;IAI5C,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IAatC,QAAQ,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,CAAC;IAIjC,2FAA2F;IAC3F,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU;;;;;CAQtC"}

package/core/engine.ts

@@ -29,6 +29,13 @@ export type ConstraintIssue = {
    * this captures that reference edge.
    */
   involvedEdges?: Array<[TokenId, TokenId]>;
+
+  /**
+   * Structured, rule-specific data for JSON consumers.
+   * For example, WCAG contrast issues can expose actual/required ratios here
+   * without forcing callers to parse human-readable messages.
+   */
+  metadata?: Record<string, unknown>;
 };
 
 /**

package/core/flatten.d.ts

@@ -1,15 +1,17 @@
 export type TokenId = string;
 export type TokenValue = string | number;
+export type DtcgStructuredValue = Record<string, unknown>;
 export type TokenNode = {
     $type?: string;
-    $value?: TokenValue;
-    [k: string]: TokenNode | string | number | undefined;
+    $value?: TokenValue | DtcgStructuredValue;
+    $extensions?: DtcgStructuredValue;
+    [k: string]: TokenNode | string | number | DtcgStructuredValue | undefined;
 };
 export type FlatToken = {
     id: TokenId;
     type: string;
     value: TokenValue;
-    raw: TokenValue;
+    raw: TokenValue | DtcgStructuredValue;
     refs: TokenId[];
 };
 export type FlattenResult = {

package/core/flatten.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["flatten.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AACzC,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CACtD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,CAAC;IAChB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAIF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CA4F5D"}
+{"version":3,"file":"flatten.d.ts","sourceRoot":"","sources":["flatten.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAC;AAGzC,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1D,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,UAAU,GAAG,mBAAmB,CAAC;IAC1C,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;CAC5E,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,GAAG,EAAE,UAAU,GAAG,mBAAmB,CAAC;IACtC,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACjC,KAAK,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5C,CAAC;AAKF,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CA4G5D"}