DESIGN.mdの書き方
DESIGN.mdが機能する条件は、機械が推測しなくてよいことです。詳細より先に方向を示し、形容詞ではなく値を書き、実際に作るコンポーネントを扱います。機能する構造と、静かに壊す失敗を紹介します。
詳細ではなく方向から始める
最初に、スタイル名、初見の人へ説明する一文のエッセンス、ライトかダークかなど後のすべてを変えるフラグを示します。
多くの仕様はこれをファイル上部の小さな構造化ブロックに置きます。YAML frontmatterはGoogleの公開DESIGN.md仕様でも使われる慣例です。エージェントはこれを先に読み、後のセクションを解釈します。方向なしに50の色値から始めると、意図の推測を強いることになります。
形容詞ではなく値を書く
"Warm, minimal, editorial" means something different to every model on every run. "Background <hex>, ink <hex>, one accent <hex>, body type at <px> with a 1.5 line height, spacing on an <px> rhythm" means the same thing every time. Tokens are the contract; adjectives are decoration.
トークンは見た目ではなく役割で命名します。background、ink、accent、lineとし、「薄いグレー」「青」としません。役割名はテーマ変更に耐え、値の使い場所を伝えます。
文章にも仕事を与えます。値の理由と組み合わせ方を説明してください。「アクセントは1画面に1アクションだけ」は実行できますが、「配色は穏やか」は実行できません。
エージェントが作るコンポーネントを扱う
トークンだけではUIを決めきれません。同じ配色でも、ボタンが塗りか線か、角が直線か丸か、カードが影か細線か、強調がウェイト・サイズ・色のどれかで別のスタイルになります。
ボタン、カード、入力、ナビゲーションを短い宣言ルールで書き、適用範囲も加えます。エディトリアル向けだと分かれば、エージェントは高密度ダッシュボードに無理に使いません。
仕様を静かに壊す失敗
値のない形容詞。雰囲気の説明だけで数値がないと、エージェントは理解したように見えて独自の配色を作ります。
ブランドブックを全部入れること。DESIGN.mdは作業仕様であり資料庫ではありません。読む方が作るより長いと、エージェントは飛ばし読みし、自信を持って推測します。出力を変える内容だけ残します。
適用範囲がないこと。使うべきでない場所を示さない仕様は、どこにでも誤って適用されます。
放置すること。リポジトリのテキストなのでコードと同様に扱います。デザイン変更と同じコミットでDESIGN.mdも更新しないと、古いデザインを忠実に適用します。
内部参照の矛盾。文字セクションとコンポーネント例が違うスケールを示すと、エージェントが勝手にどちらかを選びます。
手書きを省き、既成のものを選ぶ
自社のデザインシステムならDESIGN.mdを書く価値があります。しかしBauhaus、Swiss International、ブランド品質の現代スタイルなど確立したものを求める場合、流派全体を自分で逆解析し、微妙に誤る可能性が高くなります。
そこでライブラリを使います。Curioは数百の実在スタイルを調査・構造化済みの完全なDESIGN.mdとして提供し、AIがMCP、共有リンク、ダウンロードから適用できます。スタイルを選べばファイルは完成しています。
FAQ
DESIGN.mdはどの程度の長さにすべきですか？
必要な視覚上の問いに答えられる範囲で短くします。通常は1〜2ページで、方向、主要トークン、頻出コンポーネント、適用範囲を含みます。AIの出力を変えないセクションは削除します。
プロジェクトのどこに置きますか？
README.mdの隣のプロジェクトルートです。コーディングエージェントが最初に見る場所で、命名慣例にも合います。明示的なパスやMCP取得に対応するツールもありますが、ルート配置が最も広く機能します。
1ファイルですか、複数ですか？
一つです。エージェントがシステム全体を一度で読むことが目的です。複数に分けると、見つけて整合させる推測を再び持ち込みます。
YAML frontmatterは必須ですか？
Googleの公開仕様が使い、機械が解析しやすいため良い既定値です。ただし本質は「方向を詳細より先に」です。構文にかかわらず、値を並べる前にスタイルを説明します。