by tsubotax
人間にも、AIにも、読めるデザインシステム — AI-Ready Design System for Claude Code & Cursor
# Add to your Claude Code skills
git clone https://github.com/tsubotax/melta-ui人間にも、AIにも、読めるデザインシステム。
デザインシステムは、人間のためだけのものだった。 スタイルガイドを読み、コンポーネントの意図を汲み取り、文脈に合わせて判断する——それはデザイナーとエンジニアの仕事だった。
しかし今、UIを書くのは人間だけではない。
AIがコードを生成し、コンポーネントを選び、レイアウトを組む時代に、 デザインシステムは 「人間が読める」だけでは足りない。
melta UI は、この問いに対する一つの答えである。
人間の可読性を犠牲にせず、AIの可読性を加える。 両立こそが、melta UI の設計思想である。
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 で自動実行
| レイヤー | 形式 | 読み手 | 役割 | |---------|------|--------|------| | DESIGN.md | Markdown | AI(全エージェント) | デザイン憲法 + Quick Reference。これだけで基本 UI を生成可能 | | CLAUDE.md | Markdown | AI (Claude Code) | 作業手順・読み込みガイド・npm scripts | | contracts/ | JSON | AI + harness | 28 コンポーネント + 89 ルール + 99 トークンの厳密仕様 | | harness | TypeScript | CI | Schema 検証・drift 検出・Playwright + axe | | components/*.md | Markdown | 人間 | 設計意図・使い方・判断基準を自然言語で記述 | | docs/index.html | HTML | 人間 | 全コンポーネントのインタラクティブショーケース | | MCP サーバー | TypeScript | AI エージェント | トークン検索・コンポーネント取得・ルール検証をツールとして公開 |
| モード | 読むファイル | 用途 | |--------|------------|------| | クイック | のみ | 単体UIの生成 | | 標準 | + + contracts / component md | ページ単位の生成 | | MCP | / / / | AI ツール統合 | | フル | 全ファイル | 新規プロジェクト構築 |
No comments yet. Be the first to share your thoughts!
DESIGN.mdtheme.mdget_tokenget_componentcheck_ruleget_rules// 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" }
]
}
// 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 のみでカードを構成"
}
AI エージェントは MCP ツールを通じて、必要な情報だけをオンデマンドで取得する。
Human: 「ユーザー一覧テーブルを作って」
AI (内部):
1. get_component("table") → 仕様・HTMLサンプル取得
2. get_component("pagination") → ページ送り仕様取得
3. check_rule("text-black shadow-lg") → 禁止パターン検出
4. → DS準拠の HTML を生成
DESIGN.md + CLAUDE.md を自動で読み込む「ユーザー一覧のテーブルを作って」
→ table contract + badge contract を参照し、DS準拠のHTMLを生成
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/rules/ に 3 つのルールファイルを同梱:
melta-ui.mdc — DS 全体ルールcolor-system.mdc — カラートークン一覧components.mdc — 28 コンポーネントの Tailwind クラス一覧foundations/theme.md の CSS 変数をプロジェクトに追加DESIGN.md の Quick Reference を参照してクラスを適用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 の整合性
bg-primary-500 を使う。bg-blue-* は使わないshadow-sm 〜 shadow-md。shadow-lg 以上はオーバーレイ限定詳細は
foundations/design_philosophy.mdを参照。
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 |
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 用ルール
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 セクション。
MIT License — LICENSE
同梱アイコンのライセンスは THIRD_PARTY_LICENSES.md を参照。