ガイド：AIエージェントに守らせるデザインシステム・DESIGN.md
Claude Code / Codex / Cursor などに、毎回同じトンマナでUIを書かせるための「ルールの置き方」をまとめたガイドです。
1. 置き場所と読ませ方
- DESIGN.md（トークン＋ルール）を置き、AGENTS.md / CLAUDE.md から必ず読ませる DESIGN.md（トークン＋ルール）を置き、AGENTS.md / CLAUDE.md から必ず読ませる
- CLAUDE.mdには要点だけのリファレンスを置き、トークンはJSON、禁止パターン・用語集は別に定義する。成熟度チェックリストで次にやることを決める コーディングエージェント向けのデザインシステムは「要点を集めたリファレンス・トークンのJSON・禁止パターン・用語集」で組み、成熟度を段階でチェックする
- ルールが増えて守られなくなったら、常時は CLAUDE.md、条件付きは
.claude/rules/へ分ける 守らせたいルールは CLAUDE.md に全部書かず、条件付きは .claude/rules/ へ分ける - 単発のプロンプトなら冒頭にミニ・デザインシステムを書く LP生成プロンプトの冒頭に「ミニ・デザインシステム」を書く
2. 何を書くか
- 雰囲気の言葉より「値」を書き、ルールには「なぜ」を添え、使いながら育てる DESIGN.mdは「雰囲気の言葉」より「値」を書き、値には「なぜ」を添えて、使いながら育てる
- トークン名だけでなく「正しい使い方のコード例（ゴールデンセット）」を渡し、レジストリやMCPで配る トークン名ではなく「正しい使い方のコード例（ゴールデンセット）」をエージェントに渡す。レジストリ／MCPで配る
- 日本語UIなら和文フォント・行間1.7〜2.0・字間0.04〜0.1emを明記 日本語UIのDESIGN.mdには、和文フォント・行間1.7〜2.0・字間0.04〜0.1emを明記する
- 禁止するなら代わりのやり方とセットで書く AIっぽいデザインを避ける「禁止リスト」は、代わりの整え方とセットで指示する
- CSSの書き方の方針（100dvw、:focus-visible、:has() など）や余白の単位の考え方もルールに入れる モダンCSSのDos/Don'ts（100dvw、:focus-visible、:has()、@layer など）をAIへのルールにも入れる ／ 余白のトークンはremかpxの二択にしない。%・cqi・コンテナクエリも使い分ける ／ フォーム部品のブランド色は accent-color の1行で揃える ／ 見出しの「1文字だけ2行目」は text-wrap: balance で整える
3. どう作るか
- 好きなサイトのスクショから、選んだ要素だけを抜き出す 好きなサイトのスクショ3〜5枚をエージェントに分析させ、選んだ要素だけをDESIGN.mdにする
- 既存サイトや素材から、Skillsでデザインシステムをまるごと抽出させる 既存のサイトや素材から、Skillsを使ってデザインシステムを「抽出」させ、AI用のJSONにする
- ベースDSは組織向けローカルDSに落としてから使う ベースのデザインシステムは「そのまま使わず」、組織向けのローカルデザインシステムに落としてから使う
- エージェントにはスクショだけでなくキット（md・JSON・部品・検証）で渡す エージェントへの受け渡しはスクショではなく「読めるキット」（md・JSON・部品・検証）にする
- イメージが言葉にしにくいなら、既製のDESIGN.md集から選んで差し替える 「◯◯のサイトっぽく」と頼むより、イメージに近い既製のDESIGN.mdを選んで渡す
- awesome-design-md で選んだDESIGN.mdを、公式 shadcn スキルでデザインシステムページまで落とす awesome-design-md で見た目を選び、公式 shadcn スキルでデザインシステムページまで作る
- Claude Designのプロトは名札＋対応表でFigmaのDSコンポーネントへ組み直す Claude Designのプロトは「名札＋対応表」でデザインシステムどおりのFigmaにする
- 決めた経緯はDDR（Design Decision Record）として残し、AIに参照させる デザインの成果物だけでなく「なぜそう決めたか」をDDR（Design Decision Record）として記録し、AIに探索させる
4. 守られているかを確かめる
- Before/Afterのスクショで確認する デザインシステムをAIエージェントに読ませ、UI変更はBefore/Afterスクリーンショットでレビューする
- 見た目の差分を自動で検知する（VRT） Vitest 4のBrowser Mode＋GitHub Actionsで、見た目の変化を検知するテスト（VRT）を入れる
- 値の正本を
@themeに1か所にし、標準色を外して lint で任意値・直書き部品を止める。繰り返す指摘は lint へ上げる デザインハーネスを「作る・見直す・守る」で組む：値の正本を1か所にし、外れたらlintで止め、AI評価は合否に使わない - ルールファイル同士の矛盾や古い指示を
/doctor prompt-auditで点検する CLAUDE.md やデザインのルールファイルは、足すだけにせず /doctor prompt-audit で古い指示・存在しない参照・矛盾を点検する