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 — 主張には検証経路をつける
配布物 — いま 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 で落ちる:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
