melta UI

melta UI

AI 向けデザインガイドラインを、違反を止める実行可能な契約へ。

🇬🇧 English: README.en.md · Showcase: https://melta.tsubotax.com （ドキュメント・契約の正本はこのリポジトリ）

AI にガイドラインを読ませることはできる。守るかどうかは AI 任せになる。melta UI は、その「任せ」を機械に置き換える。生成の前（MCP で契約を参照させる）・直後（lint / hook が違反を突き返す）・マージ前（CI が止める）・その後（drift 検査がドキュメントと実装の腐りを検知し続ける）の 4 点で機械が関与する。読ませるだけでなく、守らせる。

境界: melta UI は完成済みの CSS コンポーネント集ではない。配るのは値（tokens）・規則（rules）・仕様（contracts）・検証器（lint / MCP）で、import して貼れば動く UI ライブラリではない。web の実装は HTML + Tailwind クラスの参照実装として同梱している。

誰のためのものか

向いている

• AI コーディングエージェント（Claude Code / Cursor / Codex 等）で UI を生成・運用しているチーム
• 「ガイドラインは書いたのに守られない」を仕組みで潰したい個人・少人数チーム
• web と React Native で 1 つのデザイン契約を共有したいプロダクト

向いていない

• 完成済みの Web コンポーネント集（React コンポーネントを install してすぐ使いたい）が欲しい場合
• Tailwind / class ベース以外のスタイリング（CSS-in-JS の props 経由など）が主体で、スタイルがマークアップに現れない場合。静的 lint が効かない

Proof — 主張には検証経路をつける

• 107 禁止ルールのうち 49 / 107 を静的に自動検出。残りも「なぜ自動検出しないか」を automationStatus で分類・可視化する（rules.json / 内訳は制約と正直な範囲）
• Playwright + axe-core 372 tests が CI 必須ゲート（.github/workflows/design-check.yml / 実行履歴）
• 5 種の代表的リセット CSS 環境で VRT 差分ピクセル 0。pixelmatch の literal 比較で機械検証（tests/reset-vrt.spec.ts、npm run test:reset-vrt）
• npm 3 パッケージ + MCP Registry で配布（melta-contracts / melta-ds-mcp / melta-app、Registry ID io.github.tsubotax/melta-ui）
• 別リポジトリの React Native 実装が同じ契約を購読し、契約の破壊的変更は APP 側が契約バージョンを取り込んだ時点で consumer テストが検出する（melta-app / npm 公開版との互換は npm run design:compat が publish 前に検査）
• 外部プロジェクトで「AI が違反を書く → 即検出 → 自己修正」ループを実測（2026-08、非公開 RN アプリへ npm 経由で導入。melta-app README の成熟度・メンテナンス節）
• drift 検査自身に負のテストがある（わざと壊して発火することを固定：tests/drift-heal.spec.ts）

配布物 — いま install できるもの

パッケージ	役割	使い方
melta-contracts	契約データ（tokens / rules / component contracts / recipes の JSON）。ビルド不要・フレームワーク非依存	npm install melta-contracts
melta-ds-mcp	MCP サーバー + lint エンジン（このリポジトリ）。check_html は CI / hook と同一ロジック	npx -y melta-ds-mcp / melta-ds-mcp/lint
melta-app	React Native 実装。消費者プロジェクト向け eslint plugin を同梱	npm install melta-app

melta-ds-mcp 自体の bare import（import "melta-ds-mcp"）は非サポート。entry は import しただけで stdio サーバーが起動する CLI なので、npx melta-ds-mcp か subpath 経由で使う。entry 規約・deep import 互換・パッケージ分割の予定は docs/distribution.md。

自分のデザインシステムで検査したい場合（BYO-DS）: melta-ds-mcp は起動時に読み込むアセット root を自分の DS bundle へ切り替えられる（melta のルールとは混在しない）。4 ファイルの最小構成から始める手順と限界は docs/distribution.md の BYO-DS 節。

前提条件・互換性

項目	値
Node	22 以上（CI は 22 で検証）
MCP クライアント	stdio MCP に対応したもの（Claude Code で検証。Cursor は同梱の .cursor/mcp.json をプロジェクト設定として読む（有効化は Cursor 側の操作に従う）。Codex は同じ stdio コマンドで登録）
スタイリング	Tailwind CSS の class ベース前提。静的 lint は class 属性 / HTML 属性 / DOM 構造を読む
生成物の表示	プロトタイプは Tailwind CDN + DESIGN.md の tailwind.config、プロダクションは foundations/theme.md の v4 @theme
JSX / Vue	class 属性と HTML 属性の lint は効く。composition lint（ネスト構造・a11y DOM）は HTML のみ。JSX の変数経由 class・spread は静的には追えない
ライセンス	MIT

5 分クイックスタート

経路 A — npm（MCP サーバー、推奨）

clone せずに、契約参照と自己検証だけを既存プロジェクトへ足す経路。

claude mcp add melta-ui -- npx -y melta-ds-mcp
claude mcp list

成功判定 — claude mcp list にこの行が出る:

melta-ui: npx -y melta-ds-mcp - ✔ Connected

接続時に MCP instructions が渡るので、「melta は完成 CSS ライブラリではない」「先に melta://design-constitution を読む」「生成後は check_html で自己検証する」を利用側が毎回プロンプトに書く必要はない。あとは UI を指示するだけ:

ユーザー一覧のテーブルを作って

成功判定 — AI が生成 HTML を check_html に通し、この形の応答を得る（違反があれば修正して再検証する）:

{
  "passed": false,
  "errorCount": 2,
  "warnCount": 0,
  "violations": [
    { "ruleId": "AI_NO_CARD_COLOR_BAR_TOP", "severity": "error", "token": "border-t-4",
      "reason": "AI生成UIの典型パターン。装飾過剰で汎用性が低い",
      "alternative": "border border-slate-200 のみでカードを構成" },
    { "ruleId": "COLOR_NO_BLUE_BG", "severity": "error", "token": "bg-blue-500",
      "reason": "primaryで統一する", "alternative": "bg-primary-*" }
  ],
  "coverage": { "automated": "...", "notAutomated": "..." }
}

生成された HTML をブラウザで表示するには Tailwind と melta のトークン設定が要る。プロトタイプなら CDN でよい:

<script src="https://cdn.tailwindcss.com"></script>
<script>
  // DESIGN.md「Quick Reference → HTML テンプレート」の tailwind.config をそのまま貼る。
  // fontSize は 8 段すべて Tailwind デフォルトと異なる（本文 18px / 行間 2.0 が melta の核）。
</script>

経路 B — clone（フルハーネス）

hook / CI / lint CLI まで含めた強制層が要る場合。npm install した消費者にはこの 3 層は届かない（制約と正直な範囲）。

git clone https://github.com/tsubotax/melta-ui.git
cd melta-ui && npm install
printf '<div class="text-black shadow-2xl">x</div>' > /tmp/melta-bad.html
npm run design:lint-generated -- /tmp/melta-bad.html

npm install で有効になるもの: .mcp.json（Claude Code へ MCP 自動接続）/ .cursor/mcp.json（Cursor 向けに同じ MCP サーバーの設定を同梱。有効化は Cursor 側の操作に従う。作業指示は AGENTS.md を読ませ、.cursor/rules/melta-ui.mdc は所在ポインタだけを置く）/ .claude/settings.json の PostToolUse hook / lint CLI。

成功判定 1 — 違反ファイルに lint CLI をかけると exit 1 で落ちる:

  ✗ [error] COLOR_NO_TEXT_BLACK: "text-black" → text-slate-900（純黒はコントラストが強すぎて長時間の利用で目が疲れる）
  ✗ [error] SPACE_NO_SHADOW_2XL: "shadow-2xl" → shadow-sm 〜 shadow-md（オーバーレイ: shadow-xl）（影が強すぎてノイズになる）

1 ファイル走査 / error 2 / warn 0
❌ FAILED

成功判定 2 — Claude Code が .html / .tsx / .jsx / .vue を Write / Edit した直後、hook がこの JSON を返して修正ループに乗せる（warn のみなら additionalContext で助言注入）:

{"decision":"block","reason":"melta UI 禁止パターン検出（error 2 / warn 0）。書き込まれたファイルを修正してください: ..."}

仕組み — 契約・参照・検証・監視の 4 層

① 契約（SSOT）        design/contracts/
                        tokens.json      101 デザイントークン
                        rules.json       107 禁止ルール（ID + severity + detector + alternative）
                        components/      40 contract（web 28 / app 先行 12）
                        recipes/         プラットフォーム具象（web: 生成ミラー / app: RN styleRefs）
                      DESIGN.md / AGENTS.md   AI が最初に読む憲法と作業ガイド

② 参照（生成の前）     MCP サーバー（melta-ds-mcp）
                        必要な仕様・値・ルールだけをオンデマンドで渡す

③ 検証（生成の直後〜マージ前）
                      PostToolUse hook   Write/Edit 直後に lint → error は block で自動修正
                      lint CLI / CI      .github/workflows/design-check.yml
                      MCP check_html     CI と同一ロジックの自己検証

④ 監視（その後）       design:drift       ドキュメント ↔ contracts の腐りを検知
                      design:compat      npm 公開版との破壊的変更 × semver 検査
                      design:drift-heal  drift を検出して derived のみ再生成（SSOT は human gate）

MCP が公開するツール:

ツール	説明	入力例
get_token	トークン検索	{ "path": "color.primary.600" }
get_component	コンポーネント仕様取得（variants / sizes / stateSpecs / anatomy / a11y）	{ "id": "button" }
check_rule	クラス文字列の禁止パターン検査（34パターン自動検出）。文脈依存は conditional 付き	{ "classes": "text-black shadow-2xl" }
check_html	生成 HTML / JSX 全体を CI / hook と同一ロジックで lint	{ "source": "<div class=...>" }
get_rules	107 禁止ルール参照（manual 含む全件、filter 対応）	{ "category": "accessibility" }
search	全文検索（最大 20 件 + truncated 通知）	{ "query": "card" }

Resource は melta://design-constitution（DESIGN.md 全文）/ melta://tokens / melta://components / melta://components/{id} / melta://rules / melta://rules/auto-detectable。

web の実装対象は 28 コンポーネント + 13 ファウンデーション + 5 パターン。設計原則は Content First / WCAG 2.1 AA / Semantic Color / 3-Color Rule / 4px Grid / Minimal Elevation / No AI-ish Decoration の 7 つ（DESIGN.md）。

Web と APP — 1 つの契約が両方に降りる

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

契約は規範と具象の 2 層。規範（components/*.contract.json）は variant の語彙・states・tokenRefs・a11y で、全プラットフォーム共通。分岐が正当な箇所（hover→pressed、elevation の表現差、タッチターゲット 44pt 等）は platformSemantics で意味論だけを宣言する。具象（recipes/）は web が契約の Tailwind からの導出ミラー（鮮度を CI が担保）、app が RN の styleRefs（色は 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 のテストが赤くなる

melta-app は消費者プロジェクト向けの eslint plugin も npm で配っており、使う側のコードで生値の直書きが止まる。RN カタログの live showcase は https://app.melta.tsubotax.com。

限制与坦诚说明

49 / 107 的含义。不能声称“强制执行 107 条禁止规则”。可通过静态方式自动检测的有 49 条，其余规则通过 automationStatus 对验证路径进行分类并展示（盘点所有规则，确保不存在仅声明而未验证的规则）。

路径	数量	内容
静态自动验证	49 / 107	class 匹配 34（与 MCP check_rule 使用相同路径）+ html-attr 7 + composition 8（嵌套 + a11y DOM）
interaction test	3	tests/modal.spec.ts 在实际环境中验证 focus trap / Escape / focus 恢复
无法静态检测	3（其中 error 3）	impossible-static（active/selected/current 的判定取决于语义）
LLM 审查候选项	43（其中 error 31）	llm-judge-candidate（引入 shadow judge 前没有自动验证）
仅限人工审核	9（其中 error 9）	仅通过人工审核来保证。通过 get_rules 呈现给 AI
未分类	0（其中 error 0）	尚未完成盘点（未声明 automationStatus）

此表由 npm run design:coverage 根据 contracts 生成，并由 npm run design:drift 确保内容保持最新。数字会随着改进而变化。各规则状态的 SSOT 是 rules.json 中的 automationStatus。

其他限制：

• clone 路径与 npm 路径覆盖的层不同。PostToolUse hook 和 CI workflow 是面向“clone 此仓库并使用”的层，无法覆盖通过 npm install 安装的使用者。npm 路径的强制执行层有 3 个：melta-ds-mcp/lint（包含 composition；判定方式与 check_html / CI / hook 相同）、将其封装为 CLI 的 melta-lint，以及 MCP 的 check_html。需要在各项目中自行将其集成到 hook / CI
• 无法检查非 class 样式。如果样式未体现于标记（class / 属性）中的代码，静态 lint 将无法检测
• 尚不支持 JSX composition lint。嵌套结构和 a11y DOM 检查仅适用于 HTML。JSX 仅支持 class / 属性 lint
• BYO-DS 仅支持替换数据。以 JSON 编写自有 DS 的 token 和规则后，可使用相同引擎进行检查；但 component metadata 生成工具未随 npm 一同提供，detector 固定为 6 种（manual 表示不进行自动检查）。新增检查逻辑需要修改引擎
• check_html.passed 不代表已获批准。它表示草稿通过了 lint，不代表符合品牌要求；最终判断由人工做出

安全与数据边界

MCP 服务和 lint 引擎都在本地进程中运行。没有向外部发送生成代码、提示词或检查结果的途径，也不收集 telemetry。仅在通过 npx 获取软件包，以及 npm run design:compat / npm run check:pack / npm run check:registry 查询 npm registry 或 MCP Registry 中的公开版本时，才会访问网络。

成熟度与维护

• 由个人维护的 OSS（tsubotax）。没有 SLA，也没有专职团队。目前用于实际运行的 dogfood（web showcase / RN 应用）
• 0.x / 1.x 策略：契约软件包 melta-contracts 处于 0.x 阶段，可能通过 minor bump 引入破坏性更改。不过，破坏性更改由 npm run design:compat 进行机器判定，而非人工分类，并强制执行 semver bump
• 变更通知渠道为 CHANGELOG.md。每次发布都会记录 Added / Changed / Removed
• Bug 和功能请求请提交至 GitHub Issues。如要贡献代码，请参阅 CONTRIBUTING.md（本地 CI 镜像、生成文件的处理方式、PR 前检查清单）
• 漏洞请通过 SECURITY.md 中的非公开渠道（GitHub private vulnerability reporting）报告，不要提交到 issue。安全修复仅针对各软件包的最新 minor 版本提供

了解更多

文档	内容
DESIGN.md	设计规范 + Quick Reference。仅凭此文档即可生成基础 UI
AGENTS.md	AI Agent 通用工作指南（读取模式、按任务分类的指南、npm scripts）
design/authority.md	SSOT 声明和值冲突时的优先级
docs/melta-loop-playbook.md	loop / pipeline 自动化的治理原则（自动化 3 Level 分类、SSOT write-protect、Human Gate 的 Hard / Soft 两层划分、审计日志）。目前 W2 drift repair 已投入运行
docs/benchmarks.md	基准测试协议（通过 6 种条件 × N 次试验衡量 DS 合规分数的提升）及已知限制
docs/distribution.md	npm entry 规范、deep import 兼容性、BYO-DS（引入自有 DS）及软件包拆分计划
docs/ai-ready-ds-maturity-model.md	AI-Ready 成熟度模型（Lv0 None → Lv4 Verified）。可应用于任意项目
melta-screendiff	用实际截图比较 UI 变更 PR 的 Before/After 的 Claude Code plugin（独立仓库）。此仓库中的 .claude/screendiff.json 是其配置文件，仓库中也提供了常设演示 PR。它负责让人工审核 lint 无法检测的“视觉意图”
design/compat/google-designmd.md	与 Google Labs design.md spec 的对应表。melta 的 DESIGN.md 包含兼容 spec 的 front matter，npx @google/design.md lint 检查结果为 errors: 0。适用范围的区别是：“spec 仅验证 DESIGN.md 文件本身；melta 还会验证生成代码，并支持 CI 和 hook”

License

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

Acknowledgments: Charcoal Icons（pixiv Inc., Apache License 2.0）/ Lucide Icons（ISC License）/ Tailwind CSS