DESIGN.md — コーディングエージェントにビジュアルアイデンティティを永続的に持たせるためのファイル形式。その構造・書き方・落とし穴を、実測にもとづいて日本語で解説します。
チームで DESIGN.md を書き、レビューし、共同開発できる状態を作ることを目的にしています。
対象バージョン: フォーマット
alpha/ CLI@google/design.mdv0.4.0本家: google-labs-code/design.md
---
name: Heritage
colors:
primary: "#1A1C1E"
tertiary: "#B8422E"
typography:
h1:
fontFamily: Public Sans
fontSize: 3rem
---
## Overview
Architectural Minimalism meets Journalistic Gravitas.
高級マット紙の質感 — 上質なブロードシートか、現代的なギャラリー。
## Colors
高コントラストのニュートラルと、単一のアクセントカラーに根ざしたパレット。
- **Primary (#1A1C1E):** 見出しと本文のための深いインク。
- **Tertiary (#B8422E):** "Boston Clay" — インタラクションを駆動する唯一の色。YAML frontmatter が機械可読なトークン、Markdown 本文が人間可読な根拠。 エージェントはこの1ファイルを読むだけで、セッションをまたいでも同じ視覚言語で UI を生成できます。
| # | ドキュメント | 内容 |
|---|---|---|
| 1 | DESIGN.md とは何か | 位置づけ。何を解決し、何ではないか |
| 2 | 構造リファレンス | スキーマ・セクション・型・{参照} 記法 |
| 3 | 2つの流派と選び方 | 実物74件の実測。どちらの型で書くか |
| 4 | 書き方ガイド | 良い DESIGN.md の条件。レビュー観点 |
| 5 | 落とし穴 | 仕様どおりに書くと壊れる箇所。実測済み |
| 6 | デザイナー不在の組織での運用 | CSS を書ける人がいない組織で、何が効いて何が効かないか |
| 7 | 実装が仕様を守っているか機械で判定する | 実験記録。決定的チェッカと LLM judge を並走させて測った |
はじめての人は 1 → 3 → 4 の順が早いです。2 と 5 は書きながら引く辞書として使ってください。
組織にデザイナーがいない場合は 6 を先に読んでください。 推奨する始め方が変わります（トークンを書かない「散文のみ」の型から入る）。
# テンプレートをコピー
cp templates/DESIGN.md ./DESIGN.md
# 検証
npx @google/design.md lint DESIGN.md
# Tailwind v4 のテーマとして出力
npx @google/design.md export --format css-tailwind DESIGN.md > theme.cssWindows では
.md拡張子がファイル関連付けと衝突するため、designmdエイリアスを使ってください。npx -p @google/design.md designmd lint DESIGN.md
一次資料の要約ではなく、実際に測って確かめたことを書いています。
- 実物74件の統計 — VoltAgent/awesome-design-md の実在する DESIGN.md（airbnb, apple, figma, nike, notion, spotify, tesla …）を機械的に測定。「2つの流派が存在する」「仕様外セクションが過半数に定着している」といった事実は、この測定から出ています。測定スクリプトは
tools/measure.pyに同梱しているので、誰でも再現できます。 - 実装との差分 — 仕様書どおりに書くと黙って値が消える箇所が実在します。全項目を CLI v0.4.0 で再現し、回避策を添えました。
docs/ 解説（上表）
templates/ 出発点にできる DESIGN.md
sandbox/ 実験環境（docs/07 の素材。3つの実装バリアントとスクショ）
tools/ 実測・判定スクリプト
measure.py … 実物74件の統計（docs/03 の再現）
shoot.mjs … スクリーンショット
probe.mjs … 決定的チェッカ（docs/07 の再現）
誤り・追記の指摘は Issue か Pull Request でお願いします。
事実の記述には出典を添えてください。 一次資料（docs/spec.md / PHILOSOPHY.md）の該当行、または再現できるコマンドのどちらかです。このガイドの価値は「測って確かめた」ことにあるので、そこは守りたいところです。
本ガイドの文章・図表・スクリプトは CC BY 4.0（クリエイティブ・コモンズ 表示 4.0 国際）で提供します。帰属表示さえあれば、翻訳・改変・商用利用を含めて自由に使えます。
引用部分の権利は各原典に帰属します。
DESIGN.md フォーマットおよび @google/design.md は Google LLC のプロジェクトであり、本リポジトリは非公式の解説資料です。Google LLC とは無関係で、同社による承認・後援を受けたものではありません。
フォーマットは alpha 段階のため、記述が実装に追いつかなくなる可能性があります。各ドキュメントの冒頭に検証時点のバージョンを明記しています。