AI 向け DESIGN.md は「値」ではなく「なぜ・いつ」を書き、守らせる部分は lint にする
色やフォントの値を並べただけの DESIGN.md では、AI は新しい場面で判断できず画面ごとにブレる（DESIGN.md なしで5画面作ったら見出しフォント4種・配色4種になった例）。各項目を「原則（Why）→ スケール（What）→ 使い分け（When）」で書き、守れなかったら困る値はコードから抜き出して hook で機械的に検査する。
どんな場面で使う？
- Claude Code／Claude Design でプロトタイプを量産していて、画面ごとに見た目がバラつく
- デザインガイドラインを、人と AI の両方が読める1か所にまとめたい
書き方（@saladdays さんの DESIGN.md ジェネレーターより）
- セクションを Why → What → When の順にする。 例: 色なら「なぜこの配色か」→ カラースケール → 色ごとの Do／Don't
- Creative North Star を比喩で1つ決め、「This means / This does NOT mean」を添える。 比喩だけだと AI は都合よく拡大解釈する
- 自由にしてよい領域も具体的に書く。
- ❌「ホバーエフェクトの演出は自由」
- ✅「ホバーエフェクトの演出。静かに確かな変化を。」
- 判断基準を数字や条件で書く。 例: 選択肢が3つ以下なら Radio／SegmentedControl、4〜7なら Select、8以上なら Combobox。通知は割り込みの重さで Toast／Inline Alert／Dialog を使い分ける
Claude Code ならプラグインで生成できる。参考サイトの URL を3つほど渡すと、DESIGN.md と W3C DTCG 形式の design-tokens.json が出る（再実行時は「更新か作り直しか」を聞いてくる）。
/plugin marketplace add saladdays/agent-skills
/plugin install design-md@saladdays-skills
/design-md:generate守らせ方（@sota_mikami さんの仕組みより）
- ガイドラインは MDX にして、人も AI も同じファイルを読む。 Storybook／React の実物コンポーネントを埋め込む
- SSoT を守る。 ガイドラインにしかない値を作らない。色やサイズはスクリプトでコードから抽出して載せる
- ルールは「ルール／理由／実装」の3点セットで書く
- NG パターンを JSON にして、Claude Code の hook で編集のたびに検査する。 例:
#000000直書き、グラデーション、10px の文字
足りないものを洗い出す・お手本を借りる
- 「何をどの順番で整えれば AI がデザインシステム通りに UI を書くか」を5段階で診断するチェックリスト（melta-ui の ds-health-check、@tsubotax さん）で、自分のリポジトリの成熟度を確かめる
- 非デザイナーは「○○っぽく」と頼むより、有名サービスを再現した DESIGN.md を渡す方が早い: getdesign.md、awesome-design-md、Claude Design 用68種の Awesome Claude Design
注意点
- 借りた DESIGN.md はあくまで出発点。そのまま使うと他社サービスそっくりになる
- 長い DESIGN.md は毎回コンテキストに乗る。lint で弾けるものは文章から外す（Claude Code: 「〜したら〜して」はルールではなく hooks（settings.json）に書く）
- トークン名だけでなく使用例を見せる方が効く場面もある: UI 生成は「トークン名」より「使用例」を見せる（golden set）。Claude Design との連携は Claude Design から Claude Code へ渡すときは「実際に動くアプリとして作って」と頼む、画像生成で作った LP を、素材の切り出し→Claude Design で再現→Claude Code で仕上げる