melta UI

人間にも、AIにも、読めるデザインシステム。

🤖 Built for AI coding agents — Claude Code / Cursor / Codex が DESIGN.md と JSON contracts を読んで DS 準拠の UI を生成し、CI で違反を検知する。

デザインシステムは、人間のためだけのものだった。 スタイルガイドを読み、コンポーネントの意図を汲み取り、文脈に合わせて判断する——それはデザイナーとエンジニアの仕事だった。

しかし今、UIを書くのは人間だけではない。

AIがコードを生成し、コンポーネントを選び、レイアウトを組む時代に、 デザインシステムは 「人間が読める」だけでは足りない。

melta UI は、この問いに対する一つの答えである。

人間の可読性を犠牲にせず、AIの可読性を加える。 両立こそが、melta UI の設計思想である。

Architecture — AI-Ready 2.0

3 層構造で「AI が迷わない、間違えにくい、間違えても検知される」を実現する。

Layer 1: 憲法（AI が最初に読む入口）
  DESIGN.md          ← Brand Identity + 7原則 + Quick Reference
  CLAUDE.md          ← Claude Code 作業手順書

Layer 2: 仕様（Machine-Readable SSOT）
  design/contracts/
    ├── tokens.json   ← 99 デザイントークン
    ├── rules.json    ← 89 禁止ルール（ID + severity + detector）
    └── components/   ← 28 contract（variant + size + a11y + rules）

Layer 3: 検証（破っても通さない）
  scripts/design/     ← validate / drift-check / build-legacy / update-showcase
  tests/              ← Playwright + axe-core（9テスト）
  .github/workflows/  ← CI で自動実行

AI にとっての読みやすさ

1. 段階的読み込み — コンテキストを浪費しない

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

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 パターン。

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