io.github.CseperkePapp/design-constraint-validator

Official

by CseperkePapp · TypeScript

Design Constraint Validator

Validate design tokens for accessibility, scales, and design-system constraint consistency.

Validates design tokens for accessibility, scales, and design system compliance.

README.md12 KBView on GitHub

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.

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.

DCV validation pipeline — token files → flatten & resolve → build engine → load constraints → run plugins → report results; CLI, API, and MCP all use the same flow.

Installation

bash

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

bash

# 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):

text

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:

json

{
  "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.

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

Comparison: Schema Linters vs DCV

Feature	Schema Linters	DCV
Validates	JSON structure, types	Mathematical relationships, accessibility
Catches	Missing fields, wrong types	Contrast violations, hierarchy breaks
Purpose	Format compliance	Design system integrity
Examples	DTCG schema validator	WCAG checks, monotonic scales

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

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

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:

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:

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

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

Install

claude_desktop_config.json

{
  "mcpServers": {
    "design-constraint-validator": {
      "command": "npx",
      "args": [
        "-y",
        "design-constraint-validator@2.3.0"
      ]
    }
  }
}