design-md-convention

DESIGN.md — AI フレンドリーなデザインシステムの規約

VoltAgent/awesome-design-md（人気のデザインシステム 55 件以上、Google Stitch のコンセプト）に触発されています。

原則： プロジェクトのルートにある Markdown ファイル DESIGN.md を、UI を生成または変更する AI エージェントの信頼できる唯一の情報源として使用します。Figma も複雑な JSON も不要で、人間にも LLM にも読みやすいテキストだけを使います。

なぜ DESIGN.md なのか？

DESIGN.md がない場合の問題	DESIGN.md を使った解決策
AI がランダムな色を生成する	AI が定義済みのパレットを参照する
コンポーネント間でスペーシングに一貫性がない	AI が文書化されたスケールを適用する
タイポグラフィにばらつきがある	AI が定義済みのトークンを使用する
デザイナー／開発者のオンボーディングに時間がかかる	DESIGN.md が唯一の回答になる
あらゆる判断で Figma に依存する	コードと一緒にバージョン管理された Markdown

推奨される構成

DESIGN.md には必須セクションが 7 つあります。

1. ビジュアルの原則 — トーン、個性、Do／Don't
2. デザイントークン — 色、タイポグラフィ、スペーシング、角丸、シャドウ
3. グリッドとレイアウト — ブレークポイント、カラム、ガター、コンテナーの幅
4. コンポーネント — 一覧＋バリエーション＋使用ルール
5. インタラクションパターン — ホバー、フォーカス、アクティブ、無効、読み込み中
6. アクセシビリティ — 目標レベル（AA/AAA）、コントラスト、フォーカスリング
7. 参考資料 — Figma へのリンク（任意）、参考にしたデザインシステム

完全な構成については .claude/templates/DESIGN.md.template を参照してください。

作成ルール

1. 簡潔で構造化する

• 文章より表
• ハードコードされた値よりトークン
• 理論より具体例

2. 生の値ではなく、名前付きトークンを使う

❌ MAUVAIS
Primary button: background #3B82F6

✅ BON
| Token | Valeur | Usage |
|-------|--------|-------|
| `color.primary.500` | #3B82F6 | Boutons primaires, liens actifs |
| `color.primary.600` | #2563EB | Hover des éléments primaires |

3. Do／Don't を明示する

### Boutons

**DO**
- Utiliser `button.primary` pour l'action principale d'un écran (1 max)
- Utiliser `button.secondary` pour actions secondaires

**DON'T**
- Jamais 2 boutons primaires sur le même écran
- Jamais de couleur custom hors palette

4. コードと一緒にバージョン管理する

DESIGN.md はリポジトリ内に置き、コードと同様に PR でレビューします。

Claude Craft エージェントとの連携

以下のエージェントはデフォルトで DESIGN.md を読み込みます。

• @ui-designer — トークンに準拠した UI を生成する
• @ux-ergonome — インタラクションパターンを検証する
• @accessibility-expert — 目標レベルに対するコントラストを確認する
• @{react,vue,angular}-reviewer — ハードコードされた値を検出する

推奨ワークフロー

1. Nouveau projet → copier .claude/templates/DESIGN.md.template à la racine
2. Remplir les 7 sections (30-60 min)
3. Commiter DESIGN.md
4. Référencer depuis @.claude/CLAUDE.md projet : "@DESIGN.md"
5. Les agents IA le chargent automatiquement
6. Mettre à jour à chaque évolution du design system

生成支援

専用コマンド（フェーズ 4）：/uiux:generate-design-md

• tailwind.config.js または既存のトークンを分析する
• 各セクションの下書きを作成する
• 曖昧な箇所について確認を求める

参考になる DESIGN.md の例

• Stripe Dashboard
• Linear
• Vercel
• 全一覧：awesome-design-md

アンチパターン

アンチパターン	解決策
DESIGN.md が 500 行を超える	サブファイル docs/design/*.md に分割する
表のない文章	構造化されたトークン形式に整える
Do／Don't がない	明示的なルールを追加する
スクリーンショットのみ	テキストでの説明を追加する（LLM は画像を常に認識できるとは限りません）
コードとの不整合	CI チェック（トークンの lint）を追加する

---

最終更新日： 2026-04-15 バージョン： 1.0.0