design-constraint-validator 2.0.1 → 2.2.0

package/core/constraints/monotonic.ts

@@ -12,11 +12,25 @@ export function MonotonicPlugin(
     evaluate(engine, candidates) {
       const issues = [];
       for (const [a, op, b] of orders) {
-        const va = parse(engine.get(a));
-        const vb = parse(engine.get(b));
-        if (va == null || vb == null) continue; // skip unparseable
+        if (!candidates.has(a) && !candidates.has(b)) continue; // incremental
+        const rawA = engine.get(a);
+        const rawB = engine.get(b);
+        const va = parse(rawA);
+        const vb = parse(rawB);
+        // A present-but-unparseable size operand (e.g. "50%", "10vw") can't be
+        // compared — warn instead of silently skipping (TASK-031).
+        if ((rawA != null && rawA !== "" && va == null) || (rawB != null && rawB !== "" && vb == null)) {
+          issues.push({
+            id: `${a}|${b}`,
+            rule: "monotonic",
+            level: "warn" as const,
+            message: `Cannot check ${a} ${op} ${b}: unparseable size value(s)`
+          });
+          continue;
+        }
+        if (va == null || vb == null) continue; // operand absent — nothing to check
         const ok = op === ">=" ? va >= vb : va <= vb;
-        if (!ok && (candidates.has(a) || candidates.has(b))) {
+        if (!ok) {
           issues.push({
             id: `${a}|${b}`,
             rule: "monotonic",
@@ -30,14 +44,21 @@ export function MonotonicPlugin(
   };
 }
 
-// a minimal parser for "rem"/"px" numbers
+// Parse a size to px for comparison. Coerces bare numbers and unitless strings to
+// px (TASK-031: numeric `$value` and aliases-to-numbers previously returned null,
+// silently skipping the rule). `rem`/`em` are 16px-relative. Returns null only for
+// genuinely unparseable operands (e.g. "50%", "10vw") — callers warn, not skip.
 export const parseSize = (v: unknown): number | null => {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null; // bare number == px
   if (typeof v !== "string") return null;
-  const m = v.trim().match(/^([0-9.]+)(rem|px)?$/i);
+  // Real number only: rejects ".", "5.", "1.2.3px" (which previously slipped
+  // through `[0-9.]+` + parseFloat as NaN/garbage and became spurious errors).
+  const m = v.trim().match(/^(\d*\.?\d+)\s*(px|rem|em)?$/i);
   if (!m) return null;
   const num = parseFloat(m[1]);
-  const unit = (m[2] || "rem").toLowerCase();
-  return unit === "px" ? num : num * 16; // assume 1rem=16px for comparisons
+  if (!Number.isFinite(num)) return null;
+  const unit = (m[2] || "px").toLowerCase();
+  return unit === "rem" || unit === "em" ? num * 16 : num; // px and unitless as-is
 };
 
 // Parser for unitless numbers (like scale factors)

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

@@ -1 +1 @@
-{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["threshold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,CAAC;AAWF,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,SAAc,GAAG,gBAAgB,CAuB9F"}
+{"version":3,"file":"threshold.d.ts","sourceRoot":"","sources":["threshold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CAC1B,CAAC;AAiBF,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,MAAM,SAAc,GAAG,gBAAgB,CAoC9F"}

package/core/constraints/threshold.js

@@ -1,12 +1,20 @@
+// Coerces bare numbers and unitless strings to px (TASK-031: numeric `$value`
+// previously returned null, silently skipping the threshold). `rem`/`em` are
+// 16px-relative. Returns null only for genuinely unparseable operands.
 const parseSizePx = (v) => {
+    if (typeof v === "number")
+        return Number.isFinite(v) ? v : null;
     if (typeof v !== "string")
         return null;
-    const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
+    // Real number only — rejects ".", "5.", "1.2.3px" (TASK-034).
+    const m = v.trim().match(/^(\d*\.?\d+)\s*(px|rem|em)?$/i);
     if (!m)
         return null;
     const n = parseFloat(m[1]);
+    if (!Number.isFinite(n))
+        return null;
     const unit = (m[2] || "px").toLowerCase();
-    return unit === "rem" ? n * 16 : n;
+    return unit === "rem" || unit === "em" ? n * 16 : n;
 };
 export function ThresholdPlugin(rules, ruleId = "threshold") {
     return {
@@ -16,9 +24,21 @@ export function ThresholdPlugin(rules, ruleId = "threshold") {
             for (const r of rules) {
                 if (!candidates.has(r.id))
                     continue; // incremental
-                const px = parseSizePx(engine.get(r.id));
-                if (px == null)
+                const raw = engine.get(r.id);
+                const px = parseSizePx(raw);
+                if (px == null) {
+                    // Present-but-unparseable size — warn instead of silently skipping (TASK-031).
+                    if (raw != null && raw !== "") {
+                        issues.push({
+                            id: r.id,
+                            rule: ruleId,
+                            level: "warn",
+                            where: r.where,
+                            message: `Cannot check ${r.id} ${r.op} ${r.valuePx}px: unparseable size value`
+                        });
+                    }
                     continue;
+                }
                 const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
                 if (!ok) {
                     issues.push({

package/core/constraints/threshold.ts

@@ -8,13 +8,19 @@ export type ThresholdRule = {
   level?: "error" | "warn";      // default error
 };
 
+// Coerces bare numbers and unitless strings to px (TASK-031: numeric `$value`
+// previously returned null, silently skipping the threshold). `rem`/`em` are
+// 16px-relative. Returns null only for genuinely unparseable operands.
 const parseSizePx = (v: unknown): number | null => {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
   if (typeof v !== "string") return null;
-  const m = v.trim().match(/^([0-9.]+)\s*(px|rem)?$/i);
+  // Real number only — rejects ".", "5.", "1.2.3px" (TASK-034).
+  const m = v.trim().match(/^(\d*\.?\d+)\s*(px|rem|em)?$/i);
   if (!m) return null;
   const n = parseFloat(m[1]);
+  if (!Number.isFinite(n)) return null;
   const unit = (m[2] || "px").toLowerCase();
-  return unit === "rem" ? n * 16 : n;
+  return unit === "rem" || unit === "em" ? n * 16 : n;
 };
 
 export function ThresholdPlugin(rules: ThresholdRule[], ruleId = "threshold"): ConstraintPlugin {
@@ -24,8 +30,21 @@ export function ThresholdPlugin(rules: ThresholdRule[], ruleId = "threshold"): C
       const issues = [];
       for (const r of rules) {
         if (!candidates.has(r.id)) continue; // incremental
-        const px = parseSizePx(engine.get(r.id));
-        if (px == null) continue;
+        const raw = engine.get(r.id);
+        const px = parseSizePx(raw);
+        if (px == null) {
+          // Present-but-unparseable size — warn instead of silently skipping (TASK-031).
+          if (raw != null && raw !== "") {
+            issues.push({
+              id: r.id,
+              rule: ruleId,
+              level: "warn" as const,
+              where: r.where,
+              message: `Cannot check ${r.id} ${r.op} ${r.valuePx}px: unparseable size value`
+            });
+          }
+          continue;
+        }
         const ok = r.op === ">=" ? px >= r.valuePx : px <= r.valuePx;
         if (!ok) {
           issues.push({

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

@@ -3,7 +3,7 @@ function resolveColor(engineGet, x) {
     if (typeof x !== "string")
         return undefined;
     // If it's a CSS color literal, return as is; else treat as token id.
-    const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
+    const isLiteral = /^(#|rgba?\(|hsla?\(|oklch\(|oklab\(|transparent$)/i.test(x);
     return isLiteral ? x : String(engineGet(x) ?? "");
 }
 export function WcagContrastPlugin(pairs) {
@@ -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

@@ -14,7 +14,7 @@ export type ContrastPair = {
 function resolveColor(engineGet: (id: TokenId)=>unknown, x: TokenId | string): string | undefined {
   if (typeof x !== "string") return undefined;
   // If it's a CSS color literal, return as is; else treat as token id.
-  const isLiteral = /^#|^rgb|^hsl|^oklch|^oklab|^transparent/i.test(x);
+  const isLiteral = /^(#|rgba?\(|hsla?\(|oklch\(|oklab\(|transparent$)/i.test(x);
   return isLiteral ? x : String(engineGet(x) ?? "");
 }
 
@@ -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,CAqH5D"}

package/core/flatten.js

@@ -1,5 +1,15 @@
-const REF_RE = /\{([a-z0-9.-]+)\}/gi;
+import { normalizeDtcgValue } from "./dtcg.js";
+const REF_RE = /\{([a-z0-9_.-]+)\}/gi;
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 export function flattenTokens(root) {
+    // Fail closed on a malformed token root (TASK-017). A non-object root — null,
+    // an array, or a scalar — previously walked to a silently-empty set that
+    // "validated" with ok:true; that hid garbage input. The token root must be a
+    // JSON object. (An empty object `{}` is still valid — it just has no tokens.)
+    if (root === null || typeof root !== 'object' || Array.isArray(root)) {
+        const got = root === null ? 'null' : Array.isArray(root) ? 'array' : typeof root;
+        throw new Error(`Token root must be a JSON object (got ${got}).`);
+    }
     const flat = {};
     const edges = [];
     // First pass: collect all tokens
@@ -8,13 +18,17 @@ export function flattenTokens(root) {
             return;
         if (Object.prototype.hasOwnProperty.call(node, '$value')) {
             const id = path.join('.');
-            const raw = node.$value;
-            if (raw === undefined)
+            if (node.$value === undefined)
                 return; // Skip tokens without values
+            // Normalize DTCG 2025.10 structured color/dimension objects to the
+            // string/number form the engine + plugins expect (strings, incl. aliases,
+            // pass through unchanged). Keeps the color math in core/color.ts untouched.
+            const raw = node.$value;
+            const normalized = normalizeDtcgValue(raw, node.$type);
             const refs = [];
             // Find all references in the value
-            if (typeof raw === 'string') {
-                const matches = raw.matchAll(REF_RE);
+            if (typeof normalized === 'string') {
+                const matches = normalized.matchAll(REF_RE);
                 for (const match of matches) {
                     refs.push(match[1]);
                 }
@@ -22,7 +36,7 @@ export function flattenTokens(root) {
             flat[id] = {
                 id,
                 type: String(node.$type ?? 'unknown'),
-                value: raw,
+                value: normalized,
                 raw,
                 refs
             };
@@ -44,7 +58,7 @@ export function flattenTokens(root) {
     // Second pass: resolve references iteratively
     let changed = true;
     let iterations = 0;
-    const maxIterations = Object.keys(flat).length * 2; // Safety limit
+    const maxIterations = Object.keys(flat).length * 2 + 1; // Safety limit (never 0)
     while (changed && iterations < maxIterations) {
         changed = false;
         iterations++;
@@ -63,7 +77,7 @@ export function flattenTokens(root) {
                         break;
                     }
                     // Replace the reference with the resolved value
-                    const refPattern = new RegExp(`\\{${refId}\\}`, 'g');
+                    const refPattern = new RegExp(`\\{${escapeRegExp(refId)}\\}`, 'g');
                     newValue = newValue.replace(refPattern, String(refToken.value));
                 }
                 if (fullyResolved && newValue !== token.value) {
@@ -73,8 +87,16 @@ export function flattenTokens(root) {
             }
         }
     }
-    if (iterations >= maxIterations) {
-        throw new Error('Token resolution exceeded maximum iterations - possible circular reference');
+    // A token still carrying an unresolved "{ref}" placeholder after the fixpoint
+    // means a genuine cycle (a -> b -> a) or a self-reference. An empty or
+    // fully-literal token set resolves cleanly and must never trip this guard —
+    // the old `iterations >= maxIterations` check threw a bogus "circular
+    // reference" error whenever no tokens were found (maxIterations === 0).
+    const unresolved = Object.values(flat).filter((t) => typeof t.value === 'string' && t.value.includes('{'));
+    if (unresolved.length > 0) {
+        throw new Error(`Token resolution exceeded maximum iterations - possible circular reference (unresolved: ${unresolved
+            .map((t) => t.id)
+            .join(', ')})`);
     }
     return { flat, edges };
 }