Repository navigation
Home
コーディングエージェントに、ビジュアルアイデンティティを持たせるための1ファイルです。
このページは趣旨と全体像を扱います。書き方の手順・スキーマ・ツールの使い方はリポジトリの docs にあります。
:::message
引用について: 本家の PHILOSOPHY.md は英語で書かれています。このページの日本語の引用は筆者による訳です。原文は本家リポジトリを参照してください。
:::
エージェントに UI を作らせると、毎回違うものが出てきます。
「モダンで、クリーンで、信頼感があって、プレミアムな感じで」と指示する。悪くないものが出てくる。翌日また頼む。また悪くないものが出てくる。でも昨日のものとは違う。
原因は指示の側にあります。「モダン」「クリーン」は領域を指す言葉で、点を指していません。モデルはその領域の真ん中あたりに何かを作ります。真ん中は毎回微妙にずれますし、そもそも真ん中は凡庸です。
DESIGN.md は、この「毎回ずれる」を止めるために、視覚的な意図を1つのファイルに固定して持ち回れるようにしたものです。人間が読めて、書き直せて、変更履歴が残ります。
┌─────────────────────────────────────┐
│ トークン（機械可読） │
│ 色・書体・余白・角丸の具体的な値 │
├─────────────────────────────────────┤
│ 散文（人間可読） │
│ なぜその値なのか / どこに使うのか │
│ そして、どこに使ってはいけないのか │
└─────────────────────────────────────┘
上だけなら、既存のデザイントークン形式で足ります。DESIGN.md の本体は下です。
トークンを扱うファイル形式なのに、本家のドキュメント（PHILOSOPHY.md）はこう言い切ります。
生成されたデザインの品質は、値の精度よりも、意図がどれだけ明確に記述されているかで決まる。
そして踏み込んで、
トークンの値はコンテキストであって、レンダリング指示ではない。 一般に、仕様の中でトークンの要件を定めることは受け入れないし、推奨もしない。
理由は「先行する言語やツールが積み上げた数十年の仕事を再発明しない」ため。
CSS も Tailwind も既にあります。DESIGN.md が引き受けるのは、それらが引き受けられなかった「なぜその値なのか」の方だ、という立て付けです。
→ 詳しくは 思想
あなたの意図が、あなたのいない場所で生き続けます。
これまで、デザインの意図は Figma のファイルと、口頭の説明と、レビューでの指摘に分散していました。実装する人が変われば伝わりません。エージェントが実装するなら、なおさら伝わりません。
DESIGN.md は、その意図をエージェントが毎回読み直す場所に置きます。
具体的に変わるのは、書くものの中身です。
| これまで書いていたもの | DESIGN.md で書くもの |
|---|---|
#B8422E |
この赤は唯一のアクセントで、図版の中だけに棲む。文字にもページ番号にも使わない |
| 角丸 4px | 建築的な鋭さ。モダンに見える最小限だけやわらげ、それ以上は丸めない |
| フォント指定 | この書体は制度的で信頼できる声を出すために選んでいる |
左は Figma でも表現できます。右は、これまでどこにも書く場所がありませんでした。
そして右こそが、書いていない場面でエージェントが判断を誤らないために必要なものです。
これが DESIGN.md の技術的な核心です。
「1970年代の、古い伝統ある大学の大学院講義ハンドアウト」は完結した世界を喚起する。一色のインク、たっぷりの余白、読みやすいサイズのセリフ、装飾の不在。その一文が、十数個の数値より多くの有用な情報を運ぶ。値の背後にある理由を運ぶからだ。
形容詞は領域を描き、具体的な参照は点を描く。
さらに強力な副作用があります。具体的な参照は、禁止事項を無料で運んできます。
モデルは講義ハンドアウトが何であるかを知っており、それが何でないかも知っている。グローもグラデーションも使わない。列挙する必要がない。犬と名指せば、犬が鳴かないことも伝わる。
「禁止リストが長くなってきた」と感じたら、それは参照が曖昧だったサインです。禁止を足すより、参照を具体化する方が早く解決します。
DESIGN.md は1ファイルですが、書く人は分かれていて構いません。
| セクション | 主に書く人 | 中身 |
|---|---|---|
| Overview | デザイナー（不在なら全員で合議） | 参照。ここが全体を決める |
| Colors / Typography / Shapes | デザイナー | 役割と、使ってはいけない場所 |
| Layout / Elevation | デザイナー | 密度と階層の考え方 |
| Components | デザイナー + エンジニア | 状態と、その意図 |
| Do's and Don'ts | 全員 | 運用で気づいた違和感を1行ずつ足す |
| Known Gaps | 全員 | まだ決めていない領域の宣言 |
Do's and Don'ts が全員なのは意図的です。 「良いものを作る」より「違和感を指摘する」方が、人間は得意で、しかも訓練を要しません。気づいた人がその場で1行足せる形にしておくと、資産が溜まります。
期待の輪郭をはっきりさせておきます。
- コンポーネントライブラリは作りません。 MUI や shadcn などは別途必要です
- Figma と同期しません。 Figma へ戻す経路は用意されていません
- 情報設計やインタラクション設計は対象外です
- 出来上がったものが良いかどうかは判定しません。 検証ツールは値の整合性を見るだけで、散文（＝本体）は読みません
最後の点は重要です。「検証を通った」ことは「良いデザインである」ことを意味しません。
この Wiki（趣旨と背景）
リポジトリ（実務）
- 構造リファレンス — スキーマ・型・セクション
- 書き方ガイド — 良い例・悪い例・レビュー観点
- 落とし穴 — 仕様どおりに書くと壊れる箇所
- デザイナー不在の組織での運用
- テンプレート — そのまま使える出発点
DESIGN.md フォーマットは Google LLC のプロジェクトです。本 Wiki は非公式の解説資料で、同社による承認・後援を受けたものではありません。フォーマットは alpha 段階です。