{
  "markdown": "# Design Constraint Validator (DCV)\n\n> Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence.\n\n[![npm version](https://img.shields.io/npm/v/design-constraint-validator.svg)](https://www.npmjs.com/package/design-constraint-validator)\n[![npm downloads](https://img.shields.io/npm/dm/design-constraint-validator.svg)](https://www.npmjs.com/package/design-constraint-validator)\n[![CI](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/ci.yml)\n[![SBOM](https://img.shields.io/badge/SBOM-CycloneDX-brightgreen)](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/sbom.yml)\n[![Supply Chain Security](https://img.shields.io/badge/security-hardened-blue)](SECURITY.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18.x-339933.svg)](#)\n\n**Design Constraint Validator (DCV)** validates design constraints across token sets and styles:\n- ✅ **Accessibility:** WCAG text contrast, perceptual lightness floor/ceilings\n- ✅ **Order & Monotonicity:** increasing typography scales, spacing hierarchies\n- ✅ **Thresholds & Policies:** min/max ranges, cross-axis guards (size × weight × contrast)\n- ✅ **Graph Intelligence:** Hasse/poset graph export; \"why\" explanations with implicated edges\n\nThis is **not** a schema linter; it's a **reasoning validator** for values and relationships.\n\n![DCV at a glance — one engine with three entry points (CLI, Library API, MCP server) over a shared validation core that flattens tokens, builds the engine, loads constraints, runs plugins, and reports errors/warnings.](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-at-a-glance.png)\n\n![DCV validation pipeline — token files → flatten & resolve → build engine → load constraints → run plugins → report results; CLI, API, and MCP all use the same flow.](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-pipeline.png)\n\n---\n\n## Installation\n\n```bash\n# Local (recommended)\nnpm i -D design-constraint-validator\n\n# One-off run, no install (the bin name `dcv` belongs to an unrelated package)\nnpx design-constraint-validator --help\n```\n\nAfter a local install, the shorter `dcv` bin is available (e.g. `npx dcv --help`).\n\n**Requirements:** Node.js ≥ 18.x (ESM)\n\n---\n\n## Quick Start\n\nDCV validates **your** tokens against **your** constraints. From an empty directory:\n\n```bash\n# 1. Your design tokens (DTCG-style \"$value\")\ncat > tokens.json <<'JSON'\n{\n  \"color\": {\n    \"text\": { \"$value\": \"#888888\" },\n    \"bg\":   { \"$value\": \"#999999\" }\n  }\n}\nJSON\n\n# 2. Your constraints — auto-discovered as dcv.config.json in the cwd\ncat > dcv.config.json <<'JSON'\n{\n  \"constraints\": {\n    \"enableBuiltInWcagDefaults\": false,\n    \"enableBuiltInThreshold\": false,\n    \"wcag\": [\n      { \"foreground\": \"color.text\", \"background\": \"color.bg\", \"ratio\": 4.5, \"description\": \"Body text on background\" }\n    ]\n  }\n}\nJSON\n\n# 3. Validate (positional path or --tokens; exits non-zero on violations)\nnpx design-constraint-validator validate tokens.json --summary table\n\n# Explain one token (the tokenId is required)\nnpx design-constraint-validator why color.text --tokens tokens.json --format table\n\n# Export the dependency graph\nnpx design-constraint-validator graph --tokens tokens.json --format mermaid > graph.mmd\n```\n\n> These one-offs use the full package name because the bare `dcv` bin name on npm\n> belongs to an unrelated package. After `npm i -D design-constraint-validator`,\n> use the shorter `npx dcv …`.\n\n**Example output** (`validate`):\n\n```text\nvalidate: 1 error(s), 0 warning(s)\nERROR wcag-contrast  color.text|color.bg @ Body text on background — Contrast 1.24:1 < 4.5:1\nscope   rules  warnings  errors\n------  -----  --------  ------\nglobal  1      0         1\n```\n\nExit code is `1` when violations are found, `0` when clean (use `--fail-on off` to always exit `0`). The built-in WCAG/threshold defaults target the bundled example token ids, so disable them (as above) when validating your own token names.\n\n---\n\n## Programmatic API\n\n```ts\nimport { validate } from 'design-constraint-validator';\n\n// Synchronous. Point at files, or pass `tokens` / `constraints` inline.\nconst result = validate({\n  tokensPath: './tokens.json',\n  configPath: './dcv.config.json', // omit to auto-discover dcv.config.json in the cwd\n});\n\nif (!result.ok) {\n  for (const v of result.violations) {\n    console.log(`[${v.ruleId}] ${v.message}`);\n  }\n  process.exitCode = 1;\n}\n```\n\nSee **[API Reference](docs/API.md)** for complete programmatic usage.\n\n---\n\n## Use from AI agents (MCP)\n\nDCV ships a second binary, `dcv-mcp`, that exposes the validator over MCP stdio for agent clients. Add it to a Claude Desktop or generic MCP client config like this:\n\n```json\n{\n  \"mcpServers\": {\n    \"dcv\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"--package\", \"design-constraint-validator\", \"dcv-mcp\"]\n    }\n  }\n}\n```\n\nThe server exposes six read-only, JSON-returning tools:\n\n- `validate` - validate inline `tokens` or a `tokensPath` against inline `constraints` or a config file.\n- `why` - explain provenance, aliases, dependencies, dependents, and alias chain for one token id.\n- `graph` - return token dependency `nodes` and `edges`.\n- `list-constraints` - enumerate the active constraints (WCAG pairs, thresholds, order/lightness scales, cross-axis) for the given input.\n- `explain` - turn a violation into plain-English text plus machine-readable facts.\n- `suggest-fix` - compute a verified satisfying value for a violation (WCAG color, threshold/monotonic boundary) without writing anything.\n\nThe three derivation tools (`list-constraints`, `explain`, `suggest-fix`) stay read-only — they return suggestions; applying them is up to you (`dcv set` / `dcv patch`). See **[AI Guide](docs/AI-GUIDE.md)** for the full agent loop.\n\nTool failures are returned as structured JSON: `{ \"ok\": false, \"error\": { \"code\": \"...\", \"message\": \"...\" } }`.\n\n---\n\n## Documentation\n\n### For Everyone\n- **[Getting Started](docs/Getting-Started.md)** - 5-minute tutorial\n- **[Features & Complete Guide](docs/Features.md)** - All features, examples, and FAQ\n- **[Examples](docs/Examples.md)** - Sample projects and use cases\n\n### For Users\n- **[Constraints](docs/Constraints.md)** - All 5 constraint types in detail\n- **[CLI Reference](docs/CLI.md)** - Complete command documentation\n- **[Configuration](docs/Configuration.md)** - Config file options\n- **[Concepts](docs/Concepts.md)** - Core terminology and defaults\n\n### For Developers\n- **[API Reference](docs/API.md)** - Programmatic usage\n- **[Architecture](docs/Architecture.md)** - Internal design\n- **[Adapters](docs/Adapters.md)** - Input/output formats\n\n### Additional Resources\n- **[Prior Art / Method](docs/prior-art/)** - Design rationale (Decision Themes, receipts)\n- **[AI Guide](docs/AI-GUIDE.md)** - Using DCV with ChatGPT/Claude/Copilot\n- **[Contributing](CONTRIBUTING.md)** - Contribution guidelines\n- **[Security](SECURITY.md)** - Supply chain security measures\n\n---\n\n## Why Constraints, Not Conventions?\n\nConventional linters catch **schema** issues (\"has a value, has a type\").\n**DCV** enforces **relationships** that matter to users and brand integrity:\n\n- Legible contrast under all themes and states\n- Proper hierarchical spacing/typography (monotonic scales)\n- Coherent cross-axis behavior (e.g., weight increases with size where needed)\n- Policy conformance (AA/AAA, internal thresholds)\n\nThis transforms tokens from \"bags of numbers\" into a **formal design system**.\n\n![What DCV checks — five plugin families: WCAG contrast, monotonic order, lightness ordering, thresholds, and cross-axis rules; every plugin returns a structured issue (rule, level, message, involved tokens, metadata).](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-plugins.png)\n\n---\n\n## Comparison: Schema Linters vs DCV\n\n| Feature | Schema Linters | DCV |\n|---------|----------------|-----|\n| **Validates** | JSON structure, types | Mathematical relationships, accessibility |\n| **Catches** | Missing fields, wrong types | Contrast violations, hierarchy breaks |\n| **Purpose** | Format compliance | Design system integrity |\n| **Examples** | DTCG schema validator | WCAG checks, monotonic scales |\n\n![Mathematical Integrity for Design Systems — the DCV engine: the three core constraint types (accessibility & contrast, monotonic & lightness ordering, thresholds & cross-axis rules), one engine with three interfaces (CLI, library API, MCP server), and the difference between schema linters (format compliance) and DCV (mathematical relationships / design-system integrity).](https://raw.githubusercontent.com/CseperkePapp/design-constraint-validator/main/images/dcv-overview.png)\n\n> DCV is not affiliated with Anima's `design-tokens-validator` (schema-focused).\n\n---\n\n## Input Formats\n\nDCV accepts **token JSON** (flat or nested) and optional **policy JSON**.\nAdapters normalize common ecosystems:\n\n- **Style Dictionary** - See [examples/style-dictionary/](examples/style-dictionary/)\n- **Tokens Studio JSON** - See [examples/tokens-studio/](examples/tokens-studio/)\n- **DTCG** (Design Tokens Community Group) — reads the **2025.10 stable spec** (structured sRGB colors, structured dimensions, `{alias}` references, `$extensions` passthrough; non-sRGB spaces warn rather than mis-calculate; composite types out of scope). See [examples/dtcg/](examples/dtcg/)\n\nFull adapter documentation: **[Adapters](docs/Adapters.md)**\n\n---\n\n## DCV & DecisionThemes\n\nDCV is the **standalone validation engine** — use it for any token system.\n\n**DecisionThemes** (coming 2026) is a complete design system framework built on DCV:\n- **5-axis decision model** (Tone, Emphasis, Size, Density, Shape)\n- **VT/DT pipeline** (Value Themes + Decision Themes → deterministic CSS configs)\n- **Studio UI** + **Hub marketplace** for sharing Decision Systems\n\nDCV powers DecisionThemes' validation layer — but works perfectly standalone.\nPreview: [www.decisionthemes.com](https://www.decisionthemes.com)\n\n---\n\n## Method & Prior Art\n\nThe Design Constraint Validator engine is based on a theming and validation method published as **defensive prior art**.\n\nTo understand the underlying architecture (Decision Themes / Value Themes, deterministic compute, post-compute validation and receipts):\n\n- [Decision Themes Method](docs/prior-art/Decision-Themes-Deterministic-Compute-and-Dual-Namespaces.md)\n- [DCV Validation & Receipts](docs/prior-art/DCV-Post-Compute-Validation-and-Receipts.md)\n\nThese documents keep the method openly implementable and prevent patent lock-up.\n\n---\n\n## Security & Supply Chain\n\n### SBOM (Software Bill of Materials)\n\nDCV generates CycloneDX-compliant SBOMs for supply chain transparency:\n\n- **CI Builds:** SBOM artifacts on every CI run (90-day retention)\n- **Version tags:** SBOM artifacts for release tags\n- **GitHub Releases:** SBOM files (JSON + XML) attached when a GitHub Release is created\n- **Manual:** Run `npx @cyclonedx/cyclonedx-npm` in project root\n\n**Download:**\n- [GitHub Actions Artifacts](https://github.com/CseperkePapp/design-constraint-validator/actions/workflows/sbom.yml)\n- [Latest Release](https://github.com/CseperkePapp/design-constraint-validator/releases/latest)\n\n---\n\n## Roadmap\n\n- Plugin API for **custom constraints**\n- **VS Code** diagnostics (inline explain)\n- **Cross-axis packs** (typography × weight × contrast)\n- **Signed / attestable receipts** — `dcv validate --receipt` already emits environment + input content hashes today; cryptographic **signing** is the roadmap part\n- UI graph explorer (node inspector, violations focus)\n\n---\n\n## Philosophy\n\n> **Constraints, not conventions.**\n\nDesign systems need mathematical guarantees. This validator:\n\n1. **Enforces relationships** - Typography hierarchies, color progressions\n2. **Validates accessibility** - WCAG contrast with alpha compositing\n3. **Explains violations** - Provenance tracing shows why rules fail\n4. **Scales with complexity** - Incremental validation of 1000s of tokens\n\n---\n\n## Related Projects\n\nThis is the **core validation engine**. For a complete decision-driven design system with a 5-axis framework (Tone, Emphasis, Size, Density, Shape) and theme configurator UI, see **DecisionThemes** (coming soon).\n\n---\n\n## Contributing\n\nContributions welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)**\n\n---\n\n## License\n\n[MIT](LICENSE) © Cseperke Papp\n",
  "bytes": 12624,
  "sha": "bf1b90a4ae7d067efefab0b6d27f8779a6fcccae82183407b8320b92342fa015",
  "repo_slug": "cseperkepapp/design-constraint-validator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cseperkepapp_design_constraint_489e37e7/readme"
}