DESIGN.mdとは｜AIが作るUIを「それっぽい」で終わらせない設計ファイル

DESIGN.mdとは、AIコーディングエージェントにデザインの判断基準を渡すためのファイル仕様です。色・書体・余白・角丸といった値を機械可読なトークンとして書き、その値がなぜその値なのかという設計意図を同じファイルの本文に書きます。Google Labsが2026年4月10日に公開し、Apache-2.0で運用されています。

AIにUIを作らせると、動くものは出てくるのに、どれも同じ顔つきになる。角丸のカード、紫のグラデーション、中央寄せのヒーロー。指示のたびに配色が変わり、前回と揃わない。原因はAIの能力ではなく、判断基準を渡していないことにあります。プロンプトに書いた「もう少し落ち着いた色で」は、その会話が終われば消えます。次のセッションのAIは、あなたが何を良しとしたのかを知りません。

この記事では、DESIGN.mdの中身と書き方を公式仕様に沿って整理し、そのうえで書いたファイルが本当に機能しているかを検証する手順まで踏み込みます。公式CLIを実際に動かした出力も載せました。仕様・CLI・カタログの価格はいずれも2026年9月10日時点のものです。

DESIGN.mdとは何か

DESIGN.mdは、デザインシステムを1枚のプレーンテキストで表現するための書式です。公式仕様の説明では「デザインセッションをまたいでも、異なるAIエージェントやツールの間でも、様式上の選択が引き継がれるようにするもの」と位置づけられています。人間とAIの両方が読めて、更新していける「生きた正本」という考え方です。

現在の状況を数字で押さえておきます。

スター数とフォーク数はGitHub APIで2026年9月10日に取得した値、CLIのバージョンはnpmレジストリで確認した値です。仕様バージョンがalphaである点は最初に押さえておいてください。公式リポジトリのStatus節に「仕様・トークンスキーマ・CLIはいずれも開発中で、書式は今後変わることを想定してほしい」と明記されています。

人が読むガイドラインとは目的が違う

従来のデザインガイドラインは、人が読んで判断するための資料でした。PDFやFigmaのページに、ロゴの余白規定やカラーコードが並んでいる形です。DESIGN.mdが違うのは、読み手がエージェントであることを前提に構造を決めている点です。値は決まった形式のトークンとして置き、意図は散文で置く。仕様はこの二層について「トークンが規範値であり、散文はそれをどう適用するかの文脈を与える」と役割を明確に分けています。

逆に言えば、デザインの意図を自分の言葉で説明できない段階では、このファイルは書けません。「なんとなく良い」を「なぜ良いのか」に変換する作業が先に必要です。その練習はデザインを言語化する練習帳｜“なぜ良いのか”を説明できる力を鍛えようで扱っています。

読めるツールに条件はほぼない

特別な連携やプラグインは要りません。実体はプロジェクトルートに置かれたMarkdownファイルなので、ルート直下のMarkdownを読み込む仕組みを持つツールであれば、そのまま参照できます。Claude Code、Cursor、Gemini CLI、Codex、Windsurf、Kiroなどが該当します。専用のAPIに依存しないことが、この書式が短期間で広まった理由の一つです。

なぜAIが作るUIは「それっぽい」で止まるのか

原因は3つに分けられます。どれもプロンプトの書き方では解決しません。

2つ目が実務では一番厄介です。カラーコードを渡しても、AIは「この色をどこに使うか」を知りません。primaryを渡せば、ボタンにも見出しにも背景にも使ってきます。仕様がOverview節を最初に置き、ブランドの人格や想定読者、UIが呼び起こすべき感情を書かせているのは、トークンが定義していない場面での判断材料を先に渡すためです。

1回のプロンプトで結果をどこまで動かせるかについてはAIとの協働コーディング入門｜プロンプトの書き方で結果が変わる理由で検証しています。DESIGN.mdはその上のレイヤー、つまり毎回書かなくても効き続ける前提を担当します。

中身は二層構造になっている

ファイルの構造は単純です。先頭にYAMLフロントマター（機械可読なトークン）を置き、その下にMarkdown本文（設計意図）を書きます。フロントマターは省略可能で、本文だけのDESIGN.mdも仕様上は成立します。

最小構成に近い例です。公式リポジトリのサンプルを短く整えたものです。

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

建築的なミニマリズムと、報道写真のような重み。マットな高級紙の
質感を狙う。

## Colors

高コントラストのニュートラルと、単一のアクセント色で構成する。

- **Primary (#1A1C1E):** 見出しと本文に使う深いインク色
- **Secondary (#6C7278):** 罫線・キャプション・メタ情報に使う
- **Tertiary (#B8422E):** インタラクションの唯一の担い手
- **Neutral (#F7F5F2):** 純白より柔らかい下地

注目してほしいのは、本文側で色に説明的な呼び名と用途が与えられている点です。トークン側はtertiaryという機械的な名前ですが、本文では「インタラクションの唯一の担い手」と役割が書かれています。この一文があるかどうかで、AIが2つ目のボタンに何色を使うかが変わります。

トークンの設計はW3CのDesign Tokens Formatを参照しており、tokens.json・Figmaの変数・Tailwindのテーマ設定と相互変換できる形に寄せられています。既存のデザイントークンがある環境なら、ゼロから作り直す話にはなりません。

セクションは8つ、順番も決まっている

本文のセクションは##見出しで書きます。関係ないセクションは省略してよいのですが、置くなら仕様の順番に従うという制約があります。順番を崩すとリンターが警告を出します。

Elevation & Depthの扱いが親切です。影を使わないフラットな設計でも「この節は不要」ではなく、階層を何で表しているか（罫線か、色のコントラストか、面の重ね方か）を書くことが求められます。書かなければAIは影を足してきます。

省略するセクションがあるなら、フロントマターのomittedで宣言できます。理由も添えられるので、「書き忘れ」と「意図した省略」を区別できます。

omitted:
  - spacing
  - section: rounded
    reason: "ブランドブックに角丸の規定がないため"

逆に、同じ見出しが2回出てくるとエラーになりファイルごと拒否されます。仕様は未知の内容にはおおむね寛容で、知らないセクション見出しや知らないトークン名は「保持する・エラーにしない」と定めていますが、見出しの重複だけは明確に不可とされています。コピー＆ペーストでColors節を2つ作ってしまう事故が一番起きやすいところです。

トークンで詰まりやすい3点

参照は波括弧、指す先は原則プリミティブ値

他のトークンを指すときは{colors.primary}のように波括弧で囲みます。ほとんどのトークン群では、参照先は単一の値でなければなりません。{colors}のようにグループを指すのは不可です。例外はcomponents節で、ここだけは{typography.label-md}のような複合値への参照が許されています。

components:
  button-primary:
    backgroundColor: "{colors.primary-60}"
    textColor: "{colors.primary-20}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.primary-70}"

hoverやactiveのような状態は、button-primary-hoverのように関連する別キーとして並べるのが仕様の想定です。入れ子にはしません。エージェント側が全バリアントを見て判断します。

単位はpx・em・remの3つだけ

寸法を表すDimension型で使える単位はpx・em・remに限られます。vwや%、chは入りません。流体的なサイズ指定を普段から使っている場合、その考え方はトークンではなくLayout節の散文側に書くことになります。

色は逆に広く、16進数・名前付きの色・rgb()・hsl()・oklch()・color-mix()まで有効なCSS色文字列であれば通ります。ただしコントラスト検査のために内部でsRGBへ変換されるため、推奨は#RRGGBBの16進数です。行間だけは例外的に、単位なしの数値（1.6）も書けます。

綴りを間違えたキーは黙って無視される

これが一番気づきにくい罠です。トップレベルのキーをcoloursと書いてしまっても、YAMLとしては正しいのでパースは通ります。しかし仕様が知っているキーではないため、エクスポート時には黙って捨てられます。値は書いてあるのに効かない、という状態になります。

後述する公式CLIには、この綴り間違いを名指しで指摘するルールが2つ入っています。手で見つける前提にしないでください。

CLAUDE.md・AGENTS.md・SKILL.mdとの役割分担

AIに渡す定義ファイルは増え続けています。混ざりやすいので、どのファイルが何を担当するかだけ地図として置いておきます。書き方の詳細はそれぞれの記事に譲ります。

境界を一言でいうと、DESIGN.mdは「判断基準」、SKILL.mdは「手順」です。「ボタンは角丸8pxにする」はDESIGN.md、「デプロイ前にこの3コマンドを流す」はSKILL.mdです。この2つを混ぜると、どちらのファイルも読みにくくなります。

ルールファイルを何層に分け、どこに何を置くかという設計の話はClaude Codeのルール・エージェント設計術｜CLAUDE.mdとサブエージェント運用の実践知にまとめてあります。DESIGN.mdはそこで言う「参照読み込みされるルールファイル」の層に入ります。各ファイルのフロントマターや置き場所の構文はClaude Code上級編｜MCP・Hooks・Skills・サブエージェント実践ガイド、いつどれを選ぶかの判断はClaude Codeのスキル・ループ・ワークフローの使い分け｜いつどれを使うか判断ガイドが扱っています。

どこに置けばエージェントが読むか

基本はプロジェクトルート直下にDESIGN.mdという名前で置くだけです。ファイル名が仕様名そのものなので、エージェント側が探しに来ます。

確実に読ませたい場合は、プロジェクトの指示書から明示的に参照します。読み込みの優先順位を自分で決められるので、こちらを勧めます。

## デザイン規約

UIを作る前に @DESIGN.md を読み、色・書体・余白・角丸は
そこで定義されたトークンだけを使う。
定義がない場面では Overview の方針から判断する。

複数のアプリを1つのリポジトリに入れている場合は、ルートに共通のDESIGN.md、各アプリ配下に個別のDESIGN.mdという構成が取れます。ただし「どちらが勝つか」はツールが自動で決めてくれません。優先順位は次の節で決めます。

なお、既存のデザイン資産がFigmaにある場合は、ファイルを書き起こす前にFigma側から変数やスタイル定義を直接渡す経路もあります。そちらはFigmaとClaude Codeを連携する方法｜Dev Mode MCPでデザインをコード化するワークフローで扱っています。DESIGN.mdはFigmaを使わない、あるいはFigmaに正本がないプロジェクトで効きます。

自作するか、公開カタログから借りるか

ゼロから書く以外に、公開されているDESIGN.mdを出発点にする方法があります。代表的なのがgetdesign.mdです。VoltAgentのチームが運営していて、550件以上のサイトを分析したDESIGN.mdをカタログとして公開しています。GitHubにはawesome-design-mdという収集リポジトリもあります。

ここで必ず押さえておくべき前提があります。カタログに並んでいるファイルは、その企業が公式に配布しているデザインシステムではありません。AIコーディング向けに作られた参考実装であり、実際のブランドカラーや書体と厳密には一致しません。「有名企業のデザインシステムがそのまま手に入る」と理解して案件に持ち込むと、値の出どころとブランドの扱いの両方で、説明が難しくなります。

そのうえで、使い分けの基準はこう置けます。

getdesign.mdは有料の商品も持っています。2026年9月10日時点の掲載価格は、Premium DESIGN.mdファイルが39ドルの買い切り、Webサイト用スターターキットとモバイルアプリ用スターターキットがそれぞれ249ドルの買い切り、カタログ全体にアクセスできるCatalog Passが月額99ドルです。カタログの閲覧自体は無料でできるので、まず数本読んでOverview節の書き方を掴むのが費用のかからない使い方です。

どのテーマがどう見えるかを先に確かめたい場合は、DESIGN.mdプレビューを用意しました。公式リポジトリのファイル8本と、日本語書体を指定した自作テーマ6本を切り替えて、簡易なランディングページで配色・書体・余白・角丸の違いを見比べられます。選んだテーマをAIに渡すためのプロンプトもそのままコピーできます。

実運用の型は「共通テンプレ→案件ファイル」の2階建て

複数の案件やプロダクトを並行して持っている場合、案件ごとにDESIGN.mdを白紙から書くのは続きません。運用として回るのは、共通のテンプレートを1つ持ち、案件直下のDESIGN.mdがそれを上書きする2階建ての形です。

1. 共通テンプレートを作る。セクションの見出しだけ8つ並べ、どの案件でも変わらない項目（最小フォントサイズ、コントラストの下限など）を埋めておく
2. 案件開始時にコピーする。案件直下にDESIGN.mdとして置き、Overview節から書き始める。色やコンポーネントは後でよい
3. 優先順位を明文化する。「案件直下のDESIGN.mdがある場合はそれが最終決定」と指示書側に1行書く。書かないとAIが両方を混ぜる
4. 更新のきっかけを決める。デザインの相談が発生したとき、決まった内容をその場でファイルに戻す。会話で決めて終わりにしない

3番目が抜けると事故になります。テンプレートに「アクセントは1色だけ」と書いてあり、案件側で「アクセント2色」に変えたとき、優先順位が宣言されていないとAIは折衷案を出してきます。どのファイルが勝つかは、人間が先に決めて書いておく必要があります。

4番目は地味ですが、このファイルが資産になるかどうかを決めます。DESIGN.mdの価値は「一度書いたこと」ではなく「決定が全部そこに集まっていること」にあります。デザイン工程をどこまでAIに任せるかという役割分担の話はAI社員の職種一覧｜1人会社が実際に配属できる仕事とその境界で整理しています。

書いたあとの検証 — 公式CLIで確かめる

DESIGN.mdを書いて終わりにすると、効いているかどうかが分かりません。公式にリンターが用意されているので、ファイルを保存したら必ず1回通します。インストールは不要です。

npx @google/design.md lint DESIGN.md

出力はJSONです。エラーが1件でもあれば終了コード1、なければ0を返すので、そのままCIやコミット前のフックに載せられます。

実際に走らせた結果

わざと粗のあるDESIGN.mdを用意して、CLI 0.4.0で検査しました。仕込んだ問題は「{rounded.lg}という存在しないトークンへの参照」「coloursという綴り間違い」「ColorsをOverviewより前に置いた順番違反」「どのコンポーネントからも参照していない色を2つ定義」です。

{
  "findings": [
    {
      "severity": "error",
      "path": "components.button-primary",
      "message": "Reference {rounded.lg} does not resolve to any defined token.",
      "rule": "broken-ref"
    },
    {
      "severity": "warning",
      "path": "colors.neutral",
      "message": "'neutral' is defined but never referenced by any component.",
      "rule": "orphaned-tokens"
    },
    {
      "severity": "warning",
      "message": "Section 'Colors' appears before 'Overview', which is out of order.",
      "rule": "section-order"
    },
    {
      "severity": "warning",
      "path": "colours",
      "message": "Unknown key \"colours\" — did you mean \"colors\"?",
      "rule": "unknown-key"
    }
  ],
  "summary": { "errors": 1, "warnings": 5, "infos": 2 }
}

仕込んだ4種すべてが検出され、終了コードは1でした。上の抜粋は見やすさのために一部を省いていますが、実際の出力は警告5件・情報2件を含みます。coloursについては「知らないキーだが値がトークンらしいので、エクスポート時に黙って無視される」という警告も別に出ました。綴り間違いを人の目で見つける必要はありません。

コントラスト比は自動で測られる

粗を直した版で走らせたところ、残ったのは1件だけでした。

{
  "severity": "warning",
  "path": "components.chip-accent",
  "message": "textColor (#9aa5b1) on backgroundColor (#f7f5f2) has contrast ratio 2.30:1, below WCAG AA minimum of 4.5:1.",
  "rule": "contrast-ratio"
}

コンポーネントに背景色と文字色の組み合わせを書いておくと、WCAG AAの4.5:1を下回った時点で比率つきで指摘されます。これはDESIGN.mdを書く実利として大きい部分です。デザインの決定を書き留めるだけでなく、その決定がアクセシビリティ上成立するかを機械が見てくれます。

リンターは全部で11のルールを持っています。severityは固定です。

更新して壊れていないかはdiffで見る

DESIGN.mdは更新されていくファイルなので、変更で悪化していないかを見る手段が要ります。diffサブコマンドが担当します。

npx @google/design.md diff DESIGN.md DESIGN-v2.md

先ほどの2つのファイルで実行すると、追加されたspacingの2トークン、追加されたコンポーネント、変更されたコンポーネントがそれぞれ名前で列挙されました。エラーと警告の増減も出ます。今回はerrorsが-1、warningsが-4で、regression: false、終了コードは0でした。警告が増える方向の変更を入れたときだけ終了コード1になるので、レビューの機械的な足切りに使えます。

Tailwindのテーマとして書き出せる

トークンは他の形式に変換して出力できます。Tailwind v4向けのCSSを書き出した実際の結果です。

@theme {
  --color-primary: #4a6fa5;
  --color-neutral: #f7f5f2;
  --color-accent: #b8422e;
  --font-body-md: "Public Sans";
  --text-body-md: 16px;
  --font-weight-body-md: 400;
  --radius-md: 8px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}

Tailwind v3のJSON設定、W3C準拠のtokens.jsonも同じexportから出せます。ここで1つ実測で気づいた点があります。元のファイルにはlineHeight: 1.6を書いていたのに、書き出されたCSSに行間の変数は含まれていませんでした（0.4.0で確認）。単位なしの数値で書いた行間がそのまま渡らない可能性があるので、エクスポートを実装の正本にするなら出力を目で確認してから使ってください。

ここまでがファイル側の検証です。次の一手は、出てきたUIそのものの検品になります。リンターはDESIGN.mdが仕様として正しいかを見ますが、そのトークンを使ったUIに優先順位があるかは見ません。色を抜き、ぼかし、強弱だけを残しても情報の順番が伝わるか、という検品手順を構造→視覚→文字を守れたかを検品する｜色・ぼかし・強弱の3テストにまとめてあります。lintが通ったら、そのままこの3テストへ進んでください。

よくある失敗

最後の項目は軽視しないでください。仕様バージョンはalphaで、CLIも0.4.0です。今書いたファイルが半年後にそのまま通る保証はありません。チームで使うならCLIのバージョンをpackage.jsonで固定し、上げるときにlintを流して差分を確認する運用にしておくと安全です。

よくある質問

Q. DESIGN.mdはGoogleの公式仕様ですか？

Google Labsが公開しているオープン仕様で、ライセンスはApache-2.0です。ただしGoogle全社の標準規格や、Web標準として策定されたものではありません。仕様バージョンはalphaで、今後変わることが公式に明記されています。

Q. CLAUDE.mdに全部書くのではだめですか？

動きますが、2つの理由で分ける方が有利です。1つは公式CLIによる検査が使えること。コントラスト比の警告や壊れた参照の検出は、指示書の中に散文で書いた色には効きません。もう1つは、DESIGN.mdが他のツールでも読める共通形式であることです。エージェントを乗り換えても資産が残ります。

Q. 既存のデザイントークンがある場合はどうしますか？

作り直す必要はありません。DESIGN.mdのトークンはW3CのDesign Tokens Formatを参照して設計されており、tokens.json・Figmaの変数・Tailwindのテーマ設定と相互に変換できる形になっています。既存の値を写し、足りないのは散文側の設計意図だけというケースが多いです。

Q. 1人開発でも書く意味はありますか？

あります。むしろ1人の方が効きます。デザインの決定を頭の中だけに置いていると、AIに毎回説明し直すことになり、説明が微妙に変わるたびに出力もぶれます。ファイルに置けば、来週の自分と来週のAIが同じ基準を読みます。

Q. どのセクションから書き始めるのが早いですか？

Overviewだけ書いて一度AIに投げてみるのが早いです。色や数値がなくても、狙う雰囲気と想定読者が書かれていれば出力の方向は変わります。そこで出てきたものを見ながら「この色は違う」と直していくと、Colors節の中身が具体的に決まっていきます。

Q. getdesign.mdのカタログをそのまま案件に使えますか？

参考実装として読むのは有用ですが、そのまま持ち込むのは避けてください。カタログのファイルは各企業が公式に配布しているデザインシステムではなく、実際のブランドカラーや書体と厳密には一致しません。既存ブランドがある案件では、正本はクライアントの規定側にあります。

Q. lintをCIに入れるとき、警告も落とすべきですか？

最初はエラーだけを落とす設定で十分です。lintはエラーがある場合のみ終了コード1を返すため、そのまま入れればエラーだけの足切りになります。警告も管理したい段階に来たら、diffを使って「前より警告が増えたら落とす」形にする方が現実的です。

まとめ

• DESIGN.mdは、AIにデザインの判断基準を渡すためのファイル仕様。Google Labsが2026年4月に公開し、ライセンスはApache-2.0、仕様バージョンはalpha
• 構造は二層。YAMLフロントマターのトークンが規範値で、Markdown本文の散文がその適用文脈を与える
• セクションは8つで、置くなら仕様の順番に従う。見出しの重複だけはエラーでファイルごと拒否される
• トークンの綴り間違いは黙って無視される。手で探さずnpx @google/design.md lintに見つけさせる
• コンポーネントに背景色と文字色を書くと、WCAG AA未満のコントラストが比率つきで警告される
• 複数案件で回すなら、共通テンプレートと案件ファイルの2階建てにし、どちらが勝つかを先に明文化する
• 公開カタログのファイルは各企業の公式デザインシステムではない。参考実装として読む

まずはOverview節だけのDESIGN.mdをルートに置き、lintを1回通してみてください。設計意図を書き出す作業そのものが、自分のデザイン判断の棚卸しになります。

自社プロダクトや案件でデザインシステムの整備から相談したい場合は、制作側で受けています。

関連記事

• Claude Codeのルール・エージェント設計術｜CLAUDE.mdとサブエージェント運用の実践知
• Claude Code上級編｜MCP・Hooks・Skills・サブエージェント実践ガイド
• Claude Codeのスキル・ループ・ワークフローの使い分け｜いつどれを使うか判断ガイド
• FigmaとClaude Codeを連携する方法｜Dev Mode MCPでデザインをコード化するワークフロー
• 構造→視覚→文字を守れたかを検品する｜色・ぼかし・強弱の3テスト