Design Constraint Validator

Design Constraint Validator (DCV)

Mathematical constraint validator for design systems — ensuring consistency, accessibility, and logical coherence.

Design Constraint Validator (DCV) validates design constraints across token sets and styles:

• ✅ Accessibility: WCAG text contrast, perceptual lightness floor/ceilings
• ✅ Order & Monotonicity: increasing typography scales, spacing hierarchies
• ✅ Thresholds & Policies: min/max ranges, cross-axis guards (size × weight × contrast)
• ✅ Graph Intelligence: Hasse/poset graph export; "why" explanations with implicated edges

This is not a schema linter; it's a reasoning validator for values and relationships.

---

Installation

# Local (recommended)
npm i -D design-constraint-validator

# One-off run, no install (the bin name `dcv` belongs to an unrelated package)
npx design-constraint-validator --help

After a local install, the shorter dcv bin is available (e.g. npx dcv --help).

Requirements: Node.js ≥ 18.x (ESM)

---

Quick Start

DCV validates your tokens against your constraints. From an empty directory:

# 1. Your design tokens (DTCG-style "$value")
cat > tokens.json <<'JSON'
{
  "color": {
    "text": { "$value": "#888888" },
    "bg":   { "$value": "#999999" }
  }
}
JSON

# 2. Your constraints — auto-discovered as dcv.config.json in the cwd
cat > dcv.config.json <<'JSON'
{
  "constraints": {
    "enableBuiltInWcagDefaults": false,
    "enableBuiltInThreshold": false,
    "wcag": [
      { "foreground": "color.text", "background": "color.bg", "ratio": 4.5, "description": "Body text on background" }
    ]
  }
}
JSON

# 3. Validate (positional path or --tokens; exits non-zero on violations)
npx design-constraint-validator validate tokens.json --summary table

# Explain one token (the tokenId is required)
npx design-constraint-validator why color.text --tokens tokens.json --format table

# Export the dependency graph
npx design-constraint-validator graph --tokens tokens.json --format mermaid > graph.mmd

These one-offs use the full package name because the bare dcv bin name on npm belongs to an unrelated package. After npm i -D design-constraint-validator, use the shorter npx dcv ….

Example output (validate):

validate: 1 error(s), 0 warning(s)
ERROR wcag-contrast  color.text|color.bg @ Body text on background — Contrast 1.24:1 < 4.5:1
scope   rules  warnings  errors
------  -----  --------  ------
global  1      0         1

Exit 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.

---

Programmatic API

import { validate } from 'design-constraint-validator';

// Synchronous. Point at files, or pass `tokens` / `constraints` inline.
const result = validate({
  tokensPath: './tokens.json',
  configPath: './dcv.config.json', // omit to auto-discover dcv.config.json in the cwd
});

if (!result.ok) {
  for (const v of result.violations) {
    console.log(`[${v.ruleId}] ${v.message}`);
  }
  process.exitCode = 1;
}

See API Reference for complete programmatic usage.

---

Use from AI agents (MCP)

DCV 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:

{
  "mcpServers": {
    "dcv": {
      "command": "npx",
      "args": ["-y", "--package", "design-constraint-validator", "dcv-mcp"]
    }
  }
}

The server exposes six read-only, JSON-returning tools:

• validate - validate inline tokens or a tokensPath against inline constraints or a config file.
• why - explain provenance, aliases, dependencies, dependents, and alias chain for one token id.
• graph - return token dependency nodes and edges.
• list-constraints - enumerate the active constraints (WCAG pairs, thresholds, order/lightness scales, cross-axis) for the given input.
• explain - turn a violation into plain-English text plus machine-readable facts.
• suggest-fix - compute a verified satisfying value for a violation (WCAG color, threshold/monotonic boundary) without writing anything.

The 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 for the full agent loop.

Tool failures are returned as structured JSON: { "ok": false, "error": { "code": "...", "message": "..." } }.

---

Documentation

For Everyone

• Getting Started - 5-minute tutorial
• Features & Complete Guide - All features, examples, and FAQ
• Examples - Sample projects and use cases

For Users

• Constraints - All 5 constraint types in detail
• CLI Reference - Complete command documentation
• Configuration - Config file options
• Concepts - Core terminology and defaults

For Developers

• API Reference - Programmatic usage
• Architecture - Internal design
• Adapters - Input/output formats

Additional Resources

• Prior Art / Method - Design rationale (Decision Themes, receipts)
• AI Guide - Using DCV with ChatGPT/Claude/Copilot
• Contributing - Contribution guidelines
• Security - Supply chain security measures

---

Why Constraints, Not Conventions?

Conventional linters catch schema issues ("has a value, has a type"). DCV enforces relationships that matter to users and brand integrity:

• Legible contrast under all themes and states
• Proper hierarchical spacing/typography (monotonic scales)
• Coherent cross-axis behavior (e.g., weight increases with size where needed)
• Policy conformance (AA/AAA, internal thresholds)

This transforms tokens from "bags of numbers" into a formal design system.

---

Comparison: Schema Linters vs DCV

DCV is not affiliated with Anima's design-tokens-validator (schema-focused).

---

Input Formats

DCV accepts token JSON (flat or nested) and optional policy JSON. Adapters normalize common ecosystems:

• Style Dictionary - See examples/style-dictionary/
• Tokens Studio JSON - See examples/tokens-studio/
• 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/

Full adapter documentation: Adapters

---

DCV & DecisionThemes

DCV is the standalone validation engine — use it for any token system.

DecisionThemes (coming 2026) is a complete design system framework built on DCV:

• 5-axis decision model (Tone, Emphasis, Size, Density, Shape)
• VT/DT pipeline (Value Themes + Decision Themes → deterministic CSS configs)
• Studio UI + Hub marketplace for sharing Decision Systems

DCV powers DecisionThemes' validation layer — but works perfectly standalone. Preview: www.decisionthemes.com

---

Method & Prior Art

The Design Constraint Validator engine is based on a theming and validation method published as defensive prior art.

To understand the underlying architecture (Decision Themes / Value Themes, deterministic compute, post-compute validation and receipts):

• Decision Themes Method
• DCV Validation & Receipts

These documents keep the method openly implementable and prevent patent lock-up.

---

Security & Supply Chain

SBOM (Software Bill of Materials)

DCV generates CycloneDX-compliant SBOMs for supply chain transparency:

• CI Builds: SBOM artifacts on every CI run (90-day retention)
• Version tags: SBOM artifacts for release tags
• GitHub Releases: SBOM files (JSON + XML) attached when a GitHub Release is created
• Manual: Run npx @cyclonedx/cyclonedx-npm in project root

Download:

• GitHub Actions Artifacts
• Latest Release

---

Roadmap

• Plugin API for custom constraints
• VS Code diagnostics (inline explain)
• Cross-axis packs (typography × weight × contrast)
• Signed / attestable receipts — dcv validate --receipt already emits environment + input content hashes today; cryptographic signing is the roadmap part
• UI graph explorer (node inspector, violations focus)

---

Philosophy

Constraints, not conventions.

Design systems need mathematical guarantees. This validator:

1. Enforces relationships - Typography hierarchies, color progressions
2. Validates accessibility - WCAG contrast with alpha compositing
3. Explains violations - Provenance tracing shows why rules fail
4. Scales with complexity - Incremental validation of 1000s of tokens

---

Related Projects

This 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).

---

Contributing

Contributions welcome! See CONTRIBUTING.md

---

License

MIT © Cseperke Papp