AI 向けデザインガイドラインを、違反を止める実行可能な契約へ。 🇬🇧 English: README.en.md · Site: AI にガイドラインを読ませることはできる。守るかどうかは AI 任せになる。melta UI は、その「任せ」を機械に置き換える。生成の前(MCP で契約を参照させる)・直後(lint / hook が違反を突き返す)・マージ前(CI が止める)・その後(drift 検査がドキュメントと実装の腐りを検知し続ける)の 4 点で機械が関与する。読ませるだけでなく、守らせる。 境界:
$ npx -y skills add tsubotax/melta-ui --agent claude-code
Run the curl in your terminal, the rest in Claude Code.
Repo: tsubotax/melta-ui
What's inside
AI 向けデザインガイドラインを、違反を止める実行可能な契約へ。
🇬🇧 English: README.en.md · Site: 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 クラスの参照実装として同梱している。
向いている
向いていない
automationStatus で分類・可視化する(rules.json / 内訳は制約と正直な範囲)npm run test:reset-vrt)io.github.tsubotax/melta-ui)npm run design:compat が publish 前に検査)| パッケージ | 役割 | 使い方 |
|---|---|---|
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-core |
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。
| 項目 | 値 |
|---|---|
| Node | 22 以上(CI は 22 で検証) |
| MCP クライアント | stdio MCP に対応したもの(Claude Code で検証。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 |
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>
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 自動接続)/ .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)。書き込まれたファイルを修正してください: ..."}
① 契約(SSOT) design/contracts/
tokens.json 101 デザイントークン
rules.json 106 禁止ルール(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 | 106 禁止ルール参照(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)。
同じ契約パッケージ(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。
守らせる仕組みも双方向:
npm run design:compat): npm 公開版と HEAD の golden diff。token 削除・variant 削除・rule の意味変更を breaking 分類し、semver bump を機械強制するmelta-app は消費者プロジェクト向けの eslint plugin も npm で配っており、使う側のコードで生値の直書きが止まる。RN カタログの live showcase は https://app.melta.tsubotax.com。
48 / 106 の意味。「106 禁止ルールを強制する」とは言えない。静的に自動検出できるのは 48 件で、残りは検証経路を automationStatus で分類して可視化している(宣言だけのルールをゼロにするための棚卸し)。
| 経路 | 件数 | 内容 |
|---|---|---|
| 静的自動検証 | 48 / 106 | class マッチ 34(MCP check_rule 同経路)+ html-attr 7 + composition 7(ネスト + 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 導入までは自動検証なし) |
| human-only | 9(うち error 9) | 人間レビューでのみ守る。get_rules で AI に提示 |
| 未分類 | 0(うち error 0) | 棚卸し未了(automationStatus 未宣言) |
この表は npm run design:coverage が contracts から生成し、鮮度を npm run design:drift が守る。数字は改善のたびに動く。各ルールの状態の SSOT は rules.json の automationStatus。
その他の制約:
npm install した消費者には届かない。npm 経路の強制層は melta-ds-mcp/lint-core と MCP の check_html の 2 つで、これを各プロジェクトのフック / CI に自前で組み込むcheck_html.passed は完成承認ではない。lint-clean draft であってブランド適合の判定ではなく、最終判断は人間に渡すMCP サーバーも lint エンジンもローカルプロセスで完結する。生成コード・プロンプト・検査結果を外部へ送信する経路はなく、telemetry も持たない。ネットワークに出るのは npx によるパッケージ取得と、npm run design:compat / npm run check:pack が npm registry の公開バージョンを照会するときだけ。
melta-contracts は 0.x で、破壊的変更は minor bump で入りうる。ただし破壊的変更の分類は人手ではなく npm run design:compat の機械判定で、semver bump を強制する| ドキュメント | 内容 |
|---|---|
| DESIGN.md | デザイン憲法 + Quick Reference。これだけで基本 UI を生成できる |
| AGENTS.md | AI エージェント共通の作業ガイド(読み込みモード・タスク別ガイド・npm scripts) |
| design/authority.md | SSOT 宣言と値競合時の優先順位 |
| docs/melta-loop-playbook.md | loop / pipeline 自動化の統治原則(自動化 3 Level 分類・SSOT write-protect・Human Gate の Hard / Soft 2 層化・監査ログ)。現状 W2 drift repair が稼働 |
| docs/benchmarks.md | ベンチマークのプロトコル(5 条件 × N トライアルで DS 準拠スコアの lift を測る)と既知の限界 |
| docs/distribution.md | npm entry 規約・deep import 互換・vendor 経路・パッケージ分割の予定 |
| docs/ai-ready-ds-maturity-model.md | AI-Ready 成熟度モデル(Lv0 None → Lv4 Verified)。任意のプロジェクトに当てられる |
| 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 まで」 |
MIT License — LICENSE。同梱アイコンのライセンスは THIRD_PARTY_LICENSES.md を参照。
Acknowledgments: Charcoal Icons(pixiv Inc., Apache License 2.0)/ Lucide Icons(ISC License)/ Tailwind CSS
.claude/
screendiff.json
settings.json
.cursor/
rules/
color-system.mdc
components.mdc
melta-ui.mdc
.design-baseline.json
.github/
ISSUE_TEMPLATE/
bug_report.yml
config.yml
feature_request.yml
pull_request_template.md
workflows/
design-check.yml
.gitignore
.mcp.json
AGENTS.md
assets/
icons/
Add.svg
AddImage.svg
AddModel.svg
AddPeople.svg
AddRubi.svg
AddText.svg
Alart.svg
Announcement.svg
Ar.svg
Archive.svg
ArrowDown.svg
ArrowUp.svg
Artwork.svg
Back.svg
Binet.svg
Body.svg
BodyEdit.svg
Book.svg
BookmarkOff.svg
BookmarkOn.svg
BringBackward.svg
BringForward.svg
Calendar.svg
Camera.svg
CameraVideo.svg
Cart.svg
ChangeCharacter.svg
ChatBot.svg
Check.svg
ChromaticAberration.svg
Click.svg
Close.svg
Codes.svg
Collapse.svg
Collection.svg
Comment.svg
CommentFill.svg
CommentOff.svg
CommentOn.svg
CommentOutline.svg
Contest.svg
Contrast.svg
Copy.svg
Delete.svg
Description.svg
DeviceRotation.svg
Discovery.svg
Dot.svg
DotAlt.svg
Down.svg
DownloadAlt.svg
Duplicate.svg
Dust.svg
Edit.svg
Emoji.svg
Error.svg
ErrorOctagon.svg
Events.svg
Expand.svg
FaceEdit.svg
Fashion.svg
Feed.svg
File.svg
Filter.svg
Flare.svg
FormatAlignCenter.svg
FormatAlignJustified.svg
FormatAlignLeft.svg
FormatAlignRight.svg
FormatColorFill.svg
FormatColorFillNoColor.svg
FormatFontFamily.svg
FormatFontSize.svg
FormatLetterSpacing.svg
FormatLineSpacing.svg
Fov.svg
FrameEffect.svg
FrameSize.svg
Gift.svg
Glow.svg
Groups.svg
HairEdit.svg
Hashtag.svg
Hide.svg
HightlightText.svg
Home.svg
HorizontalWriting.svg
Hue.svg
Idea.svg
Image.svg
ImageAlt.svg
ImageHidden.svg
ImageReplace.svg
ImageResponse.svg
Images.svg
ImgContain.svg
ImgCover.svg
Index.svg
Info.svg
Invalid.svg
Invoice.svg
ItemRemove.svg
LatestWorks.svg
Like.svg
LikeOff.svg
LikeOn.svg
LikeOnPrivate.svg
Link.svg
List.svg
LockLock.svg
LockUnlock.svg
Login.svg
Logout.svg
lucide/
activity.svg
bar-chart-2.svg
clock.svg
cloud.svg
credit-card.svg
database.svg
folder.svg
globe.svg
key.svg
monitor.svg
phone.svg
server.svg
shield.svg
trending-down.svg
trending-up.svg
Manga.svg
Menu.svg
Message.svg
Microphone.svg
MobilePhone.svg
More.svg
Move1.svg
MultiSelect.svg
Next.svg
Nextworks.svg
NoImage.svg
Notification.svg
NotificationOff.svg
Novels.svg
NovelViewerSettings.svg
OpenInNew.svg
Options.svg
OptionsAlt.svg
Overlay.svg
Palette.svg
Pan.svg
Pause.svg
PauseAlt.svg
Pencil.svg
PencilAdd.svg
PencilDraw.svg
PencilLive.svg
PencilText.svg
Person.svg
Play.svg
Pose.svg
Prev.svg
Projects.svg
PullDown.svg
PullUp.svg
Question.svg
QuestionOutline.svg
Ranking.svg
ReadHorizontalLeft.svg
ReadHorizontalRight.svg
ReadVertical.svg
Redo.svg
Reload.svg
ReloadLoop.svg
Remove.svg
Reorder.svg
Reply.svg
Roll.svg
RollHorizontal.svg
RollVertical.svg
Rotate90DegreesC.svg
Rotate90DegreesCc.svg
RotateRight.svg
SansSerif.svg
Saturation.svg
Save.svg
Search.svg
Send.svg
Serif.svg
Services.svg
Set.svg
Settings.svg
ShareAndroid.svg
ShareIos.svg
Shopping.svg
Show.svg
ShowOutline.svg
Shutter.svg
Smile.svg
Speaker.svg
Star.svg
Subtract.svg
Sun.svg
Temperature.svg
Text.svg
Thread.svg
Trash.svg
TrashAlt.svg
Undo.svg
Up.svg
Upload.svg
UploadAlt.svg
Usagi.svg
UsagiAlt.svg
User.svg
Users.svg
VerticalWriting.svg
Video.svg
View.svg
ViewGrid2Columns.svg
ViewGrid3Columns.svg
ViewList.svg
Warning.svg
ZoomIn.svg
Meltan_favicon.svg
Meltan.svg
CHANGELOG.md
CLAUDE.md
components/
accordion.md
alert.md
avatar.md
badge.md
breadcrumb.md
button.md
card.md
checkbox.md
copy-button.md
datepicker.md
divider.md
dropdown.md
list.md
modal.md
pagination.md
progress.md
radio.md
select.md
sidebar.md
skeleton.md
stepper.md
table.md
tabs.md
tag.md
textfield.md
toast.md
toggle.md
tooltip.md
CONTRIBUTING.md
design/
DESIGN.md
audits/
2026-05-30_harness-redteam.md
authority.md
benchmarks/
history.json
prompts/
prompts.ts
standard.md
provenance.ts
providers/
anthropic.ts
mock.ts
openai.ts
rubrics/
evaluation.md
runner.ts
score.ts
stats.ts
compat/
google-designmd.md
contracts/
components/
accordion.contract.json
action-sheet.contract.json
alert.contract.json
avatar.contract.json
badge.contract.json
bottom-sheet.contract.json
breadcrumb.contract.json
button.contract.json
card.contract.json
checkbox.contract.json
copy-button.contract.json
datepicker.contract.json
divider.contract.json
dropdown.contract.json
empty-state.contract.json
header.contract.json
icon.contract.json
image.contract.json
list.contract.json
metric.contract.json
modal.contract.json
pagination.contract.json
progress.contract.json
radio.contract.json
row.contract.json
screen.contract.json
select.contract.json
sidebar.contract.json
skeleton.contract.json
stack.contract.json
stepper.contract.json
surface.contract.json
table.contract.json
tabs.contract.json
tag.contract.json
text.contract.json
textfield.contract.json
toast.contract.json
toggle.contract.json
tooltip.contract.json
LICENSE
package.json
README.md
recipes/
app/
action-sheet.recipe.json
alert.recipe.json
avatar.recipe.json
bottom-sheet.recipe.json
button.recipe.json
card.recipe.json
checkbox.recipe.json
empty-state.recipe.json
header.recipe.json
icon.recipe.json
image.recipe.json
metric.recipe.json
modal.recipe.json
progress.recipe.json
radio.recipe.json
row.recipe.json
screen.recipe.json
skeleton.recipe.json
stack.recipe.json
surface.recipe.json
tag.recipe.json
text.recipe.json
textfield.recipe.json
toast.recipe.json
toggle.recipe.json
web/
accordion.recipe.json
action-sheet.recipe.json
alert.recipe.json
avatar.recipe.json
badge.recipe.json
bottom-sheet.recipe.json
breadcrumb.recipe.json
button.recipe.json
card.recipe.json
checkbox.recipe.json
copy-button.recipe.json
datepicker.recipe.json
divider.recipe.json
dropdown.recipe.json
empty-state.recipe.json
header.recipe.json
icon.recipe.json
image.recipe.json
list.recipe.json
metric.recipe.json
modal.recipe.json
pagination.recipe.json
progress.recipe.json
radio.recipe.json
row.recipe.json
screen.recipe.json
... 206 moreFAQ
melta-ui is a Claude Code plugin with 2 hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. It includes ban-pattern, design-review. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.