コーディングエージェントに「うちのデザインで作って」と頼んだとき、毎回トーンがズレた経験はありませんか。
セッションをまたぐたびにプライマリカラーが変わる。
フォントが違う。
ボタンの角丸がバラバラ。
これ、プロンプトの書き方が悪いわけじゃないんです。
デザイン仕様を 永続的に渡す場所 がそもそも存在しないことが問題で、設計の欠陥と呼んでいい話です。
2026年4月、Google Labs がその「置き場所」を作るためのフォーマット仕様を公開しました。
それが DESIGN.md です。
どういう問題を解くのかを整理しながら、今日から使える最小構成を具体的に示します。
エージェントへのデザイン指示が「毎回ブレる」のは、設計の問題だ
チャットで「色は #1a1a1a、フォントは Inter、角丸は 8px で…」と毎回書いている人、かなり多いと思います。
でもこの方法には根本的な欠陥があって、セッションが終わった瞬間にその情報は消えます。
次のセッションではゼロから書き直し。
チームメンバーが別のセッションで作業すれば、また違うトーンになる。
これはプロンプトの質の問題ではなく、「デザイン仕様をどこに置くか」という設計の問題です。
コードの意図は README.md に書けます。
エージェントの振る舞いや規約は CLAUDE.md に書けます。
でも ビジュアルアイデンティティを永続的に渡す場所 は、これまで存在しませんでした。
tokens.json を使っているプロジェクトもあるでしょう。
ただ tokens.json が渡せるのは「値」だけです。
「primary は #B8422E」という事実は伝わっても、「これは CTA ボタンやリンクに使うべき色だ」という 意図 は伝わりません。
エージェントは値を知っていても、それをどう使うべきかを判断できない。
DESIGN.md は、その「置き場所」を作るためのフォーマット仕様として、2026年4月に Google Labs がオープンソース化しました。
リポジトリは google-labs-code/design.md、ライセンスは Apache-2.0 です。
もともとは Google の UI 生成ツール「Stitch」の内部機能でしたが、ツールから切り離して、どのコーディングエージェントでも使える共通フォーマットとして公開されました。
二層構造：トークンと「なぜ」を1ファイルに同居させる
DESIGN.md の構造は「YAML フロントマター ＋ Markdown 本文」の二層構成です。
上の層が機械可読なトークン（具体値）、下の層が人間とエージェント双方が読む設計の意図（rationale）。
この組み合わせが tokens.json との決定的な違いです。
実際のファイルはこんな形になります。
---
colors:
primary: "#B8422E" # Boston Clay
on-primary: "#FFFFFF"
surface: "#F5F0EB" # Limestone
on-surface: "#1A1A1A"
error: "#BA1A1A"
typography:
heading:
family: "Public Sans"
weight: 700
size-scale: [32, 28, 24, 20]
body:
family: "Public Sans"
weight: 400
size: 16
spacing:
unit: "4px"
scale: [4, 8, 12, 16, 24, 32, 48, 64]
rounded:
sm: "4px"
md: "8px"
lg: "16px"
---
# デザインシステム
## ブランドの雰囲気
このプロダクトは「温かみのある信頼感」を軸にしています。
Limestone（#F5F0EB）のサーフェスが落ち着いた印象を作り、Boston Clay（#B8422E）が行動を促すアクセントとして機能します。
過度な装飾を避け、余白と階層で情報を整理するスタイルです。
## カラーパレット
Boston Clay（#B8422E）はインタラクションの唯一の駆動力として使います。
CTA ボタン・リンク・フォーカスリング・選択状態など、ユーザーのアクションを促す要素にのみ適用してください。
デコレーション目的での使用は避けること。
## タイポグラフィ
すべてのテキストに Public Sans を使います。
見出しは Bold（700）で視覚的な階層を作り、本文は Regular（400）で読みやすさを確保します。
フォントサイズは 4px グリッドに沿ったスケールを使い、任意の値は使わないでください。
エージェントはこのファイルを読むことで、「primary は #B8422E」という事実だけでなく、「これは CTA ボタンに使う色で、デコレーションには使わない」という意図まで理解できるようになります。
トークンと rationale が同じファイルに同居しているから、値と意図がズレることもない。
README.md・CLAUDE.md・DESIGN.md の役割分担
3つのファイルを並べると、それぞれの役割はかなりはっきりしています。
- README.md はプロジェクトの「何を・なぜ作ったか」を伝えます。セットアップ手順・アーキテクチャの概要・コントリビュート方法など、人間が最初に読むドキュメントです。
- CLAUDE.md はエージェントの「振る舞い・コーディング規約」を伝えます。コミットメッセージのルール・使ってはいけないライブラリ・テストの書き方など、エージェントが作業するときに守るべきルールを書く場所です。
- DESIGN.md はプロダクトの「ビジュアルアイデンティティ」を伝えます。色・タイポグラフィ・スペーシング・コンポーネントの方針など、UI を作るときの判断基準を書く場所です。
重複しやすいのは CLAUDE.md と DESIGN.md の境界線です。
「CLAUDE.md に色の指定を書いてしまう」パターンは実際によく見かけます。
たとえば CLAUDE.md に「ボタンの色は #B8422E を使うこと」と書くのは、本来 DESIGN.md に書くべき内容です。
CLAUDE.md はあくまで「エージェントの振る舞い」を規定するファイルで、デザイントークンの置き場所ではありません。
3つを「コンテキストの層」として捉えると整理しやすいです。
プロジェクトの目的（README.md）→ 作業ルール（CLAUDE.md）→ 見た目の基準（DESIGN.md）という順番で、それぞれが独立した関心事を持っています。
CLAUDE.md から DESIGN.md を参照させる場合は、ファイル内に以下のように書くだけです。
@DESIGN.md
これで Claude Code はセッション開始時に DESIGN.md を自動的に読み込みます。
Cursor や GitHub Copilot など他のエージェントも、プロジェクトルートに置いたファイルをコンテキストとして参照するため、特別な設定なしに機能します。
今日から使える最小構成を書く
「完璧なデザインシステムを書こう」と思うと、手が止まります。
最初は色・タイポグラフィ・コンポーネント方針の3セクションで十分です。
それだけでも、エージェントの出力は明らかに変わります。
Web 制作プロジェクト向けの最小構成はこんな形です。
---
colors:
primary: "#2563EB" # ブランドブルー：CTA・リンク・フォーカス専用
on-primary: "#FFFFFF"
surface: "#FFFFFF"
surface-variant: "#F8FAFC"
on-surface: "#0F172A"
on-surface-muted: "#64748B"
border: "#E2E8F0"
error: "#DC2626"
typography:
heading:
family: "Inter"
weight: 700
body:
family: "Inter"
weight: 400
size: 16
caption:
family: "Inter"
weight: 400
size: 12
spacing:
unit: "4px"
scale: [4, 8, 12, 16, 24, 32, 48, 64, 96]
rounded:
sm: "4px"
md: "8px"
lg: "12px"
full: "9999px"
---
# デザインシステム
## ブランドの方向性
クリーンで信頼感のある印象を基本とします。
余白を十分に取り、情報の階層を明確にすることで、ユーザーが迷わない UI を目指します。
アニメーションは控えめに。動きで注目を集めるより、構造で誘導するスタイルです。
## カラーパレット
ブランドブルー（#2563EB）はインタラクション専用です。
CTA ボタン・テキストリンク・フォーカスリング・アクティブ状態にのみ使います。
背景の装飾・アイコンの塗りつぶし・見出しの色付けには使わないでください。
muted テキスト（#64748B）はラベル・補足説明・プレースホルダーに使います。
本文テキストに使うと読みにくくなるため、主要なコンテンツには on-surface（#0F172A）を使ってください。
## タイポグラフィ
すべてのテキストに Inter を使います。
フォントサイズは 4px グリッドに沿ったスケールを使い、任意の値（例：15px・17px）は使わないでください。
行間は本文で 1.6、見出しで 1.2 を基準にします。
## コンポーネント方針
ボタンは primary・secondary・ghost の3種類のみ使います。
primary は primary カラーで塗りつぶし、ページ内で最も重要なアクション1つにだけ使います。
secondary は border カラーのアウトライン、ghost はテキストのみです。
カードは surface-variant の背景に border カラーのボーダー（1px）、rounded-md（8px）の角丸を基本とします。
シャドウは使わず、ボーダーで区切ることを優先します。
フォームの入力欄は border カラーのアウトライン・rounded-sm（4px）・フォーカス時に primary カラーのアウトライン（2px）を使います。
リポジトリルートに置いて、CLAUDE.md から参照するだけで動き始めます。
CLI リンターを使うと WCAG アクセシビリティの検証も自動で行えます。
npx @google/design.md lint
コントラスト比の問題や、アクセシビリティ上の懸念をエージェントが自分でチェックできるようになるので、レビューの手間が減ります。
コンポーネントを追加するたびに DESIGN.md を更新する習慣をつけておくと、ドキュメントとコードのズレが起きにくくなります。
新しいコンポーネントを実装したら、その方針をコンポーネント方針セクションに1〜2行追記する。
それだけで十分です。
「チャットの中」から「リポジトリの中」へ
DESIGN.md の本質は、エージェントへの指示を「チャットの中」から「リポジトリの中」へ移すという発想の転換にあります。
チャットに書いた指示はセッションとともに消えますが、リポジトリに書いた仕様はコードと同じようにバージョン管理され、チームで共有され、変更履歴が残ります。
デザイン仕様をコードと同じ扱いにする、という考え方です。
フォントを変えたらコミットする。
カラーパレットを更新したらレビューを通す。
それが当たり前になると、「なぜかこのブランチだけボタンの色が違う」みたいな問題が起きにくくなります。
現時点では DESIGN.md はバージョン alpha・最新リリースは v0.2.0（2026年5月時点）で、まだ開発中の仕様です。
ただ Apache-2.0 という緩いライセンスで公開し、W3C 標準への準拠を意識した設計になっていることから、業界標準を狙う動きとして複数のメディアが報じています。
公開後にスター数が急速に伸びたことも、この方向性への関心の高さを示しています。
仕様が alpha であることは、今すぐ試す理由にもなります。
フォーマットが固まる前に使い始めて、自分のプロジェクトに合った書き方を探しておくほうが、標準化されてから慌てて対応するより楽です。
「完璧な DESIGN.md」を目指すより、まず色とタイポグラフィだけ書いた薄いファイルをリポジトリに置いてみる。
そこから育てていく感覚で十分だと思います。
株式会社ホコサキは山口県宇部を拠点に、Web 制作・業務システム開発・AI 活用支援を行っています。
コーディングエージェントの実務導入や、デザインシステムの整備についてご相談があればお気軽にどうぞ。
詳しくは お問い合わせページ からご連絡ください。