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/   ← npm: melta-contracts（web / APP 両実装が購読）
    ├── tokens.json   ← 99 デザイントークン
    ├── rules.json    ← 99 禁止ルール（ID + severity + detector）
    ├── components/   ← 40 contract（web 28 + app 先行 12。variant + size + a11y + rules）
    └── recipes/      ← プラットフォーム具象（web: Tailwind 生成ミラー / app: RN styleRefs）

Layer 3: 検証（破っても通さない）
  scripts/design/     ← validate / drift-check / lint-generated / build-legacy / update-showcase
  tests/              ← Playwright + axe-core
  .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. 99 ルールの禁止パターン — 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. → DS準拠の HTML を生成
  4. check_html(生成したHTML) → CI と同一ロジックで自己検証
  5. 違反があれば修正して再検証 → 提示

5. Enforcement — 書いた直後に検知して直させる

「読める」だけでは AI-Ready ではない。違反コードが書かれた瞬間に検知し、修正ループに乗せる 3 層を同梱する。

hook は npm install 後に有効（未インストール時はその旨をコンテキストに通知）。Claude Code 以外のエージェントには CI + CLI が代替層。

検証カバレッジ（npm run design:coverage で再生成）

「宣言だけ」を排し、99 ルールがどの経路で検証されているかを経路別に出す。

「宣言だけで検知ゼロ」だった a11y ルール 7 件を棚卸しし、3 件を DOM 検証で蘇生（icon-only button / ×ボタン / skeleton の aria）、4 件は静的不能/test 担保として automationStatus で明示。各ルールの状態は rules.json の automationStatus フィールドが SSOT。

6. Loop governance — 「守らせ続けられる」を仕組みにする

AI-Ready の本質は「一度守らせる」ことではなく「破られ続けないこと」。自動化を 3 Level に分類し、何を loop に任せ・何を人間が決めるかを docs/melta-loop-playbook.md で固定する。

統治の核は 2 つ。SSOT write-protect（loop は generated / derived / 提案のみ write 可。contracts・tokens・rules・schema は human gate）と、Human Gate の Hard（パスで機械強制）/ Soft（意味変更は人間判断）2 層化。

現状 W2 drift repair が稼働（npm run design:drift-heal：drift 検出 → derived のみ再生成 → SSOT に触れたら escalate / auto-commit せず diff を出して停止 / 監査ログ .melta-loop/runs.jsonl）。W1 UI 自己修復・W3 benchmark・W4 red-team・W5 release readiness は playbook 定義済みで順次実装。loop playbook 自身も npm run design:drift の監視対象に入っており、陳腐化を検知する。

7. マルチプラットフォーム契約 — 1 つの契約が web と APP に降りる

同じ契約パッケージ（npm: melta-contracts）を web（melta-ui / HTML + Tailwind）と APP（melta-app / React Native）の両実装が購読する。token を各実装にコピーして持つ経路は存在しない（二重化の物理防止）。

契約は規範と具象の 2 層で持つ:

• 規範（components/*.contract.json）: variant の語彙・states・tokenRefs・a11y。全プラットフォーム共通で、語彙の分岐は契約違反。分岐が正当な箇所（hover→pressed、elevation の表現差、タッチターゲット 44pt 等）は platformSemantics で意味論だけを宣言する
• 具象（recipes/）: web は契約の Tailwind から生成される導出ミラー（鮮度を CI が担保）、app は RN の styleRefs（{"token": "color.primary.500"} 形式、色は 100% token 参照）を手書きする authoring source

守らせる仕組みも双方向:

• web 側 → 互換ゲート（npm run design:compat）: npm 公開版と HEAD の golden diff。token 削除・variant 削除・rule の意味変更を breaking 分類し、semver bump を機械強制する
• APP 側 → consumer テスト: melta-app の CI が「契約 subset・token 実在・contractVersion 同期」を照合。web 側が契約を壊すと APP のテストが赤くなる。実装と recipe の値一致（styleRefs conformance）は button で機構実証済み、他コンポーネントへ展開中

Quick Start

Claude Code

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

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

外部プロジェクトから使う（npm）

# contracts のみ（tokens / rules / component contracts の JSON）
npm install melta-contracts

# MCP サーバー（ビルド不要、npx 一発）
claude mcp add melta-ui -- npx -y melta-ds-mcp

import tokens from "melta-contracts/tokens" with { type: "json" };
import rules from "melta-contracts/rules" with { type: "json" };

MCP サーバー（このリポジトリを clone した場合）

.mcp.json 同梱のため、リポジトリ内では npm install だけで Claude Code に自動接続される。手動登録する場合:

npm install
claude mcp add melta-ui -- npx tsx src/index.ts

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:coverage        # 検証カバレッジ（経路別マトリクス）
npm run design:drift           # ドキュメント ↔ contracts の drift 検出
npm run design:compat          # 互換ゲート（npm 公開版 vs HEAD の破壊的変更 × semver 検査）
npm run design:recipes         # 契約 → recipes/web/ の Tailwind レシピ生成
npm run design:build           # contract → metadata/components.json 生成 + tsc
npm run design:update-showcase # showcase の数値を contracts から自動更新
npm test                       # Playwright + axe-core
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               # 99 禁止ルール registry
│   │   └── components/              # 40 contract（web 28 + app 先行 12）
│   ├── 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 — DS を読ませると DS 準拠スコアが何点上がるか

design/benchmarks/ は 3 条件で同一 prompt から UI を生成し、共通 lint core（check_html と同じ採点）で DS 準拠スコアを測るハーネス。「context engine を足すと精度が上がる」式の限界寄与（lift）を自前の一次データとして出す。

各セル（prompt × 条件）を N トライアル実行し、mean±range と条件間 lift を report.md に出力。design/benchmarks/history.json に時系列で追記する。

# 全 prompt × 4 条件 × 3 trials（ANTHROPIC_API_KEY が必要）
npm run benchmark

# トライアル数・prompt・条件を絞る
npm run benchmark -- --trials 5
npm run benchmark -- --prompt 1 --conditions cold,full

# メーター API を使わない採点経路: 生成済み HTML を採点（サブエージェント等で先に
# <dir>/<promptId>-<conditionId>-t<k>.html を用意 → 共通 lint core で採点 + history 追記）
npm run benchmark -- --score-dir design/benchmarks/results/<dir> --trials 3

# API 不要のパイプライン検証（mock provider。history には追記しない）
npm run benchmark -- --provider mock

provider-pluggable: ModelProvider インターフェースで anthropic（実装済み・MCP 6 tool を Claude API の tool use として渡す）/ mock（オフライン検証）/ openai（placeholder、未実装）を切替。full 条件では AI が何回どの tool を呼び、どの resource を参照したかを記録する — これが「AI-Ready DS が本当に効いているか」の研究目的の核。

red-team prompt は5本（neon / heavy shadow / color bar / placeholder-only form / icon-only buttons）。standard と red-team はスコアの意味が違う（前者=準拠生成、後者=悪い指示への抵抗）ため report で分離集計する。CI は live API を叩かず、tests/benchmark-pipeline.spec.ts が stats・採点の gaming 耐性・集約ロジックの回帰を守る。

測定しているもの / 限界（発信時の前提）:

• スコアは DS 準拠の proxy（lint core 違反 + class/属性ベースの準拠シグナル）であって、見た目の美しさそのものではない。準拠シグナルはコメント等への文字列埋め込みでは稼げない（実 class 属性のみ集計）。
• full 条件は生成後の check_html 自己検証（多ターン）を含むため、contracts→full の lift は「contracts 単体」ではなく「MCP workflow（自己修正込み）」の寄与。各層を分離するため designmd / contracts を別条件にしている。
• n は trial 数。headline には mean ± 95%CI を併記し、small-n の不確実性を隠さない。人手評価との相関検証は未実施（既知の限界）。

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

Google DESIGN.md spec との関係

melta の DESIGN.md（2026-04-10 導入）と Google Labs の design.md spec（2026-04-21 OSS 公開）は、独立に同名・同思想へ収斂した。melta の DESIGN.md は Google spec 互換の YAML front matter（tokens.json から自動生成）を含み、npx @google/design.md lint DESIGN.md が errors: 0 で通る。

守備範囲の違い: Google spec は「DESIGN.md ファイル自体の検証」まで、melta は「生成されたコードの検証・CI・hook」まで。詳細な対応表は design/compat/google-designmd.md。

License

MIT License — LICENSE

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

Acknowledgments

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