design-constraint-validator 1.0.0

package/core/why.ts

@@ -0,0 +1,63 @@
+import type { FlatToken } from "./flatten.js";
+
+export type WhyReport = {
+  id: string;
+  value: string | number | undefined;
+  raw?: string | number;
+  refs?: string[];
+  provenance: "base" | "theme" | "override" | "unknown";
+  dependsOn: string[];     // immediate refs (parents)
+  dependents: string[];    // immediate children
+  chain?: string[];        // simple linear chain if raw is a single {ref} repeated
+};
+
+export function makeReverseEdges(edges: Array<[string,string]>): Map<string, Set<string>> {
+  const rev = new Map<string, Set<string>>();
+  for (const [from, to] of edges) {
+    if (!rev.has(to)) rev.set(to, new Set());
+    rev.get(to)!.add(from);
+    if (!rev.has(from)) rev.set(from, new Set());
+  }
+  return rev;
+}
+
+export function explain(
+  id: string,
+  flat: Record<string, FlatToken>,
+  edges: Array<[string,string]>,
+  layers: { overrides?: Record<string, unknown>, theme?: Record<string, unknown> } = {}
+): WhyReport {
+  const node = flat[id];
+  const rev = makeReverseEdges(edges);
+  const dependsOn = Array.from(rev.get(id) ?? []);
+  const dependents = edges.filter(([from, _to]) => from === id).map(([_, to]) => to);
+
+  const prov: WhyReport["provenance"] =
+    layers.overrides && id in layers.overrides ? "override" :
+    layers.theme     && id in layers.theme     ? "theme"    :
+    flat[id] ? "base" : "unknown";
+
+  // Try to produce a simple chain if it's a 1→1 alias chain
+  const chain: string[] = [id];
+  let cursor = id; let guard = 0;
+  while (guard++ < 32) {
+    const f = flat[cursor];
+    if (!f || !Array.isArray(f.refs) || f.refs.length !== 1) break;
+    const next = f.refs[0];
+    chain.push(next);
+    cursor = next;
+    const nxt = flat[next];
+    if (!nxt || !nxt.refs?.length) break;
+  }
+
+  return {
+    id,
+    value: node?.value,
+    raw: node?.raw,
+    refs: node?.refs,
+    provenance: prov,
+    dependsOn,
+    dependents,
+    chain: chain.length > 1 ? chain : undefined
+  };
+}

package/dist/test-overrides-removal.json

@@ -0,0 +1,4 @@
+{
+  "color.palette.brand.600": "#ffffff",
+  "color.palette.brand.700": null
+}

package/dist/tmp.patch.json

@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "generatedAt": "2025-11-01T06:31:35.033Z",
+  "baseFile": "tokens/tokens.example.json",
+  "changes": [
+    {
+      "id": "color.palette.brand.600",
+      "from": "oklch(0.62 0.18 260)",
+      "to": "#ffffff",
+      "type": "modify"
+    },
+    {
+      "id": "color.palette.brand.700",
+      "from": "oklch(0.56 0.19 260)",
+      "to": null,
+      "type": "remove"
+    },
+    {
+      "id": "color.role.accent.default",
+      "from": "oklch(0.62 0.18 260)",
+      "to": "#ffffff",
+      "type": "modify"
+    }
+  ],
+  "patch": {
+    "color.palette.brand.600": "#ffffff",
+    "color.palette.brand.700": null,
+    "color.role.accent.default": "#ffffff"
+  },
+  "hash": "e925a3d3532d35c4a569788d9b061fda15f0b5b904867094b3cba727091edf3c",
+  "baseTokensHash": "9c75c6bc19e4700ab5393e9118c6ce5596727e0fdbba890aaef1ebb831868c26",
+  "meta": {
+    "changeCount": 3
+  }
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "design-constraint-validator",
+  "version": "1.0.0",
+  "description": "Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "core/index.js",
+  "types": "core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./core/index.d.ts",
+      "import": "./core/index.js"
+    },
+    "./core/*": "./core/*",
+    "./cli/*": "./cli/*"
+  },
+  "bin": {
+    "dcv": "./cli/index.js",
+    "design-constraint-validator": "./cli/index.js"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
+    "lint": "eslint . --ext .js,.ts,.mjs,.cjs",
+    "format": "prettier -w .",
+    "check": "npm run typecheck && npm run lint && npm test",
+    "prepublishOnly": "npm run check && npm run build",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
+    "release:notes": "npm run changelog && git add CHANGELOG.md && git commit -m \"docs(changelog): update\"",
+    "release:patch": "npm version patch && git push && git push --tags && echo '\n⚠️  Now run: npm publish'",
+    "release:minor": "npm version minor && git push && git push --tags && echo '\n⚠️  Now run: npm publish'",
+    "release:major": "npm version major && git push && git push --tags && echo '\n⚠️  Now run: npm publish'"
+  },
+  "keywords": [
+    "design-constraints",
+    "design-systems",
+    "constraint-validation",
+    "design-tokens",
+    "accessibility",
+    "wcag",
+    "mathematical-validation",
+    "typography",
+    "color",
+    "monotonicity",
+    "cli-tool"
+  ],
+  "author": "Cseperke Papp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CseperkePapp/design-constraint-validator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CseperkePapp/design-constraint-validator/issues"
+  },
+  "homepage": "https://github.com/CseperkePapp/design-constraint-validator#readme",
+  "dependencies": {
+    "yargs": "^17.0.0",
+    "zod": "^3.0.0",
+    "fast-glob": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/yargs": "^17.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^9.0.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0",
+    "conventional-changelog-cli": "^2.2.2"
+  },
+  "files": [
+    "adapters",
+    
+    "dist",
+    "cli",
+    "core",
+    "themes",
+    "tokens",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/themes/color.lg.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Color lightness hierarchy constraints - LG breakpoint specific",
+  "order": [
+    ["color.palette.brand.400", ">=", "color.palette.brand.500"],
+    ["color.palette.brand.500", ">=", "color.palette.brand.600"],
+    ["color.palette.brand.600", ">=", "color.palette.brand.700"],
+
+    ["color.palette.gray.300", ">=", "color.palette.gray.400"],
+    ["color.palette.gray.400", ">=", "color.palette.gray.500"],
+    ["color.palette.gray.500", ">=", "color.palette.gray.600"],
+    ["color.palette.gray.600", ">=", "color.palette.gray.900"],
+
+    ["color.palette.brand.600", ">=", "color.palette.gray.500"]
+  ]
+}

package/themes/color.md.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Color lightness hierarchy constraints - MD breakpoint specific",
+  "order": [
+    ["color.palette.brand.400", ">=", "color.palette.brand.500"],
+    ["color.palette.brand.500", ">=", "color.palette.brand.600"],
+    ["color.palette.brand.600", ">=", "color.palette.brand.700"],
+
+    ["color.palette.gray.300", ">=", "color.palette.gray.400"],
+    ["color.palette.gray.400", ">=", "color.palette.gray.500"],
+    ["color.palette.gray.500", ">=", "color.palette.gray.600"],
+    ["color.palette.gray.600", ">=", "color.palette.gray.900"],
+
+    ["color.palette.brand.600", ">=", "color.palette.gray.500"]
+  ]
+}

package/themes/color.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Color lightness hierarchy constraints - comprehensive brand and gray ladders with bridge constraints",
+  "order": [
+    ["color.palette.brand.400", ">=", "color.palette.brand.500"],
+    ["color.palette.brand.500", ">=", "color.palette.brand.600"],
+    ["color.palette.brand.600", ">=", "color.palette.brand.700"],
+
+    ["color.palette.gray.300", ">=", "color.palette.gray.400"],
+    ["color.palette.gray.400", ">=", "color.palette.gray.500"],
+    ["color.palette.gray.500", ">=", "color.palette.gray.600"],
+    ["color.palette.gray.600", ">=", "color.palette.gray.900"],
+
+    ["color.palette.brand.600", ">=", "color.palette.gray.500"]
+  ]
+}

package/themes/color.sm.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Color lightness hierarchy constraints - SM breakpoint specific",
+  "order": [
+    ["color.palette.brand.400", ">=", "color.palette.brand.500"],
+    ["color.palette.brand.500", ">=", "color.palette.brand.600"],
+    ["color.palette.brand.600", ">=", "color.palette.brand.700"],
+
+    ["color.palette.gray.300", ">=", "color.palette.gray.400"],
+    ["color.palette.gray.400", ">=", "color.palette.gray.500"],
+    ["color.palette.gray.500", ">=", "color.palette.gray.600"],
+    ["color.palette.gray.600", ">=", "color.palette.gray.900"],
+
+    ["color.palette.brand.600", ">=", "color.palette.gray.500"]
+  ]
+}

package/themes/cross-axis.rules.json

@@ -0,0 +1,36 @@
+{
+  "rules": [
+    {
+      "id": "body-weight-vs-size",
+      "level": "error",
+      "where": "Body legibility",
+      "when": { "id": "typography.weight.body", "op": "<=", "value": 400 },
+      "require": { "id": "typography.size.body", "op": ">=", "fallback": "16px" }
+    },
+    {
+      "id": "emphasis-weight-size-balance",
+      "level": "warn",
+      "where": "Legibility emphasis",
+      "when": { "id": "typography.weight.emphasis", "op": ">=", "value": 600 },
+      "require": { "id": "typography.size.body", "op": ">=", "fallback": "15px" }
+    },
+    {
+      "id": "heading-emphasis-h2",
+      "level": "warn",
+      "where": "Heading emphasis",
+      "compare": { "a": "typography.size.h2", "op": ">=", "b": "typography.size.body", "delta": "2px" }
+    },
+    {
+      "id": "heading-emphasis-h3",
+      "level": "warn",
+      "where": "Heading emphasis",
+      "compare": { "a": "typography.size.h3", "op": ">=", "b": "typography.size.body", "delta": "2px" }
+    },
+    {
+      "id": "layout-padding-vs-container",
+      "level": "warn",
+      "where": "Layout density",
+      "compare": { "a": "layout.padding.section", "op": "<=", "b": "layout.container.sm", "delta": "-560px" }
+    }
+  ]
+}

package/themes/cross-axis.sm.rules.json

@@ -0,0 +1,12 @@
+{
+  "rules": [
+    {
+      "id": "body-size-min-sm",
+      "bp": "sm",
+      "level": "warn",
+      "where": "Small screen legibility",
+      "when": { "id": "typography.size.body", "op": ">=", "value": 0 },
+      "require": { "id": "typography.size.body", "op": ">=", "fallback": "15px" }
+    }
+  ]
+}

package/themes/layout.lg.order.json

@@ -0,0 +1,18 @@
+{
+  "$description": "Layout hierarchy order constraints - LG breakpoint specific",
+  "order": [
+    ["layout.container.xs", "<=", "layout.container.sm"],
+    ["layout.container.sm", "<=", "layout.container.md"],
+    ["layout.container.md", "<=", "layout.container.lg"],
+    ["layout.container.lg", "<=", "layout.container.xl"],
+
+    ["layout.padding.page", ">=", "layout.padding.section"],
+    ["layout.padding.section", ">=", "layout.padding.card"],
+    ["layout.padding.card", ">=", "layout.padding.chip"],
+
+    ["layout.grid.gutter", "<=", "layout.padding.section"],
+    ["layout.grid.gutter", "<=", "layout.padding.card"],
+
+    ["control.size.min", ">=", "layout.padding.card"]
+  ]
+}

package/themes/layout.md.order.json

@@ -0,0 +1,18 @@
+{
+  "$description": "Layout hierarchy order constraints - MD breakpoint specific",
+  "order": [
+    ["layout.container.xs", "<=", "layout.container.sm"],
+    ["layout.container.sm", "<=", "layout.container.md"],
+    ["layout.container.md", "<=", "layout.container.lg"],
+    ["layout.container.lg", "<=", "layout.container.xl"],
+
+    ["layout.padding.page", ">=", "layout.padding.section"],
+    ["layout.padding.section", ">=", "layout.padding.card"],
+    ["layout.padding.card", ">=", "layout.padding.chip"],
+
+    ["layout.grid.gutter", "<=", "layout.padding.section"],
+    ["layout.grid.gutter", "<=", "layout.padding.card"],
+
+    ["control.size.min", ">=", "layout.padding.card"]
+  ]
+}

package/themes/layout.order.json

@@ -0,0 +1,18 @@
+{
+  "$description": "Layout hierarchy order constraints - container widths grow, padding hierarchy, gutters ≤ paddings, control touch targets",
+  "order": [
+    ["layout.container.xs", "<=", "layout.container.sm"],
+    ["layout.container.sm", "<=", "layout.container.md"],
+    ["layout.container.md", "<=", "layout.container.lg"],
+    ["layout.container.lg", "<=", "layout.container.xl"],
+
+    ["layout.padding.page", ">=", "layout.padding.section"],
+    ["layout.padding.section", ">=", "layout.padding.card"],
+    ["layout.padding.card", ">=", "layout.padding.chip"],
+
+    ["layout.grid.gutter", "<=", "layout.padding.section"],
+    ["layout.grid.gutter", "<=", "layout.padding.card"],
+
+    ["control.size.min", ">=", "layout.padding.card"]
+  ]
+}

package/themes/layout.sm.order.json

@@ -0,0 +1,18 @@
+{
+  "$description": "Layout hierarchy order constraints - SM breakpoint specific",
+  "order": [
+    ["layout.container.xs", "<=", "layout.container.sm"],
+    ["layout.container.sm", "<=", "layout.container.md"],
+    ["layout.container.md", "<=", "layout.container.lg"],
+    ["layout.container.lg", "<=", "layout.container.xl"],
+
+    ["layout.padding.page", ">=", "layout.padding.section"],
+    ["layout.padding.section", ">=", "layout.padding.card"],
+    ["layout.padding.card", ">=", "layout.padding.chip"],
+
+    ["layout.grid.gutter", "<=", "layout.padding.section"],
+    ["layout.grid.gutter", "<=", "layout.padding.card"],
+
+    ["control.size.min", ">=", "layout.padding.card"]
+  ]
+}

package/themes/spacing.order.json

@@ -0,0 +1,14 @@
+{
+  "$description": "Spacing scale order constraints - defines monotonic spacing hierarchy",
+  "order": [
+    ["size.spacing.12", ">=", "size.spacing.10"],
+    ["size.spacing.10", ">=", "size.spacing.8"],
+    ["size.spacing.8", ">=", "size.spacing.6"],
+    ["size.spacing.6", ">=", "size.spacing.4"],
+    ["size.spacing.4", ">=", "size.spacing.3"],
+    ["size.spacing.3", ">=", "size.spacing.2-5"],
+    ["size.spacing.2-5", ">=", "size.spacing.2"],
+    ["size.spacing.2", ">=", "size.spacing.1"],
+    ["size.spacing.1", ">=", "size.spacing.0-5"]
+  ]
+}

package/themes/typography.lg.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Typography hierarchy order constraints - LG breakpoint specific",
+  "order": [
+    ["typography.size.h1", ">=", "typography.size.h2"],
+    ["typography.size.h2", ">=", "typography.size.h3"], 
+    ["typography.size.h3", ">=", "typography.size.h4"],
+    ["typography.size.h4", ">=", "typography.size.h5"],
+    ["typography.size.h5", ">=", "typography.size.h6"],
+    
+    ["typography.size.xl", ">=", "typography.size.lg"],
+    ["typography.size.lg", ">=", "typography.size.base"],
+    ["typography.size.base", ">=", "typography.size.sm"],
+    ["typography.size.sm", ">=", "typography.size.xs"]
+  ]
+}

package/themes/typography.md.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Typography hierarchy order constraints - MD breakpoint specific",
+  "order": [
+    ["typography.size.h1", ">=", "typography.size.h2"],
+    ["typography.size.h2", ">=", "typography.size.h3"], 
+    ["typography.size.h3", ">=", "typography.size.h4"],
+    ["typography.size.h4", ">=", "typography.size.h5"],
+    ["typography.size.h5", ">=", "typography.size.h6"],
+    
+    ["typography.size.xl", ">=", "typography.size.lg"],
+    ["typography.size.lg", ">=", "typography.size.base"],
+    ["typography.size.base", ">=", "typography.size.sm"],
+    ["typography.size.sm", ">=", "typography.size.xs"]
+  ]
+}

package/themes/typography.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Typography hierarchy order constraints - defines that h1 ≥ h2 ≥ ... ≥ h6 by font size",
+  "order": [
+    ["typography.size.h1", ">=", "typography.size.h2"],
+    ["typography.size.h2", ">=", "typography.size.h3"], 
+    ["typography.size.h3", ">=", "typography.size.h4"],
+    ["typography.size.h4", ">=", "typography.size.h5"],
+    ["typography.size.h5", ">=", "typography.size.h6"],
+    
+    ["typography.size.xl", ">=", "typography.size.lg"],
+    ["typography.size.lg", ">=", "typography.size.base"],
+    ["typography.size.base", ">=", "typography.size.sm"],
+    ["typography.size.sm", ">=", "typography.size.xs"]
+  ]
+}

package/themes/typography.sm.order.json

@@ -0,0 +1,15 @@
+{
+  "$description": "Typography hierarchy order constraints - SM breakpoint specific",
+  "order": [
+    ["typography.size.h1", ">=", "typography.size.h2"],
+    ["typography.size.h2", ">=", "typography.size.h3"], 
+    ["typography.size.h3", ">=", "typography.size.h4"],
+    ["typography.size.h4", ">=", "typography.size.h5"],
+    ["typography.size.h5", ">=", "typography.size.h6"],
+    
+    ["typography.size.xl", ">=", "typography.size.lg"],
+    ["typography.size.lg", ">=", "typography.size.base"],
+    ["typography.size.base", ">=", "typography.size.sm"],
+    ["typography.size.sm", ">=", "typography.size.xs"]
+  ]
+}

package/tokens/overrides/base.json

@@ -0,0 +1,22 @@
+{
+  "overrides": {
+    "color": {
+      "palette": {
+        "brand": {
+          "600": {
+            "$value": "oklch(0.620 0.180 171)"
+          }
+        }
+      }
+    },
+    "typography": {
+      "font": {
+        "body": {
+          "$value": "Lora"
+        }
+      }
+    }
+  },
+  "links": {},
+  "expressions": {}
+}

package/tokens/overrides/lg.json

@@ -0,0 +1,20 @@
+{
+  "type": {
+    "size": {
+      "h1": "oklch(0.15 0.01 0) 3rem/1.1 'Segoe UI', system-ui",
+      "h2": "oklch(0.15 0.01 0) 2.25rem/1.2 'Segoe UI', system-ui",
+      "body": "oklch(0.20 0.01 0) 1.125rem/1.7 'Segoe UI', system-ui"
+    },
+    "weight": {
+      "body": "300"
+    }
+  },
+  "dimension": {
+    "spacing": {
+      "scale": {
+        "section": "4rem",
+        "component": "2rem"
+      }
+    }
+  }
+}

package/tokens/overrides/md.json

@@ -0,0 +1,16 @@
+{
+  "type": {
+    "size": {
+      "h1": "oklch(0.15 0.01 0) 2.25rem/1.2 'Segoe UI', system-ui",
+      "body": "oklch(0.20 0.01 0) 1rem/1.6 'Segoe UI', system-ui"
+    }
+  },
+  "dimension": {
+    "spacing": {
+      "scale": {
+        "section": "2.5rem",
+        "component": "1.25rem"
+      }
+    }
+  }
+}

package/tokens/overrides/sm.json

@@ -0,0 +1,16 @@
+{
+  "type": {
+    "size": {
+      "body": "oklch(0.20 0.01 0) 0.875rem/1.5 'Segoe UI', system-ui",
+      "caption": "oklch(0.20 0.01 0) 0.75rem/1.4 'Segoe UI', system-ui"
+    }
+  },
+  "dimension": {
+    "spacing": {
+      "scale": {
+        "section": "1.5rem",
+        "component": "0.75rem"
+      }
+    }
+  }
+}

package/tokens/overrides/viol.color.json

@@ -0,0 +1,6 @@
+{
+  "overrides": {
+    "color.palette.brand.500": "oklch(62% 0.12 29)",
+    "color.palette.brand.600": "oklch(80% 0.10 29)"
+  }
+}

package/tokens/overrides/viol.typography.json

@@ -0,0 +1,6 @@
+{
+  "overrides": {
+    "typography.size.h1": "1rem",
+    "typography.size.h2": "1.25rem"
+  }
+}