DESIGN.mdとは｜AIエージェントにデザインシステムを伝えるOSS仕様

Claude Code や Cursor、GitHub Copilot などの AI コーディングエージェントで UI コードを生成していると、ブランドから微妙にずれた色・フォント・角丸が返ってくる場面に遭遇したことがあるかもしれません。プロンプトで「この色を使って」「この角丸を守って」と毎回矯正するのは非効率で、チーム全体の生産性を下げます。

この課題に対して、既存のデザイントークン（tokens.json）だけでは「どの色をどこに使うか」の意図までは AI に伝わりません。値と目的の両方をひとつのファイルで受け渡す仕組みが求められていました。

そこで登場したのが、Google Labs の Stitch チームが 2026 年 4 月に OSS 化した DESIGN.md（google-labs-code/design.md）です。DESIGN.md は AI コーディングエージェントに視覚仕様を伝えるためのフォーマット規格で、YAML フロントマターで機械可読なトークンを、Markdown 本文で人間可読なラショナル（なぜその値なのか）を、同一ファイルに記述します。

本記事では、DESIGN.md の仕組みと構造、CLI ツール（lint / diff / export / spec）、tokens.json や AGENTS.md との棲み分け、そして仕様が alpha であることを踏まえた採用判断の目安までを、公式ドキュメントベースで解説します。読み終える頃には、「自プロジェクトに DESIGN.md を採用すべきか」を自チームで議論できる状態を目指します。

なお、本記事は動作検証を伴うハンズオンではなく、公式リポジトリ・公式仕様・Google 公式ブログを一次情報として整理したドキュメントベースの解説です。

DESIGN.mdとは何か

DESIGN.md は、AI コーディングエージェントに「視覚的アイデンティティ（ブランドとデザインシステム）」を持続的かつ構造化された形で伝えるためのフォーマット仕様です。公式リポジトリの説明は次の通りです。

A format specification for describing a visual identity to coding agents. DESIGN.md gives agents a persistent, structured understanding of a design system.

（出典: google-labs-code/design.md（GitHub リポジトリ））

開発元は Google Labs 内の Stitch チームで、2026 年 4 月に Apache-2.0 ライセンスで OSS 公開されました。もともとは Google の UI 生成ツール Stitch が内部で使っていたフォーマットで、コミュニティが利用できる形に整えて公開されたという経緯があります（出典: Google 公式ブログ「Stitch's DESIGN.md format is now open-source」）。

リポジトリ基本情報

執筆時点でのリポジトリ属性は次の通りです。

（出典: google-labs-code/design.md（GitHub リポジトリ）。数値は 2026 年 7 月時点）

OSS 化からわずか数ヶ月で 24,000 を超えるスターを獲得しており、AI コーディングエージェントとデザインシステムを繋ぐレイヤーへの関心の高さがうかがえます。archived / fork のフラグはいずれも false のため、本家として現在も活発にメンテナンスされているリポジトリです。

どんなエージェントで参照されるか

DESIGN.md はプロジェクトルート（またはサブディレクトリ）に DESIGN.md というファイル名で配置しておくことで、Claude Code / Cursor / GitHub Copilot / Google Stitch といった AI コーディングエージェントに「このプロジェクトの視覚仕様はこれ」と示す運用が想定されています。エージェント側が DESIGN.md を明示的にサポートするケースと、単に Markdown をコンテキストとして読み込む延長で利用するケースの両方があります。

DESIGN.mdが解決する課題

なぜ「新しいフォーマット」が必要なのかを、既存の代替と対比して整理します。

まず、AI コーディングエージェントに UI を生成させると、指示者が意図しない色・タイポグラフィ・角丸・余白が返ってくる問題があります。ブランドガイドラインが Notion や Figma に散在している場合、エージェントはその文脈を持たないため、汎用的な「それっぽい」UI を出力してしまいます。プロンプトで都度矯正するのはコストが高く、チーム内での再現性も失われます。

次に、デザイントークン（tokens.json 等）を導入していても、AI は「値」は取得できても「その値をどのコンポーネントの、どの状態に、どのような意図で使うか」までは自動では判断できません。トークンの一覧だけを渡しても、意図を伝えるプロンプトを別途書く必要があります。

DESIGN.md は次の 2 つを 1 ファイルで解決します。

• 機械可読な Design Token（値）を YAML フロントマターで定義する
• 人間可読なラショナル（なぜ・どう使うか）を Markdown 本文で書く

エージェントは同じファイルから値と意図の両方を読み取れるため、ブランドを保った UI 出力が期待できます。プロンプトを長くする代わりに、リポジトリ内に「一次情報」を置くという発想です。

DESIGN.mdの仕組みと構造

DESIGN.md は 2 層構造のファイルです。それぞれの役割を見ていきます。仕様の詳細は 公式 spec.md に定義されています。

YAML フロントマター（機械可読トークン）

ファイル冒頭に --- で囲んだ YAML ブロックを配置し、colors / typography / rounded / spacing / components などのデザイントークンを構造化して定義します。W3C の Design Tokens Format Module（DTCG）に着想を得たフォーマットで、{path.to.token} の形式でトークン間の参照が可能です（出典: google-labs-code/design.md（README）、W3C Design Tokens Format Module）。

たとえば colors.primary に基準色を定義し、components.button.background からその値を {colors.primary} として参照する、といった書き方ができます。参照が壊れている場合は後述の lint コマンドで検出できます。

Markdown 本文（人間可読ラショナル）

YAML の下に続く Markdown 本文には、「なぜその色を選んだのか」「どのコンポーネントでどう使うか」「やってはいけないこと（Do's and Don'ts）」など、値そのものからは読み取れない意図を自然言語で書きます。

この本文部分こそが、tokens.json のような「値だけ」の交換フォーマットと DESIGN.md を分ける最大の特徴です。AI エージェントは Markdown 本文を読み取ることで、「主要 CTA には primary を使い、破壊的操作には danger を使う」といった適用ルールまで理解できます。

セクションの規定順序とトークン参照

Markdown 本文には規定のセクション順序があり、Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts の並びが推奨されます（出典: google-labs-code/design.md（README の Linting Rules セクション））。この順序から外れると、後述する section-order の lint ルールで警告が出ます。

CLIツールの使い方と主要機能

DESIGN.md の使い方の中核となるのが、npm パッケージ @google/design.md として提供されている CLI ツールです。DESIGN.md は単なる Markdown 規約ではなく、CI パイプラインに組み込みやすい形で設計されており、4 つの主要サブコマンド（lint / diff / export / spec）が用意されています。Windows 環境向けにドット無しのエイリアス designmd も同梱されています（出典: google-labs-code/design.md（README））。

出力は原則 JSON で、lint / diff はエラーや回帰検出時に exit code 1、export は emitter エラー時に 1、入力読み取り失敗時は 2 を返します。CI での失敗判定に組み込みやすい設計です。

lint（構文検証・WCAG コントラストチェック）

lint は DESIGN.md の構造的正当性、トークン参照の解決可否、WCAG コントラスト比の充足を検証します。

npx @google/design.md lint DESIGN.md

（出典: google-labs-code/design.md（README のコマンドリファレンス））

適用される lint ルールは 9 種類で、代表的なものは以下です。

（出典: google-labs-code/design.md（README の Linting Rules））

WCAG コントラスト比の検証がビルトインされている点は、アクセシビリティを CI で担保したいチームにとって有用な要素です。

diff（バージョン差分の検出）

diff は 2 つの DESIGN.md 間の変更を追加・削除・変更・回帰の観点で検出します。

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

（出典: google-labs-code/design.md（README のコマンドリファレンス））

デザインシステムのバージョン更新時に「意図しない破壊的変更が混入していないか」を機械的にレビューできるため、Pull Request の CI で走らせておくと安全です。

export（Tailwind v3/v4 / W3C DTCG への変換）

export は DESIGN.md を他フォーマット（Tailwind v3 config JSON、Tailwind v4 の CSS @theme、W3C DTCG）に変換します。

npx @google/design.md export --format json-tailwind DESIGN.md

（出典: google-labs-code/design.md（README のコマンドリファレンス））

これにより、DESIGN.md をソース・オブ・トゥルースとしつつ、既存の Tailwind ベースのプロジェクトや Style Dictionary パイプラインへ値を受け渡すハイブリッド運用が可能になります。

spec（エージェントプロンプトへの仕様注入）

spec はフォーマット仕様そのものをテキスト出力するサブコマンドです。

npx @google/design.md spec --rules

（出典: google-labs-code/design.md（README のコマンドリファレンス））

エージェントが DESIGN.md を「単なる Markdown」ではなく「規約に沿った構造」として理解できるように、システムプロンプトやコンテキストに仕様を注入する用途で使います。DESIGN.md のことを知らないエージェントに対しても、spec の出力を先に読ませることで理解の土台を揃えられる想定です。

AIコーディングエージェントとの統合

DESIGN.md は特定のエージェントに縛られない可搬な仕様です。プロジェクトルートに DESIGN.md を配置しておけば、Claude Code や Cursor、GitHub Copilot は通常のファイルコンテキストとしてこれを読み取れます。Google 自身のプロダクトである Stitch では、DESIGN.md を第一級の入力として扱う統合が用意されています（出典: Google Stitch 公式ドキュメント「DESIGN.md Specification」）。

エージェントを使う側の運用としては、次の 2 パターンが考えられます。

• 暗黙参照: プロジェクトルートに DESIGN.md を置くだけで、リポジトリ内ファイルを読み込むエージェントには自然と参照される
• 明示注入: システムプロンプトや初回メッセージで「このプロジェクトの視覚仕様は DESIGN.md に従うこと」と指示する。必要に応じて npx @google/design.md spec --rules の出力もあわせて渡す

いずれの場合も、DESIGN.md の内容が更新されればエージェントの生成結果もそれに追従するため、「ブランドが変わったのにプロンプトの更新を忘れた」という運用事故を減らせます。

類似の仕様・ツールとの違い

DESIGN.md の採用を検討する際、既存の資産と役割が重複しないかは重要な論点です。代表的な 3 つと比較します。

tokens.json（W3C DTCG）との棲み分け

W3C の Design Tokens Community Group が策定する Design Tokens Format Module は、$value / $type / $description を持つ JSON でトークンを表現する共通交換フォーマットです。

DESIGN.md との差分は明確です。tokens.json は「値のみ」を扱う交換フォーマットであるのに対し、DESIGN.md は同じ値に加えて Markdown 本文で「なぜ／どう使うか」を同一ファイルに書きます。両者は対立するものではなく補完関係で、DESIGN.md の export --format dtcg 相当の出力によって W3C DTCG JSON へ変換できるため、既存の Style Dictionary パイプラインや Figma variables との橋渡しは可能です。

「Figma → tokens.json → 各プラットフォーム」というパイプラインを既に持っているチームは、DESIGN.md を その上流のソースとして置き、意図の記述を担わせるという構成が現実的です。

AGENTS.md との役割分担

AGENTS.md は AI コーディングエージェントの「振る舞い規範」を書くための Markdown ファイルです。プロジェクト前提、禁止事項、ロール、コーディング規約などを記述する用途で、視覚仕様や Design Token は扱いません。

DESIGN.md と AGENTS.md、そして SKILL.md（個別スキルを定義する仕様）は「AI へのインストラクションを 3 層に分割する」構図で整理されます。競合ではなく補完関係で、プロジェクトルートに 3 ファイルを併置する運用が広がりつつあります（出典: DEV Community「AGENTS.md, SKILL.md, DESIGN.md: How AI Instructions Split into Three Layers」）。

AGENTS.md は「何をしてよいか」、DESIGN.md は「どんな UI を出力すべきか」と役割が異なるため、両方を導入しても情報の二重管理にはなりにくい設計です。

Style Dictionary との組み合わせパターン

Style Dictionary は Amazon 発の OSS で、JSON/YAML で書かれたトークンを iOS / Android / CSS / Tailwind など複数プラットフォーム向けに変換する「トークン変換パイプライン」です。ソース定義フォーマットそのものではありません。

DESIGN.md はソース定義側、Style Dictionary は変換側と役割が分かれるため、次のような組み合わせが可能です。

• DESIGN.md → export で JSON 化 → Style Dictionary → 各プラットフォーム出力

Style Dictionary を既に運用しているチームが、その入力段だけを DESIGN.md に置き換えるパターンです。エンジニアリング側は Style Dictionary の生成物を使い続けつつ、意図・ラショナルの管理は DESIGN.md 側に寄せるという役割分担ができます。

メンテナンス状況と採用判断の目安

DESIGN.md の技術的な魅力を確認したうえで、「自プロジェクトに採用すべきか」を判断するための実運用側の観点をまとめます。

リポジトリの活動状況

先述の通り、公式リポジトリはスター数 24,755、フォーク数 1,921、直近 push が 2026-07-01（本記事執筆時点の 3 日前）と、活発にメンテナンスされている状態です。アーカイブされておらず（archived=false）、フォーク元でもない独立リポジトリ（fork=false）であることが確認できています（出典: google-labs-code/design.md（GitHub リポジトリ））。

Google Labs による公式リリースであり、Apache-2.0 という商用利用を含む幅広いユースケースを許容するライセンスが付与されている点も、企業採用の障壁を下げます。

仕様バージョン alpha のリスクと緩和策

一方で、記事執筆時点の仕様バージョンは README に明記されているとおり alpha です。今後のバージョンアップで YAML キー名やセクション順序、CLI インターフェースに非互換変更が入る可能性を織り込む必要があります。

現実的な緩和策としては次のような運用が考えられます。

• @google/design.md の CLI バージョンを CI で厳密ピン留めする（package.json の dependencies で ^ を使わず固定バージョンで記述する）
• DESIGN.md 自身をリポジトリ管理し、diff サブコマンドで差分レビューを PR に組み込む
• export の出力（Tailwind config や DTCG JSON）を成果物として保存し、DESIGN.md 側の破壊的変更が下流へ即座に波及しないバッファを設ける
• 導入初期は非クリティカルなプロジェクト（社内ツール・実験的な新規サービス等）から開始し、本番プロダクトへの本格展開は仕様が stable に近づいてから検討する

これらは特殊な運用ではなく、alpha 段階の OSS ライブラリを扱う際の一般的な流儀です。DESIGN.md 特有の巨大なリスクがあるわけではなく、「バージョンピン留めと差分レビューを徹底すれば十分実運用に載せられる」水準にあると言えます。

向いているケース／向いていないケース

現時点での採用適性を、シーン別に整理します。

向いているケース

• Claude Code / Cursor / Copilot / Stitch などの AI コーディングエージェントで UI コードを日常的に生成しており、ブランド逸脱の矯正コストが顕在化している
• デザインシステムはあるが、Figma やドキュメントに散在していて「エンジニア・AI からの一次参照先」が定まっていない
• Tailwind CSS を使っており、export --format json-tailwind の恩恵を直接受けられる
• 新規プロジェクトで、これからデザインシステムを立ち上げるためソースフォーマットを自由に選べる
• CI でアクセシビリティ（コントラスト比）を機械的に検証したい

向いていないケース／慎重に検討すべきケース

• Figma variables や既存の tokens.json パイプラインが安定稼働しており、AI エージェントを積極的には使っていない（追加導入コストに見合わない可能性がある）
• 破壊的変更のリスクを許容できない、超長期運用の SDK やライブラリ配布用途（alpha 仕様の追従コストがボトルネックになりうる）
• コンポーネント数が非常に多く、Markdown 本文で全ての適用ルールを書ききることが現実的でない大規模デザインシステム（この場合、DESIGN.md はブランド核だけに絞り、詳細は別ドキュメントに分ける運用が現実的）

判断のポイントは「AI エージェントが自チームの UI 開発フローにどれだけ深く入っているか」です。エージェント利用が中心なら DESIGN.md の投資回収は早く、そうでなければ tokens.json や Figma variables で十分な場合もあります。

まとめ

DESIGN.md は、AI コーディングエージェントに視覚仕様を伝えるための OSS フォーマットです。YAML フロントマターで機械可読なトークンを、Markdown 本文で人間可読なラショナルを一つのファイルに書くことで、値と意図の両方をエージェントに渡せる点が最大の特徴です。CLI（lint / diff / export / spec）は CI 組み込みを前提とした設計で、Tailwind や W3C DTCG との橋渡しも用意されています。

tokens.json / AGENTS.md / Style Dictionary とは競合ではなく補完関係にあり、既存のパイプラインと組み合わせて段階的に導入できます。仕様バージョンが alpha である点だけは注意が必要ですが、CLI バージョンのピン留めと diff を活用した差分レビューによって、実運用に耐える水準まで持ち込むことが可能です。

次のアクションとして、まずは公式リポジトリ（google-labs-code/design.md）と公式仕様（spec.md）、そして Google Stitch のドキュメントを参照し、自プロジェクトのブランドを DESIGN.md 形式で書き起こすことをおすすめします。書き起こす過程で、既存のデザインシステムの曖昧さがあぶり出されるという副次的な効果も得られるはずです。