Design Constraint Validator

设计约束验证器（DCV）

面向设计系统的数学约束验证器——确保一致性、可访问性和逻辑连贯性。

设计约束验证器（DCV） 可验证令牌集和样式中的设计约束：

• ✅ 可访问性： WCAG 文本对比度、感知亮度下限和上限
• ✅ 顺序与单调性： 递增的字体排版比例、间距层级
• ✅ 阈值与策略： 最小值／最大值范围、跨轴保护条件（尺寸 × 字重 × 对比度）
• ✅ 图智能： 导出 Hasse／偏序集图；提供带关联边说明的“原因”解释

这不是架构 lint 工具，而是用于值和关系的推理验证器。

---

安装

# 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

本地安装后即可使用更短的 dcv 可执行文件（例如 npx dcv --help）。

要求： Node.js ≥ 18.x（ESM）

---

快速开始

DCV 会根据你自己的约束验证你自己的令牌。在空目录中运行：

# 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

这些一次性命令使用完整的软件包名称，因为 npm 上的 dcv 可执行文件名称已属于一个无关的软件包。 执行 npm i -D design-constraint-validator 后， 请使用更短的 npx dcv …。

输出示例（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

发现违规时，退出代码为 1；验证通过时为 0（使用 --fail-on off 可始终以 0 退出）。内置的 WCAG／阈值默认规则针对随附示例中的令牌 ID，因此验证自己的令牌名称时，请像上面那样禁用这些规则。

---

编程 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;
}

完整的编程用法请参阅 API 参考。

---

在 AI Agent 中使用（MCP）

DCV 附带第二个二进制文件 dcv-mcp，可通过 MCP stdio 向 Agent 客户端提供验证功能。将其添加到 Claude Desktop 或通用 MCP 客户端配置中，如下所示：

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

该服务提供六个只读、返回 JSON 的工具：

• validate - 根据内联 constraints 或配置文件，验证内联 tokens 或 tokensPath。
• why - 说明一个令牌 ID 的来源、别名、依赖项、依赖方和别名链。
• graph - 返回令牌依赖关系的 nodes 和 edges。
• list-constraints - 列出给定输入中启用的约束（WCAG 对、阈值、顺序／亮度刻度、跨轴约束）。
• explain - 将违规情况转换为通俗易懂的文本及机器可读事实。
• suggest-fix - 为违规情况计算经过验证的满足条件的值（WCAG 颜色、阈值／单调边界），不会写入任何内容。

三个推导工具（list-constraints、explain、suggest-fix）均保持只读——它们会返回建议；是否应用建议由你决定（dcv set / dcv patch）。完整的 Agent 工作流请参阅 AI 指南。

工具失败时会返回结构化 JSON：{ "ok": false, "error": { "code": "...", "message": "..." } }。

---

文档

适合所有人

• 快速入门 - 5 分钟教程
• 功能与完整指南 - 所有功能、示例和常见问题
• 示例 - 示例项目和用例

适合用户

• 约束 - 详细介绍全部 5 种约束类型
• CLI 参考 - 完整的命令文档
• 配置 - 配置文件选项
• 概念 - 核心术语和默认值

适合开发者

• API 参考 - 程序化用法
• 架构 - 内部设计
• 适配器 - 输入／输出格式

更多资源

• 先前工作／方法 - 设计依据（决策主题、依据）
• AI 指南 - 使用 ChatGPT／Claude／Copilot 搭配 DCV
• 参与贡献 - 贡献指南
• 安全 - 供应链安全措施

---

为什么选择约束，而非惯例？

传统的代码检查工具会发现架构问题（“有值、有类型”）。 DCV 会强制执行对用户体验和品牌完整性至关重要的关系：

• 在所有主题和状态下保持清晰易读的对比度
• 合理的层级间距／排版（单调刻度）
• 协调一致的跨轴行为（例如，在需要时字号越大、字重越高）
• 符合策略要求（AA／AAA、内部阈值）

这样就能将令牌从“一堆数字”转变为形式化的设计系统。

---

对比：架构校验工具与 DCV

特性	架构校验工具	DCV
校验内容	JSON 结构、类型	数学关系、无障碍性
发现问题	缺少字段、类型错误	对比度违规、层级关系中断
目的	格式合规	设计系统完整性
示例	DTCG 架构校验器	WCAG 检查、单调刻度

DCV 与 Anima 的 design-tokens-validator（专注于架构）无关联。

---

输入格式

DCV 接受令牌 JSON（扁平或嵌套）和可选的策略 JSON。 适配器可规范化常见生态系统的数据：

• Style Dictionary - 参见 examples/style-dictionary/
• Tokens Studio JSON - 参见 examples/tokens-studio/
• DTCG（Design Tokens Community Group）— 支持读取 2025.10 稳定规范（结构化 sRGB 颜色、结构化尺寸、{alias} 引用、$extensions 透传；对非 sRGB 色彩空间发出警告而不会错误计算；不涵盖复合类型）。参见 examples/dtcg/

完整的适配器文档：适配器

---

DCV 与 DecisionThemes

DCV 是独立的校验引擎——可用于任何令牌系统。

DecisionThemes（将于 2026 年推出）是基于 DCV 构建的完整设计系统框架：

• 五轴决策模型（Tone、Emphasis、Size、Density、Shape）
• VT/DT 流水线（Value Themes + Decision Themes → 确定性的 CSS 配置）
• Studio UI + Hub 市场，用于分享 Decision Systems

DCV 为 DecisionThemes 提供校验层，但也可完美地独立运行。 预览：www.decisionthemes.com

---

方法与现有技术

Design Constraint Validator 引擎基于一套主题化和校验方法，该方法以防御性现有技术的形式发布。

如需了解底层架构（Decision Themes / Value Themes、确定性计算、计算后校验和回执）：

• Decision Themes 方法
• DCV 校验与回执

这些文档让该方法可公开实现，并防止专利垄断。

---

安全与供应链

SBOM（软件物料清单）

DCV 会生成符合 CycloneDX 标准的 SBOM，以提高供应链透明度：

• CI 构建： 每次 CI 运行都会生成 SBOM 构件（保留 90 天）
• 版本标签： 为发布标签生成 SBOM 构件
• GitHub Releases： 创建 GitHub Release 时，会附加 SBOM 文件（JSON + XML）
• 手动： 在项目根目录运行 npx @cyclonedx/cyclonedx-npm

下载：

• GitHub Actions 构件
• 最新版本

---

路线图

• 支持自定义约束的插件 API
• VS Code 诊断（内联说明）
• 跨轴规则包（排版 × 字重 × 对比度）
• 签名 / 可证明的回执——dcv validate --receipt 目前已会输出环境与输入内容哈希；密码学签名属于路线图规划
• UI 图表浏览器（节点检查器、违规项聚焦）

---

理念

约束，而非惯例。

设计系统需要数学保证。此验证器：

1. 强制执行关联关系——字体层级、颜色渐变
2. 验证无障碍性——通过 Alpha 合成计算 WCAG 对比度
3. 说明违规原因——通过来源追踪展示规则失败的原因
4. 随复杂度扩展——对数千个令牌进行增量验证

---

相关项目

这是核心验证引擎。如需了解具备 5 轴框架（语调、强调、尺寸、密度、形状）和主题配置器 UI 的完整决策驱动型设计系统，请参阅 DecisionThemes（即将推出）。

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md

---

许可证

MIT © Cseperke Papp