Design Constraint Validator

Design Constraint Validator（DCV）

デザインシステム向けの数学的制約バリデーター — 一貫性、アクセシビリティ、論理的な整合性を確保します。

**Design Constraint Validator（DCV）**は、トークンセットとスタイル全体でデザイン制約を検証します。

• ✅ アクセシビリティ： WCAG のテキストコントラスト、知覚的な明度の下限／上限
• ✅ 順序と単調性： 増加するタイポグラフィスケール、スペーシング階層
• ✅ しきい値とポリシー： 最小／最大の範囲、軸をまたぐガード（サイズ × ウェイト × コントラスト）
• ✅ グラフインテリジェンス： Hasse／poset グラフのエクスポート、関連するエッジを示す「理由」の説明

これはスキーマリンターではなく、値と関係性を検証する推論型バリデーターです。

---

インストール

# 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 です（常に 0 で終了するには --fail-on off を使用してください）。組み込みの 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 エージェントからの使用（MCP）

DCV には、エージェントクライアント向けに MCP stdio 経由でバリデーターを公開する 2 つ目のバイナリ dcv-mcp が含まれています。次のように、Claude Desktop または汎用 MCP クライアントの設定に追加してください。

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

サーバーは、読み取り専用で JSON を返す次の 6 つのツールを公開します。

• validate - インラインの tokens または tokensPath を、インラインの constraints または設定ファイルに照らして検証します。
• why - 1 つのトークン ID について、出所、エイリアス、依存関係、被依存関係、エイリアスチェーンを説明します。
• graph - トークン依存関係の nodes と edges を返します。
• list-constraints - 指定された入力に対して有効な制約（WCAG のペア、しきい値、順序／明度スケール、クロス軸）を列挙します。
• explain - 違反を平易な英語の説明と機械可読な事実に変換します。
• suggest-fix - 違反を満たす値を検証して算出します（WCAG の色、しきい値／単調性の境界）。何も書き込みません。

3 つの導出ツール（list-constraints、explain、suggest-fix）は読み取り専用です。提案を返すだけで、適用するかどうかはユーザーに委ねられます（dcv set ／ dcv patch）。エージェントの一連の処理については、AI Guide を参照してください。

ツールの失敗は、構造化 JSON として返されます：{ "ok": false, "error": { "code": "...", "message": "..." } }。

---

ドキュメント

すべてのユーザー向け

• はじめに - 5 分間のチュートリアル
• 機能と完全ガイド - すべての機能、例、FAQ
• 例 - サンプルプロジェクトとユースケース

ユーザー向け

• 制約 - 5 種類すべての制約の詳細
• CLI リファレンス - コマンドの完全なドキュメント
• 設定 - 設定ファイルのオプション
• 概念 - 基本用語とデフォルト設定

開発者向け

• API リファレンス - プログラムからの使用方法
• アーキテクチャ - 内部設計
• アダプター - 入出力形式

その他のリソース

• 先行事例／手法 - 設計の根拠（Decision Themes、根拠資料）
• 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/ を参照

アダプターのドキュメント全文：Adapters

---

DCV と DecisionThemes

DCV はスタンドアロンの検証エンジンです。あらゆるトークンシステムに使用できます。

DecisionThemes（2026 年公開予定）は、DCV を基盤とする完全なデザインシステムフレームワークです。

• 5 軸の意思決定モデル（Tone、Emphasis、Size、Density、Shape）
• VT/DT パイプライン（Value Themes + Decision Themes → 決定論的な CSS 設定）
• 共有可能な Decision Systems のための Studio UI + Hub マーケットプレイス

DCV は DecisionThemes の検証レイヤーを支えますが、スタンドアロンでも問題なく動作します。 プレビュー：www.decisionthemes.com

---

手法と先行技術

Design Constraint Validator エンジンは、防御的な先行技術として公開されたテーマ設定および検証手法を基盤としています。

基盤となるアーキテクチャ（Decision Themes / Value Themes、決定論的な計算、計算後の検証とレシート）については、以下を参照してください。

• Decision Themes Method
• DCV Validation & Receipts

これらのドキュメントにより、この手法を誰でも実装できる状態に保ち、特許による独占を防ぎます。

---

セキュリティとサプライチェーン

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. アクセシビリティを検証します - アルファ合成を考慮した WCAG のコントラスト
3. 違反の理由を説明します - 出所の追跡により、ルールに違反する理由がわかります
4. 複雑さに応じて拡張できます - 数千のトークンを段階的に検証します

---

関連プロジェクト

これはコア検証エンジンです。5 軸のフレームワーク（トーン、強調、サイズ、密度、形状）とテーマ設定 UI を備えた、意思決定主導の完全なデザインシステムについては、DecisionThemes（近日公開）をご覧ください。

---

コントリビュート

コントリビュートを歓迎します！**CONTRIBUTING.md**をご覧ください。

---

ライセンス

MIT © Cseperke Papp