グラレコ
はじめに 🎯
2026年4月21日、Google Labs が DESIGN.md というフォーマット仕様を GitHub に公開しました。リポジトリは google-labs-code/design.md、ライセンスは Apache-2.0 です。公開からしばらくして、スター数は1万5千を超えています（フォークも1.4kほど）。
DESIGN.md は、ひとことで言うと 「コーディングエージェントに視覚的アイデンティティ（ブランドの見た目）を伝えるためのフォーマット仕様」 です。AIエージェントに「うちのサービスっぽいUIを作って」と頼んだとき、毎回トーンがズレる——そんな経験をした人に向けた仕組み、と理解すると掴みやすいと思います。
もともとは Google の UI 生成ツール「Stitch」の中の機能でした。それをツールから切り離してオープンソース化し、どのコーディングエージェント・どのプラットフォームでも使える共通フォーマットにした のが今回の動きです。
この記事では、フロントエンドやデザインシステムに関わるエンジニアの方に向けて、DESIGN.md が何を解決するのか、ファイルの中身はどうなっているのか、どう使うのか を一通り解説します。
この記事でわかること:
- 🎨 DESIGN.md が解決する「AIエージェントとブランド一貫性」の課題
- 📄 ファイル構造（YAML front matter + Markdown body）の中身
- 🔢 design token の型と書き方
- 🔄 W3C 標準（DTCG）や Tailwind へのエクスポート
- 🛠️ CLI での lint / diff / export の使い方
なぜ DESIGN.md が必要なのか 🎨
最近、Claude Code や Cursor、Copilot のようなコーディングエージェントに、UIをまるごと作らせる場面が増えてきました。便利なのですが、ひとつ困ることがあります。
毎回、ブランドの見た目がズレるのです。
「プライマリカラーはこれ」「角丸はこのくらい」「見出しのフォントはこれ」——こういう決めごとを、エージェントは知りません。だから依頼のたびに微妙に違うトーンのUIが出てきて、結局手で直すことになります。指示プロンプトに毎回ベタ書きするのも限界があります。
DESIGN.md は、この「設計意図をエージェントが推測しなければならない」状態を解消します。Google 公式ブログの言葉を借りると、AIエージェントが 「意図を推測する代わりに、色の使途を正確に把握し、自分の選択を WCAG アクセシビリティルールに照らして検証できる」（原文: "Instead of guessing intent, AI agents can know exactly what a color is for, and can validate their choices against WCAG accessibility rules."）ようになる、というのが狙いです。
この図は、DESIGN.md の有無でエージェントの振る舞いがどう変わるかを示しています。読み取ってほしいのは、DESIGN.md が ブランドの「単一情報源（source of truth）」 として機能し、エージェントが推測する代わりに参照できるようになる、という点です。
ファイル構造 — 機械可読と人間可読のハイブリッド 📄
DESIGN.md の面白いところは、1つのファイルの中に「機械が読む部分」と「人間が読む部分」が同居している ことです。
-
YAML front matter（
---で囲む）: 機械可読の design token。色・余白・タイポグラフィなどの「正」の値。 -
Markdown body（
##セクション）: 人間可読の設計根拠。なぜこの色なのか、どう使うべきか、という「why」。
この図は、1ファイルが機械向け（YAML）と人間向け（Markdown）の2つの読み手に同時に応えている構造を表しています。ポイントは、トークンの値とその背景説明がバラバラのファイルに散らばらず、同じ場所にまとまっていることです。デザイントークンの管理でありがちな「JSONには値があるが、なぜその値なのかはどこにも書いていない」問題を避けられます。
YAML スキーマ
front matter で使える主なキーはこうなっています。
version: <string>
name: <string>
description: <string>
colors: {token-name: Color}
typography: {token-name: Typography}
rounded: {scale-level: Dimension}
spacing: {scale-level: Dimension}
components: {component-name: {property: string}}
colors は色、typography はフォント、rounded は角丸、spacing は余白、components はボタンなどの部品単位の指定です。
design token の書き方 🔢
トークンの値には、いくつかの型があります。
| 型 | 例 | 説明 |
|---|---|---|
| Color | "#1A1C1E" |
hex 形式の色 |
| Dimension |
48px / -0.02em
|
寸法（px や em） |
| Token Reference | {colors.primary} |
他のトークンを参照する |
特に便利なのが Token Reference です。{colors.primary} のように書くと、別のトークンの値を参照できます。色を一箇所変えれば、それを参照しているコンポーネントにも反映される、というデザイントークンらしい仕組みです。
実際のサンプル
GitHub に載っている「Heritage」というデザインシステムのサンプルを見てみます。
---
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
rounded:
sm: 4px
---
## Colors
The palette rooted in high-contrast neutrals...
- Primary (#1A1C1E): Deep ink for headlines
front matter で primary や h1 のフォントを定義し、--- の下の Markdown で「この色は見出し向けの深いインク」と説明を添えています。値と意図がワンセットになっているのがわかります。
コンポーネント単位の指定
ボタンのような部品は、components でまとめて定義できます。
button-primary:
backgroundColor: "{colors.tertiary}"
textColor: "{colors.on-tertiary}"
rounded: "{rounded.sm}"
ここで {colors.tertiary} のように Token Reference を使っている点に注目してください。ボタンの背景色を直接 hex で書かず、定義済みの色トークンを参照しています。こうしておくと、ブランドカラーを変えたときにボタンも自動で追従します。
W3C 標準への準拠とエクスポート 🔄
DESIGN.md がただの独自フォーマットで終わっていないのは、W3C の Design Token Format (DTCG) に準拠している からです。これによって、既存のデザイントークンのエコシステムと地続きになります。
CLI の export コマンドで、いくつかの形式に変換できます。
| 形式 | 変換先 |
|---|---|
json-tailwind |
Tailwind v3 の config |
css-tailwind |
Tailwind v4 の CSS 変数 |
dtcg |
W3C Design Tokens Format Module（tokens.json） |
# W3C DTCG 形式の tokens.json に変換
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
この図は、1つの DESIGN.md から複数のフォーマットへ書き出せることを示しています。読み取ってほしいのは、DESIGN.md を 「ブランド定義のハブ」 に据えれば、Tailwind プロジェクトにも W3C 標準のツールチェーンにも同じ定義を流し込める、という点です。ツールやプラットフォームに縛られない設計になっています。
CLI の使い方 🛠️
DESIGN.md は npm パッケージ @google/design.md として提供されていて、CLI で扱えます。
# インストール
npm install @google/design.md
# DESIGN.md の文法チェック
npx @google/design.md lint DESIGN.md
# 2つのバージョンの差分を見る
npx @google/design.md diff DESIGN.md DESIGN-v2.md
# W3C DTCG 形式にエクスポート
npx @google/design.md export --format dtcg DESIGN.md > tokens.json
出力はデフォルトで JSON です。これは エージェントが構造化されたフィードバックを処理しやすいように という設計で、人間が読むためというよりエージェントとの連携を意識した作りになっています。
lint でフォーマットの正しさを検証し、diff でブランド変更の差分を追い、export で各種ツールへ流す。デザインシステムを「コードと同じように」バージョン管理・CI に乗せられる、というのがこの CLI のねらいです。
Google Stitch との関係と、これから 🚀
冒頭で触れたとおり、DESIGN.md はもともと Google の UI 生成ツール Stitch の内部機能でした。
Stitch の中では、「一度作ったデザイン規則を、新しいプロジェクトを始めるときに再利用できる」という使い方をされていました。今回オープンソース化されたことで、この仕組みが Stitch から切り離され、任意のツール・任意のエージェントで使える汎用仕様 になりました。
現時点（取得時点）ではバージョンは alpha で、最新リリースは 0.2.0（2026年5月26日）です。まだ開発中の仕様ではあります。
一方で、Apache-2.0 という緩いライセンスで公開し、W3C 標準に準拠させている点からは、業界標準を狙っている 意図が読み取れます。複数のメディアも「industry standard を目指す動き」として報じています。AIエージェントによるUI生成がこれだけ一般的になってきた以上、「エージェントにブランドを伝える共通フォーマット」へのニーズは確かにあります。
⚠️ DESIGN.md は alpha 版（0.2.0）で、仕様はまだ変わり得ます。本番のデザインシステムに全面採用する前に、リポジトリで最新の仕様を確認することをおすすめします。
まとめ 🏁
DESIGN.md をまとめると、「AIエージェントにブランドの見た目を正しく伝えるための、機械可読＋人間可読のハイブリッドなフォーマット」 でした。
個人的にいちばん良いと感じたのは、「YAML で値、Markdown で意図」を1ファイルに同居させた設計 です。デザイントークンの管理では「値はあるが、なぜその値なのかが残らない」問題がずっと付きまといました。DESIGN.md はそこに正面から答えています。しかも W3C DTCG に準拠しているので、独自フォーマットにならず、既存のツールとつながげやすくなるかと思います。
まだ alpha 版なので、いきなり全面採用するのは慎重になったほうがいいです。ただ、AIエージェントでUIを作る機会が増えているなら、小さなプロジェクトで一度 DESIGN.md を書いてみて、エージェントの出力がどれだけブランドに寄るか を試す価値は十分あると思います。共通フォーマットが根づくかどうかは、結局こうして試す人がどれだけ増えるかにかかっています。