tsubotax/melta-ui

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/
    ├── tokens.json   ← 99 デザイントークン
    ├── rules.json    ← 99 禁止ルール（ID + severity + detector）
    └── components/   ← 33 contract（web 28 + app 先行 5。variant + size + a11y + rules）

Layer 3: 検証（破っても通さない）
  scripts/design/     ← validate / drift-check / lint-generated / build-legacy / update-showcase
  tests/              ← Playwright + axe-core
  .github/workflows/  ← CI で自動実行

| レイヤー | 形式 | 読み手 | 役割 | |---------|------|--------|------| | DESIGN.md | Markdown | AI（全エージェント） | デザイン憲法 + Quick Reference。これだけで基本 UI を生成可能 | | CLAUDE.md | Markdown | AI (Claude Code) | 作業手順・読み込みガイド・npm scripts | | contracts/ | JSON | AI + harness | 33 contract（web 28）+ 99 ルール + 99 トークンの厳密仕様 | | harness | TypeScript | CI | Schema 検証・drift 検出・Playwright + axe | | components/*.md | Markdown | 人間 | 設計意図・使い方・判断基準を自然言語で記述 | | docs/index.html | HTML | 人間 | 全コンポーネントのインタラクティブショーケース | | MCP サーバー | TypeScript | AI エージェント | トークン検索・コンポーネント取得・ルール検証をツールとして公開 |

---

AI にとっての読みやすさ

1. 段階的読み込み — コンテキストを浪費しない

| モード | 読むファイル | 用途 | |--------|------------|------| | クイック | DESIGN.md