2. 機械可読な仕様 — 解釈ではなく参照

// design/contracts/components/button.contract.json
{
  "id": "button",
  "variants": {
    "contained": {
      "tokenRefs": { "bg": "color.primary.500", "radius": "radius.md" },
      "tailwind": "inline-flex items-center justify-center gap-2 h-10 px-4 ..."
    }
  },
  "rules": [
    { "id": "SPACE_NO_PY_05_BTN", "severity": "error" },
    { "id": "BTN_ICON_ONLY_ARIA_REQUIRED", "severity": "error" }
  ]
}

3. 89 ルールの禁止パターン — AI が間違えても検知される

// design/contracts/rules.json
{
  "id": "AI_NO_CARD_COLOR_BAR_TOP",
  "severity": "error",
  "detector": "tailwind-class",
  "pattern": "border-t-4",
  "alternative": "border border-slate-200 のみでカードを構成"
}

4. MCP サーバー — 対話的なアクセス

AI エージェントは MCP ツールを通じて、必要な情報だけをオンデマンドで取得する。

Human: 「ユーザー一覧テーブルを作って」

AI (内部):
  1. get_component("table")   → 仕様・HTMLサンプル取得
  2. get_component("pagination") → ページ送り仕様取得
  3. check_rule("text-black shadow-lg") → 禁止パターン検出
  4. → DS準拠の HTML を生成

Quick Start

Claude Code

1. このリポジトリをプロジェクトルートに配置する
2. Claude Code が DESIGN.md + CLAUDE.md を自動で読み込む
3. UI を指示するだけで DS 準拠のコードが生成される

「ユーザー一覧のテーブルを作って」
→ table contract + badge contract を参照し、DS準拠のHTMLを生成

MCP サーバー（Claude Code / Cursor）

npm install && npm run build
claude mcp add melta-ui node ./dist/index.js

| ツール | 説明 | 入力例 | |--------|------|--------| | get_token | トークン検索 | { "path": "color.primary.600" } | | get_component | コンポーネント仕様取得 | { "id": "button" } | | check_rule | 禁止パターンチェック（32パターン自動検出） | { "classes": "text-black shadow-2xl" } | | get_rules | 89 ルール参照（manual 含む全件、filter 対応） | { "category": "accessibility" } | | search | 全文検索 | { "query": "card" } |

| Resource | 内容 | |----------|------| | melta://tokens | トークン全体 | | melta://components | 28 コンポーネント仕様 | | melta://components/{id} | 個別コンポーネント | | melta://rules | 89 禁止ルール全件（manual含む） | | melta://rules/auto-detectable | 自動検出可能サブセット（check_rule 用） |

Cursor

.cursor/rules/ に 3 つのルールファイルを同梱:

• melta-ui.mdc — DS 全体ルール
• color-system.mdc — カラートークン一覧
• components.mdc — 28 コンポーネントの Tailwind クラス一覧

手動

1. Tailwind CSS 4 をプロジェクトに導入
2. foundations/theme.md の CSS 変数をプロジェクトに追加
3. DESIGN.md の Quick Reference を参照してクラスを適用

npm Scripts

npm run design:check          # Schema + ルール + tokenRef 検証
npm run design:drift           # ドキュメント ↔ contracts の drift 検出
npm run design:build           # contract → metadata/components.json 生成 + tsc
npm run design:update-showcase # showcase の数値を contracts から自動更新
npm test                       # Playwright + axe-core（9テスト）
npm run benchmark              # 1.0 vs 2.0 A/B ベンチマーク（multi-provider, 要 API キー）
npm run build                  # TypeScript → dist/（MCP サーバー）
npm run validate               # tokens.json vs CSS の整合性

Design Principles

1. Content First — UI は黒子。コンテンツが主役
2. WCAG 2.1 AA — コントラスト 4.5:1 以上。アクセシビリティはデフォルト
3. Semantic Color — bg-primary-500 を使う。bg-blue-* は使わない
4. 3-Color Rule — 1 画面に使う色は 3 色まで
5. 4px Grid — スペーシングは 4 の倍数を基本
6. Minimal Elevation — shadow-sm 〜 shadow-md。shadow-lg 以上はオーバーレイ限定
7. No AI-ish Decoration — カラーバー禁止。全周ボーダーで構成

詳細は foundations/design_philosophy.md を参照。

Components

28 コンポーネント + 10 ファウンデーション + 5 パターン。

| カテゴリ | コンポーネント | |---------|--------------| | 入力 | Button, TextField, Select, Checkbox, Radio, Toggle, Date Picker | | ナビゲーション | Sidebar, Tabs, Breadcrumb, Pagination, Stepper, Accordion | | データ表示 | Card, Table, List, Badge, Tag, Avatar, Progress, Divider | | フィードバック | Modal, Toast, Alert, Tooltip, Skeleton, Copy Button, Dropdown |

Directory

melta-ui/
├── DESIGN.md                        # AI 向けデザイン憲法 + Quick Reference
├── CLAUDE.md                        # Claude Code 作業手順書
├── design/
│   ├── authority.md                 # SSOT 宣言
│   ├── contracts/
│   │   ├── tokens.json              # 99 デザイントークン
│   │   ├── rules.json               # 89 禁止ルール registry
│   │   └── components/              # 28 コンポーネント contract
│   ├── schemas/                     # JSON Schema（rule + component-contract）
│   └── benchmarks/                  # Agent benchmark（prompt + rubric）
├── foundations/                      # 設計基盤（13 ファイル）
├── components/                      # コンポーネント仕様（28 ファイル）
├── patterns/                        # パターン（5 ファイル）
├── metadata/components.json         # MCP 用集約データ（contracts から生成）
├── src/                             # MCP サーバー（TypeScript）
├── scripts/design/                  # validate / drift-check / build-legacy / update-showcase
├── tests/                           # Playwright + axe-core
├── docs/                            # ショーケース + OG 画像
├── examples/                        # 16 サンプルページ
├── assets/icons/                    # Charcoal 207 + Lucide 15
├── .github/workflows/               # CI（design:check + drift + test）
├── .mcp.json                        # Claude Code MCP 登録
└── .cursor/rules/                   # Cursor 用ルール

Benchmark — AI が DS をどれだけ参照するかを実測

design/benchmarks/ は「AI-Ready 1.0（旧 CLAUDE.md）」と「AI-Ready 2.0（DESIGN.md + contracts）」を同一 prompt で比較するハーネス。provider 抽象化済みで、Anthropic / fixture / OpenAI（後続） を切り替えられる。

# Anthropic で全 prompt を実行（ANTHROPIC_API_KEY が必要）
npm run benchmark

# 特定 prompt のみ
npm run benchmark -- --prompt 1
npm run benchmark -- --prompt R-1   # red-team

# モデル切替
npm run benchmark -- --provider anthropic --model claude-sonnet-4-20250514

# API なしで既存 results を score だけする（fixture）
npm run benchmark -- --provider fixture --fixture-run 2026-04-11

# 既存 HTML を上書きせず score だけ走らせる
npm run benchmark -- --skip-generate

Anthropic provider は MCP の5 tool（get_token / get_component / check_rule / get_rules / search）を Claude API の tool use として渡す。AI が実際に何回どの tool を呼んだか、どの resource を参照したかを report.md に記録する。これが「AI-Ready DS が本当に効いているか」の研究目的の核（docs/ai-ready-quality-gate-plan.md line 574）。

red-team prompt は5本（neon / heavy shadow / color bar / placeholder-only form / icon-only buttons）。

詳細仕様: docs/ai-ready-quality-gate-plan.md の P4 セクション。

License

MIT License — LICENSE

同梱アイコンのライセンスは THIRD_PARTY_LICENSES.md を参照。

Acknowledgments

• Charcoal Icons（pixiv Inc.）— Apache License 2.0
• Lucide Icons — ISC License
• Tailwind CSS