design-constraint-validator 1.0.0 → 1.1.0

package/cli/dcv.js

@@ -47,7 +47,11 @@ cli.command('build', 'Build token outputs', y => y
 cli.command('validate', 'Validate constraints', y => y
     .option('fail-on', { type: 'string', choices: ['off', 'warn', 'error'], default: 'error' })
     .option('summary', { type: 'string', choices: ['none', 'table', 'json'], default: 'none' })
+    .option('format', { type: 'string', choices: ['text', 'json'], default: 'text', describe: 'Output format' })
+    .option('output', { type: 'string', describe: 'Write JSON output to file' })
+    .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
     .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
+    .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
     .option('breakpoint', { type: 'string' })
     .option('all-breakpoints', { type: 'boolean' })
     .option('perf', { type: 'boolean', describe: 'Print timing info' })

package/cli/dcv.ts

@@ -1,107 +1,111 @@
-#!/usr/bin/env node
-// Clean minimal DCV CLI entrypoint
-import yargs from 'yargs/yargs';
-import { hideBin } from 'yargs/helpers';
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'module';
-import path from 'node:path';
-import { type SetOptions, type BuildOptions, type ValidateOptions, type GraphOptions, type WhyOptions, type PatchOptions, type PatchApplyOptions } from './types.js';
-import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
-
-// Early intercept: experimental graph diff helper
-(() => {
-  const args = process.argv.slice(2);
-  if (args[0] === 'graph' && args[1] === 'diff') {
-    const pass = args.slice(2);
-    const require = createRequire(import.meta.url);
-    const tsx = (() => { try { return require.resolve('tsx/dist/cli.mjs'); } catch { return path.resolve('node_modules/tsx/dist/cli.mjs'); }})();
-    const r = spawnSync(process.execPath, [tsx, path.resolve('scripts/graph-diff.ts'), ...pass], { stdio: 'inherit', env: process.env });
-    process.exit(r.status ?? 0);
-  }
-})();
-
-const cli = yargs(hideBin(process.argv))
-  .scriptName('dcv')
-  .parserConfiguration({ 'camel-case-expansion': false })
-  .option('quiet', { type: 'boolean' });
-
-cli.command<SetOptions>('set <expressions..>', 'Set token values', y => y
-  .positional('expressions', { type: 'string', array: true })
-  .option('dry-run', { type: 'boolean', default: false })
-  .option('write', { type: 'boolean' })
-  .option('json', { type: 'string' })
-  .option('unset', { type: 'array', string: true })
-  .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
-  .option('output', { type: 'string' })
-  .option('theme', { type: 'string' })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => setCommand(a)
-);
-
-cli.command<BuildOptions>('build', 'Build token outputs', y => y
-  .option('format', { type: 'string', choices: ['css','json','js'], default: 'css' })
-  .option('all-formats', { type: 'boolean', default: false })
-  .option('output', { type: 'string' })
-  .option('mapper', { type: 'string' })
-  .option('theme', { type: 'string' })
-  .option('dry-run', { type: 'boolean', default: false })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => buildCommand(a)
-);
-
-cli.command<ValidateOptions>('validate', 'Validate constraints', y => y
-  .option('fail-on', { type: 'string', choices: ['off','warn','error'], default: 'error' })
-  .option('summary', { type: 'string', choices: ['none','table','json'], default: 'none' })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
-  .option('breakpoint', { type: 'string' })
-  .option('all-breakpoints', { type: 'boolean' })
-  .option('perf', { type: 'boolean', describe: 'Print timing info' })
-  .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
-  .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }),
-  a => validateCommand(a)
-);
-
-cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y => y
-  .option('format', { type: 'string', choices: ['json','mermaid','dot','svg','png'], default: 'json' })
-  .option('bundle', { type: 'boolean', describe: 'When used with --hasse export mermaid+dot (+image if svg/png requested)' })
-  .option('hasse', { type: 'string' })
-  .option('filter-prefix', { type: 'string' })
-  .option('exclude-prefix', { type: 'string' })
-  .option('only-violations', { type: 'boolean' })
-  .option('highlight-violations', { type: 'boolean' })
-  .option('label-violations', { type: 'boolean' })
-  .option('label-truncate', { type: 'number', default: 0 })
-  .option('min-severity', { type: 'string', choices: ['warn','error'], default: 'warn' })
-  .option('focus', { type: 'string' })
-  .option('radius', { type: 'number', default: 1 })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => graphCommand(a)
-);
-
-cli.command<WhyOptions>('why <tokenId>', 'Explain token provenance', y => y
-  .positional('tokenId', { type: 'string', demandOption: true })
-  .option('format', { type: 'string', choices: ['json','table'], default: 'json' })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => whyCommand(a)
-);
-
-cli.command<PatchOptions>('patch', 'Export patch (diff) from overrides', y => y
-  .option('overrides', { type: 'string', describe: 'Path or inline JSON of flat overrides' })
-  .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
-  .option('output', { type: 'string' })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
-  a => patchCommand(a)
-);
-
-cli.command<PatchApplyOptions>('patch:apply <patch>', 'Apply patch document to tokens', y => y
-  .positional('patch', { type: 'string', demandOption: true })
-  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
-  .option('output', { type: 'string', describe: 'Write updated tokens to this file' })
-  .option('dry-run', { type: 'boolean', default: false }),
-  a => patchApplyCommand(a)
-);
-
-cli.help().alias('h','help').strict().wrap(cli.terminalWidth());
-cli.parse();
-
-// EOF
+#!/usr/bin/env node
+// Clean minimal DCV CLI entrypoint
+import yargs from 'yargs/yargs';
+import { hideBin } from 'yargs/helpers';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'module';
+import path from 'node:path';
+import { type SetOptions, type BuildOptions, type ValidateOptions, type GraphOptions, type WhyOptions, type PatchOptions, type PatchApplyOptions } from './types.js';
+import { setCommand, buildCommand, validateCommand, graphCommand, whyCommand, patchCommand, patchApplyCommand } from './commands/index.js';
+
+// Early intercept: experimental graph diff helper
+(() => {
+  const args = process.argv.slice(2);
+  if (args[0] === 'graph' && args[1] === 'diff') {
+    const pass = args.slice(2);
+    const require = createRequire(import.meta.url);
+    const tsx = (() => { try { return require.resolve('tsx/dist/cli.mjs'); } catch { return path.resolve('node_modules/tsx/dist/cli.mjs'); }})();
+    const r = spawnSync(process.execPath, [tsx, path.resolve('scripts/graph-diff.ts'), ...pass], { stdio: 'inherit', env: process.env });
+    process.exit(r.status ?? 0);
+  }
+})();
+
+const cli = yargs(hideBin(process.argv))
+  .scriptName('dcv')
+  .parserConfiguration({ 'camel-case-expansion': false })
+  .option('quiet', { type: 'boolean' });
+
+cli.command<SetOptions>('set <expressions..>', 'Set token values', y => y
+  .positional('expressions', { type: 'string', array: true })
+  .option('dry-run', { type: 'boolean', default: false })
+  .option('write', { type: 'boolean' })
+  .option('json', { type: 'string' })
+  .option('unset', { type: 'array', string: true })
+  .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
+  .option('output', { type: 'string' })
+  .option('theme', { type: 'string' })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  a => setCommand(a)
+);
+
+cli.command<BuildOptions>('build', 'Build token outputs', y => y
+  .option('format', { type: 'string', choices: ['css','json','js'], default: 'css' })
+  .option('all-formats', { type: 'boolean', default: false })
+  .option('output', { type: 'string' })
+  .option('mapper', { type: 'string' })
+  .option('theme', { type: 'string' })
+  .option('dry-run', { type: 'boolean', default: false })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  a => buildCommand(a)
+);
+
+cli.command<ValidateOptions>('validate', 'Validate constraints', y => y
+  .option('fail-on', { type: 'string', choices: ['off','warn','error'], default: 'error' })
+  .option('summary', { type: 'string', choices: ['none','table','json'], default: 'none' })
+  .option('format', { type: 'string', choices: ['text','json'], default: 'text', describe: 'Output format' })
+  .option('output', { type: 'string', describe: 'Write JSON output to file' })
+  .option('receipt', { type: 'string', describe: 'Generate validation receipt with audit trail' })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
+  .option('theme', { type: 'string', describe: 'Apply named theme tokens before validation' })
+  .option('breakpoint', { type: 'string' })
+  .option('all-breakpoints', { type: 'boolean' })
+  .option('perf', { type: 'boolean', describe: 'Print timing info' })
+  .option('budget-total-ms', { type: 'number', describe: 'Fail if total validation exceeds this (ms)' })
+  .option('budget-per-bp-ms', { type: 'number', describe: 'Fail if any single breakpoint exceeds this (ms)' }),
+  a => validateCommand(a)
+);
+
+cli.command<GraphOptions>('graph', 'Generate dependency / constraint graph', y => y
+  .option('format', { type: 'string', choices: ['json','mermaid','dot','svg','png'], default: 'json' })
+  .option('bundle', { type: 'boolean', describe: 'When used with --hasse export mermaid+dot (+image if svg/png requested)' })
+  .option('hasse', { type: 'string' })
+  .option('filter-prefix', { type: 'string' })
+  .option('exclude-prefix', { type: 'string' })
+  .option('only-violations', { type: 'boolean' })
+  .option('highlight-violations', { type: 'boolean' })
+  .option('label-violations', { type: 'boolean' })
+  .option('label-truncate', { type: 'number', default: 0 })
+  .option('min-severity', { type: 'string', choices: ['warn','error'], default: 'warn' })
+  .option('focus', { type: 'string' })
+  .option('radius', { type: 'number', default: 1 })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  a => graphCommand(a)
+);
+
+cli.command<WhyOptions>('why <tokenId>', 'Explain token provenance', y => y
+  .positional('tokenId', { type: 'string', demandOption: true })
+  .option('format', { type: 'string', choices: ['json','table'], default: 'json' })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  a => whyCommand(a)
+);
+
+cli.command<PatchOptions>('patch', 'Export patch (diff) from overrides', y => y
+  .option('overrides', { type: 'string', describe: 'Path or inline JSON of flat overrides' })
+  .option('format', { type: 'string', choices: ['json','css','js'], default: 'json' })
+  .option('output', { type: 'string' })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' }),
+  a => patchCommand(a)
+);
+
+cli.command<PatchApplyOptions>('patch:apply <patch>', 'Apply patch document to tokens', y => y
+  .positional('patch', { type: 'string', demandOption: true })
+  .option('tokens', { type: 'string', default: 'tokens/tokens.example.json' })
+  .option('output', { type: 'string', describe: 'Write updated tokens to this file' })
+  .option('dry-run', { type: 'boolean', default: false }),
+  a => patchApplyCommand(a)
+);
+
+cli.help().alias('h','help').strict().wrap(cli.terminalWidth());
+cli.parse();
+
+// EOF

package/cli/engine-helpers.d.ts

@@ -1,8 +1,41 @@
+/**
+ * @deprecated This module is deprecated. Use constraint-registry.ts instead.
+ *
+ * Phase 3A (Architectural Cleanup): This file contains legacy constraint loading logic
+ * that has been replaced by the centralized constraint-registry.ts module.
+ *
+ * Migration guide:
+ * - Replace createEngine() or createValidationEngine() with:
+ *   ```ts
+ *   import { Engine } from '../core/engine.js';
+ *   import { flattenTokens, type FlatToken } from '../core/flatten.js';
+ *   import { setupConstraints } from './constraint-registry.js';
+ *
+ *   const { flat, edges } = flattenTokens(tokens);
+ *   const init = {};
+ *   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));
+ *   setupConstraints(engine, { config, bp }, { knownIds });
+ *   ```
+ *
+ * This file will be removed in a future major version.
+ */
 import { type TokenNode } from '../core/flatten.js';
 import { Engine } from '../core/engine.js';
 import { loadTokensWithBreakpoint, type Breakpoint } from '../core/breakpoints.js';
 import type { DcvConfig } from './types.js';
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
 export declare function createEngine(tokensRoot: TokenNode, config?: DcvConfig): Engine;
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
 export declare function createValidationEngine(tokensRoot: TokenNode, bp: Breakpoint | undefined, config: DcvConfig): Engine;
 export { loadTokensWithBreakpoint };
 //# sourceMappingURL=engine-helpers.d.ts.map

package/cli/engine-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-helpers.d.ts","sourceRoot":"","sources":["engine-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI3C,OAAO,EAA8B,wBAAwB,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC/G,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAE,SAAc,GAAG,MAAM,CA8BlF;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAkBnH;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"engine-helpers.d.ts","sourceRoot":"","sources":["engine-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAkB,MAAM,oBAAoB,CAAC;AACnF,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAI3C,OAAO,EAA8B,wBAAwB,EAAE,KAAK,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC/G,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAgE5C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,GAAE,SAAc,GAAG,MAAM,CAQlF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,GAAG,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,MAAM,CAgBnH;AAED,OAAO,EAAE,wBAAwB,EAAE,CAAC"}

package/cli/engine-helpers.js

@@ -1,15 +1,35 @@
+/**
+ * @deprecated This module is deprecated. Use constraint-registry.ts instead.
+ *
+ * Phase 3A (Architectural Cleanup): This file contains legacy constraint loading logic
+ * that has been replaced by the centralized constraint-registry.ts module.
+ *
+ * Migration guide:
+ * - Replace createEngine() or createValidationEngine() with:
+ *   ```ts
+ *   import { Engine } from '../core/engine.js';
+ *   import { flattenTokens, type FlatToken } from '../core/flatten.js';
+ *   import { setupConstraints } from './constraint-registry.js';
+ *
+ *   const { flat, edges } = flattenTokens(tokens);
+ *   const init = {};
+ *   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));
+ *   setupConstraints(engine, { config, bp }, { knownIds });
+ *   ```
+ *
+ * This file will be removed in a future major version.
+ */
 import { flattenTokens } from '../core/flatten.js';
 import { Engine } from '../core/engine.js';
 import { MonotonicPlugin, parseSize as parseSizePx } from '../core/constraints/monotonic.js';
 import { MonotonicLightness } from '../core/constraints/monotonic-lightness.js';
 import { WcagContrastPlugin } from '../core/constraints/wcag.js';
 import { loadOrders as loadOrdersBP, loadTokensWithBreakpoint } from '../core/breakpoints.js';
-export function createEngine(tokensRoot, config = {}) {
-    const { flat, edges } = flattenTokens(tokensRoot);
-    const init = {};
-    for (const [id, token] of Object.entries(flat))
-        init[id] = token.value;
-    const engine = new Engine(init, edges);
+function applyMonotonicPlugins(engine, bp) {
     function loadOrders(path) {
         try {
             // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -19,10 +39,11 @@ export function createEngine(tokensRoot, config = {}) {
             return [];
         }
     }
-    const typOrders = loadOrders('themes/typography.order.json');
-    const spacingOrders = loadOrders('themes/spacing.order.json');
-    const layoutOrders = loadOrders('themes/layout.order.json');
-    const colorOrders = loadOrders('themes/color.order.json');
+    const suffix = bp ? `.${bp}` : '';
+    const typOrders = loadOrders(`themes/typography${suffix}.order.json`);
+    const spacingOrders = loadOrders(`themes/spacing${suffix}.order.json`);
+    const layoutOrders = loadOrders(`themes/layout${suffix}.order.json`);
+    const colorOrders = loadOrders(`themes/color${suffix}.order.json`);
     if (typOrders.length)
         engine.use(MonotonicPlugin(typOrders, parseSizePx, 'monotonic-typography'));
     if (spacingOrders.length)
@@ -31,24 +52,71 @@ export function createEngine(tokensRoot, config = {}) {
         engine.use(MonotonicPlugin(layoutOrders, parseSizePx, 'monotonic-layout'));
     if (colorOrders.length)
         engine.use(MonotonicLightness(colorOrders));
-    if (config.constraints?.wcag) {
-        const wcagRules = config.constraints.wcag.map((r) => ({ fg: r.foreground, bg: r.background, min: r.ratio || 4.5, where: r.description || 'Unknown' }));
+}
+function applyWcagPlugins(engine, config) {
+    const constraintsCfg = config.constraints ?? {};
+    if (constraintsCfg.wcag) {
+        const wcagRules = constraintsCfg.wcag.map((r) => ({
+            fg: r.foreground,
+            bg: r.background,
+            min: r.ratio || 4.5,
+            where: r.description || 'Unknown',
+        }));
         engine.use(WcagContrastPlugin(wcagRules));
     }
-    const defaultWcagPairs = [
-        { fg: 'color.role.text.default', bg: 'color.role.bg.surface', min: 4.5, where: 'Body text on surface' },
-        { fg: 'color.role.accent.default', bg: 'color.role.bg.surface', min: 3.0, where: 'Accent on surface' },
-        { fg: 'color.role.focus.ring', bg: 'color.role.bg.surface', min: 3.0, where: 'Focus ring on surface', backdrop: '#ffffff' }
-    ];
-    engine.use(WcagContrastPlugin(defaultWcagPairs));
+    const enableDefaults = constraintsCfg.enableBuiltInWcagDefaults === undefined
+        ? true
+        : !!constraintsCfg.enableBuiltInWcagDefaults;
+    if (enableDefaults) {
+        const defaultWcagPairs = [
+            {
+                fg: 'color.role.text.default',
+                bg: 'color.role.bg.surface',
+                min: 4.5,
+                where: 'Body text on surface',
+            },
+            {
+                fg: 'color.role.accent.default',
+                bg: 'color.role.bg.surface',
+                min: 3.0,
+                where: 'Accent on surface',
+            },
+            {
+                fg: 'color.role.focus.ring',
+                bg: 'color.role.bg.surface',
+                min: 3.0,
+                where: 'Focus ring on surface',
+                backdrop: '#ffffff',
+            },
+        ];
+        engine.use(WcagContrastPlugin(defaultWcagPairs));
+    }
+}
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
+export function createEngine(tokensRoot, config = {}) {
+    const { flat, edges } = flattenTokens(tokensRoot);
+    const init = {};
+    for (const [id, token] of Object.entries(flat))
+        init[id] = token.value;
+    const engine = new Engine(init, edges);
+    applyMonotonicPlugins(engine, undefined);
+    applyWcagPlugins(engine, config);
     return engine;
 }
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
 export function createValidationEngine(tokensRoot, bp, config) {
     const { flat, edges } = flattenTokens(tokensRoot);
     const init = {};
     for (const t of Object.values(flat))
         init[t.id] = t.value;
     const engine = new Engine(init, edges);
+    // Use breakpoint-aware order loading where available
     const typ = loadOrdersBP('typography', bp);
     const spc = loadOrdersBP('spacing', bp);
     const lay = loadOrdersBP('layout', bp);
@@ -61,10 +129,7 @@ export function createValidationEngine(tokensRoot, bp, config) {
         engine.use(MonotonicPlugin(lay, parseSizePx, 'monotonic-layout'));
     if (col.length)
         engine.use(MonotonicLightness(col));
-    if (config.constraints?.wcag) {
-        const wcagRules = config.constraints.wcag.map((rule) => ({ fg: rule.foreground, bg: rule.background, min: rule.ratio || 4.5, where: rule.description || 'Unknown' }));
-        engine.use(WcagContrastPlugin(wcagRules));
-    }
+    applyWcagPlugins(engine, config);
     return engine;
 }
 export { loadTokensWithBreakpoint };

package/cli/engine-helpers.ts

@@ -1,61 +1,133 @@
-import { flattenTokens, type TokenNode, type FlatToken } from '../core/flatten.js';
-import { Engine } from '../core/engine.js';
-import { MonotonicPlugin, parseSize as parseSizePx } from '../core/constraints/monotonic.js';
-import { MonotonicLightness } from '../core/constraints/monotonic-lightness.js';
-import { WcagContrastPlugin } from '../core/constraints/wcag.js';
-import { loadOrders as loadOrdersBP, loadTokensWithBreakpoint, type Breakpoint } from '../core/breakpoints.js';
-import type { DcvConfig } from './types.js';
-
-export function createEngine(tokensRoot: TokenNode, config: DcvConfig = {}): Engine {
-  const { flat, edges } = flattenTokens(tokensRoot);
-  const init: Record<string, string | number> = {};
-  for (const [id, token] of Object.entries(flat)) init[id] = (token as FlatToken).value;
-  const engine = new Engine(init, edges);
-  function loadOrders(path: string) {
-    try { 
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      return JSON.parse(require('node:fs').readFileSync(path, 'utf8')).order as [string, '<='|'>=', string][]; 
-    } catch { return []; }
-  }
-  const typOrders = loadOrders('themes/typography.order.json');
-  const spacingOrders = loadOrders('themes/spacing.order.json');
-  const layoutOrders = loadOrders('themes/layout.order.json');
-  const colorOrders = loadOrders('themes/color.order.json');
-  if (typOrders.length) engine.use(MonotonicPlugin(typOrders, parseSizePx, 'monotonic-typography'));
-  if (spacingOrders.length) engine.use(MonotonicPlugin(spacingOrders, parseSizePx, 'monotonic-spacing'));
-  if (layoutOrders.length) engine.use(MonotonicPlugin(layoutOrders, parseSizePx, 'monotonic-layout'));
-  if (colorOrders.length) engine.use(MonotonicLightness(colorOrders));
-  if (config.constraints?.wcag) {
-    const wcagRules = config.constraints.wcag.map((r: any) => ({ fg: r.foreground, bg: r.background, min: r.ratio || 4.5, where: r.description || 'Unknown' }));
-    engine.use(WcagContrastPlugin(wcagRules));
-  }
-  const defaultWcagPairs = [
-    { fg: 'color.role.text.default', bg: 'color.role.bg.surface', min: 4.5, where: 'Body text on surface' },
-    { fg: 'color.role.accent.default', bg: 'color.role.bg.surface', min: 3.0, where: 'Accent on surface' },
-    { fg: 'color.role.focus.ring', bg: 'color.role.bg.surface', min: 3.0, where: 'Focus ring on surface', backdrop: '#ffffff' }
-  ];
-  engine.use(WcagContrastPlugin(defaultWcagPairs));
-  return engine;
-}
-
-export function createValidationEngine(tokensRoot: TokenNode, bp: Breakpoint | undefined, config: DcvConfig): Engine {
-  const { flat, edges } = flattenTokens(tokensRoot);
-  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 typ = loadOrdersBP('typography', bp);
-  const spc = loadOrdersBP('spacing', bp);
-  const lay = loadOrdersBP('layout', bp);
-  const col = loadOrdersBP('color', bp);
-  if (typ.length) engine.use(MonotonicPlugin(typ, parseSizePx, 'monotonic-typography'));
-  if (spc.length) engine.use(MonotonicPlugin(spc, parseSizePx, 'monotonic-spacing'));
-  if (lay.length) engine.use(MonotonicPlugin(lay, parseSizePx, 'monotonic-layout'));
-  if (col.length) engine.use(MonotonicLightness(col));
-  if (config.constraints?.wcag) {
-    const wcagRules = config.constraints.wcag.map((rule: any) => ({ fg: rule.foreground, bg: rule.background, min: rule.ratio || 4.5, where: rule.description || 'Unknown' }));
-    engine.use(WcagContrastPlugin(wcagRules));
-  }
-  return engine;
-}
-
-export { loadTokensWithBreakpoint };
+/**
+ * @deprecated This module is deprecated. Use constraint-registry.ts instead.
+ *
+ * Phase 3A (Architectural Cleanup): This file contains legacy constraint loading logic
+ * that has been replaced by the centralized constraint-registry.ts module.
+ *
+ * Migration guide:
+ * - Replace createEngine() or createValidationEngine() with:
+ *   ```ts
+ *   import { Engine } from '../core/engine.js';
+ *   import { flattenTokens, type FlatToken } from '../core/flatten.js';
+ *   import { setupConstraints } from './constraint-registry.js';
+ *
+ *   const { flat, edges } = flattenTokens(tokens);
+ *   const init = {};
+ *   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));
+ *   setupConstraints(engine, { config, bp }, { knownIds });
+ *   ```
+ *
+ * This file will be removed in a future major version.
+ */
+
+import { flattenTokens, type TokenNode, type FlatToken } from '../core/flatten.js';
+import { Engine } from '../core/engine.js';
+import { MonotonicPlugin, parseSize as parseSizePx } from '../core/constraints/monotonic.js';
+import { MonotonicLightness } from '../core/constraints/monotonic-lightness.js';
+import { WcagContrastPlugin } from '../core/constraints/wcag.js';
+import { loadOrders as loadOrdersBP, loadTokensWithBreakpoint, type Breakpoint } from '../core/breakpoints.js';
+import type { DcvConfig } from './types.js';
+
+function applyMonotonicPlugins(engine: Engine, bp: Breakpoint | undefined): void {
+  function loadOrders(path: string) {
+    try { 
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return JSON.parse(require('node:fs').readFileSync(path, 'utf8')).order as [string, '<='|'>=', string][]; 
+    } catch { return []; }
+  }
+  const suffix = bp ? `.${bp}` : '';
+  const typOrders = loadOrders(`themes/typography${suffix}.order.json`);
+  const spacingOrders = loadOrders(`themes/spacing${suffix}.order.json`);
+  const layoutOrders = loadOrders(`themes/layout${suffix}.order.json`);
+  const colorOrders = loadOrders(`themes/color${suffix}.order.json`);
+  if (typOrders.length) engine.use(MonotonicPlugin(typOrders, parseSizePx, 'monotonic-typography'));
+  if (spacingOrders.length) engine.use(MonotonicPlugin(spacingOrders, parseSizePx, 'monotonic-spacing'));
+  if (layoutOrders.length) engine.use(MonotonicPlugin(layoutOrders, parseSizePx, 'monotonic-layout'));
+  if (colorOrders.length) engine.use(MonotonicLightness(colorOrders));
+}
+
+function applyWcagPlugins(engine: Engine, config: DcvConfig): void {
+  const constraintsCfg = config.constraints ?? {};
+
+  if (constraintsCfg.wcag) {
+    const wcagRules = constraintsCfg.wcag.map((r: any) => ({
+      fg: r.foreground,
+      bg: r.background,
+      min: r.ratio || 4.5,
+      where: r.description || 'Unknown',
+    }));
+    engine.use(WcagContrastPlugin(wcagRules));
+  }
+
+  const enableDefaults =
+    constraintsCfg.enableBuiltInWcagDefaults === undefined
+      ? true
+      : !!constraintsCfg.enableBuiltInWcagDefaults;
+
+  if (enableDefaults) {
+    const defaultWcagPairs = [
+      {
+        fg: 'color.role.text.default',
+        bg: 'color.role.bg.surface',
+        min: 4.5,
+        where: 'Body text on surface',
+      },
+      {
+        fg: 'color.role.accent.default',
+        bg: 'color.role.bg.surface',
+        min: 3.0,
+        where: 'Accent on surface',
+      },
+      {
+        fg: 'color.role.focus.ring',
+        bg: 'color.role.bg.surface',
+        min: 3.0,
+        where: 'Focus ring on surface',
+        backdrop: '#ffffff',
+      },
+    ];
+    engine.use(WcagContrastPlugin(defaultWcagPairs));
+  }
+}
+
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
+export function createEngine(tokensRoot: TokenNode, config: DcvConfig = {}): Engine {
+  const { flat, edges } = flattenTokens(tokensRoot);
+  const init: Record<string, string | number> = {};
+  for (const [id, token] of Object.entries(flat)) init[id] = (token as FlatToken).value;
+  const engine = new Engine(init, edges);
+  applyMonotonicPlugins(engine, undefined);
+  applyWcagPlugins(engine, config);
+  return engine;
+}
+
+/**
+ * @deprecated Use constraint-registry.ts setupConstraints() instead.
+ * This function will be removed in a future major version.
+ */
+export function createValidationEngine(tokensRoot: TokenNode, bp: Breakpoint | undefined, config: DcvConfig): Engine {
+  const { flat, edges } = flattenTokens(tokensRoot);
+  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);
+  // Use breakpoint-aware order loading where available
+  const typ = loadOrdersBP('typography', bp);
+  const spc = loadOrdersBP('spacing', bp);
+  const lay = loadOrdersBP('layout', bp);
+  const col = loadOrdersBP('color', bp);
+  if (typ.length) engine.use(MonotonicPlugin(typ, parseSizePx, 'monotonic-typography'));
+  if (spc.length) engine.use(MonotonicPlugin(spc, parseSizePx, 'monotonic-spacing'));
+  if (lay.length) engine.use(MonotonicPlugin(lay, parseSizePx, 'monotonic-layout'));
+  if (col.length) engine.use(MonotonicLightness(col));
+  applyWcagPlugins(engine, config);
+  return engine;
+}
+
+export { loadTokensWithBreakpoint };