DESIGN.md が OSS になって何ができるようになったか — Stitch のフォーマットがエコシステムへ広がる

はじめに

2026 年 4 月 21 日、Google Labs は Stitch で使われていた DESIGN.md のドラフト仕様と CLI ツールを Apache 2.0 ライセンスで OSS 化しました。

DESIGN.md は「AI コーディングエージェントに視覚的アイデンティティを伝えるためのフォーマット」です。これまでは Google Stitch という AI デザインツール内部で使われる独自フォーマットでしたが、OSS 化により Claude Code・Cursor・Copilot など他のエージェントや、自前のツールチェーンからも自由に扱えるようになりました。

この記事では、

• DESIGN.md がそもそも何を解決するためのフォーマットなのか
• OSS 化によって具体的に「できるようになったこと」
• CLI ツール（lint / diff / export）の使い方
• AI エージェント横断のデザインシステム運用への影響

を整理します。

DESIGN.md とは

DESIGN.md は、ブランドの視覚的アイデンティティを定義する自己完結型のプレーンテキスト形式です。1 つの Markdown ファイルが、

• YAML フロントマター — 機械可読なデザイントークン（色・タイポグラフィ・スペーシング・コンポーネント）
• Markdown 本文 — 人間が読める設計根拠（なぜその色を選んだのか、使ってはいけないケースなど）

の 2 層構造になっており、AI エージェントは前者を構造化データとして解釈し、後者を自然言語の文脈として参照します。

最小サンプル

---
version: alpha
name: Acme Brand
description: Acme 社のブランドアイデンティティ
colors:
  primary: "#1A1C1E"
  accent: "#FF6B35"
  neutral: "#F5F5F5"
typography:
  body:
    fontFamily: "Inter"
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 8px
spacing:
  xs: 4px
  base: 16px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.neutral}"
    rounded: "{rounded.md}"
    padding: 12px
---

## Overview

Acme は信頼性とプロフェッショナリズムを重視するブランドです。

## Colors

Primary は本文・主要 CTA に使用します。Accent は強調用で、画面あたり 1 〜 2 回までに留めてください。

{colors.primary} のような波括弧表記はトークン参照で、コンポーネント定義の中から色やスペーシングのトークンを再利用できます。これにより値の重複を避け、変更追跡が容易になります。

OSS 化されたもの

GitHub の google-labs-code/design.md リポジトリで、以下が公開されました。

仕様策定にあたっては W3C Design Token Format（DTCG） を参考にしており、既存のデザイントークン標準と互換性を保つ設計になっています。

OSS 化でできるようになったこと

OSS 化が「単に GitHub に置かれた」以上の意味を持つのは、これまで Stitch というクローズドな環境に閉じていたフォーマットが、仕様準拠さえすればどこでも読み書きできる共通言語になった点です。

1. AI コーディングエージェントを横断したデザインシステム共有

Stitch で生成・編集した DESIGN.md を、そのまま Claude Code・Cursor・Copilot などの AI コーディングエージェントに渡せるようになりました。プロジェクトのルートに DESIGN.md を置いておけば、エージェントが UI を生成する際にブランド規則を一貫して適用してくれます。

これまでは「Figma のデザインシステム → エージェント用のプロンプト」を都度人間が書き起こす必要がありましたが、DESIGN.md は単一ソースから複数エージェントへ配布できる構造になっています。

2. CI に組み込める検証 — lint

npx @google/design.md lint DESIGN.md

lint コマンドは以下を自動で検証します。

• 構造的正確性（必須フィールドの欠落、型の不一致）
• WCAG コントラスト比のチェック（前景色・背景色の組み合わせを自動判定）
• トークン参照の解決可能性（{colors.primary} が実在するか）

CI に組み込めば「アクセシビリティ違反のトークンが入った PR をマージできない」という運用が成立します。デザイナーがトークンを編集しても、機械的にガードレールが働きます。

3. 変更検出 — diff

npx @google/design.md diff before/DESIGN.md after/DESIGN.md

2 つの DESIGN.md ファイル間で、追加・削除・変更されたトークンを一覧表示します。「変更後のファイルが変更前より警告/エラーが増えた場合に exit code 1」 を返すため、回帰検出として CI に組み込めます。

トークン変更は影響範囲が広い（ボタンの色を変えるとアプリ全体が変わる）ため、変更レビュー時にこの diff があるとレビュアーの負担が大きく減ります。

4. 既存ツールチェーンへの橋渡し — export

DESIGN.md の最大の弱点は「新しいフォーマットを増やすこと自体がコスト」という点ですが、export コマンドが既存エコシステムへの変換口を提供します。

# Tailwind の theme 設定として書き出す
npx @google/design.md export --format tailwind DESIGN.md > tailwind.theme.json

# W3C DTCG 形式で書き出す（Style Dictionary などと連携可能）
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

DTCG 形式に出せれば、Style Dictionary を経由して iOS の Color.swift、Android の colors.xml、CSS 変数など任意の出力に変換できます。DESIGN.md を「マスター」として置き、各プラットフォーム用の生成物はビルド時に派生させる運用が現実的になりました。

5. コミュニティ拡張 — 日本語・CJK 対応など

OSS 化を受けて、すでに kzhrknt/awesome-design-md-jp のような日本語 UI 向けのコレクションが立ち上がっています。CJK フォントのフォールバックチェーンや、和文に特化した行間・約物処理などを Stitch 本体に依存せず追加できるのは、フォーマットが open であることの直接の恩恵です。

ブランド固有のセクション（例: トーン & ボイスのガイドライン、モーション原則）も Markdown 本文側に自由に追加できるため、チームごとの拡張が衝突しません。

6. プログラマブルな運用 — spec でスキーマを取得

npx @google/design.md spec --rules-only --format json

spec コマンドはフォーマット仕様自体を JSON で出力します。これを使えば、自前のツール（社内 CMS、レビュー Bot、エディタ拡張など）から DESIGN.md をファーストクラスのデータとして扱えるようになります。

たとえば「PR で colors.primary が変更されたら #design チャンネルに通知する」といったワークフローも、仕様が JSON で取れるからこそ宣言的に書けます。

実運用での導入パターン

OSS 化された DESIGN.md を実プロジェクトに組み込む場合、以下のような流れが現実的です。

1. 既存デザインシステムの抽出 — Stitch のスキルや手作業で、Figma / 既存 CSS から DESIGN.md を 1 ファイル生成する
2. リポジトリのルートに配置 — Claude Code や Cursor が自動で参照するように DESIGN.md をコミット
3. CI に lint / diff を追加 — npx @google/design.md lint を PR ワークフローに、diff をレビュー支援として導入
4. 派生物の自動生成 — export --format dtcg の結果を Style Dictionary に渡して、各プラットフォーム用の token ファイルを生成
5. コンポーネント実装時にエージェントに参照させる — 「DESIGN.md の button-primary トークンに従って実装して」とプロンプトで指示

2026 年 4 月時点で仕様は alpha 段階です。トークンスキーマは今後変更される可能性があるため、本番投入する場合はバージョン固定での運用をおすすめします。

DESIGN.md を profile に適用した具体例

DESIGN.md をデザインの説明だけで終わらせないためには、トークン、CSS、コンポーネントの対応を追えるようにします。ポートフォリオサイト profile では、Shibuya Express の色、文字、余白、コンポーネント規則をトークンとして定義し、画面の class 名に対応させています。

たとえば、背景面とアクセント面は次のように役割別の名前を持ちます。

:root {
  --color-surface-container-lowest: #ffffff;
  --color-surface-container-low: #f3f3f4;
  --color-primary-container: #ff8c00;
}

以下では、2026-09-06 に確認したトークンと実装の対応を例にします。

例 1: 記事カードのトークンを実装へつなぐ

article-card の規範は、白い surface-container-lowest、角丸なし、16px の padding です。一方、記事一覧の ArticleCard では、外側カードが通常背景を持たず親の背景の上に border を置き、16px の余白は内側の本文にあります。ホバー時だけ外側カードが surface-container-low 相当の面へ切り替わります。

これは規範と実装を 1 対 1 と見なせない具体例です。規範どおりの通常背景をカード自身に持たせるのか、親の背景を使う現状を規範へ反映するのかを、変更時に選ぶ必要があります。トークンがあるだけでは一致を保証しないため、この差分を明示してレビューできることが実装例としての価値になります。

実装には、コンテンツ固有の情報も置かれています。たとえば記事番号、サムネイルのフォールバック、日付、カテゴリ、矢印は ArticleCard が担当します。記事番号と視覚要素は、一覧の文脈に応じて省略できる設計です。DESIGN.md はすべての DOM 構造を決めるものではなく、繰り返し使う見た目の判断を共有するための契約です。

例 2: ページ全体の余白と罫線をそろえる

PageFrame は、1200px の内容幅を中央に置き、左右の縦破線と外側余白のドットグリッドを担当します。縦破線は md 未満では非表示になり、ドットグリッドは広い画面の外側余白だけに見える構成です。DESIGN.md にはこのページ罫線とドットグリッドの役割、1px と 2px の使い分けが書かれています。

この分担により、各ページで背景と縦罫線を個別に組み立てずに済みます。一方、ページ枠を共通化すると例外的なレイアウトも同じ制約を受けます。例外が必要なら、その場の任意値を増やす前に DESIGN.md の規則を更新するか、例外の理由をコンポーネントに残す判断が必要です。

例 3: Hero の強い対比を限定する

HeroProfile は、白いチケット面、濃い on-surface の右タブ、primary-container のオレンジを組み合わせています。DESIGN.md はオレンジの塗り面を CTA など強いブランド表示に限定し、太い 2px 枠をチケット構造に限る方針です。Hero はこの例外を意図的に使い、通常の本文やカードはより控えめな面と 1px の罫線を使います。

ここでのトレードオフは、印象的な要素を増やしすぎると本文の可読性や画面全体の階層が弱くなることです。トークンに名前と使用条件を置くと、色値だけを共有するより「どこで強く見せるか」もレビューできます。

検証方法と限界

2026-09-06 に npx @google/design.md lint DESIGN.md を実行し、errors 0、warnings 0 でした。これは DESIGN.md の構造とトークン参照を確認する記録です。

ただし、この lint の成功だけでは globals.css と DESIGN.md の値が常に一致すること、コンポーネントがすべての規則を守ること、画面が読みやすいことまでは証明しません。変更時は次の順で確認します。

1. DESIGN.md のトークンまたは使用条件を更新する。
2. globals.css の対応する CSS 変数・テーマ値を確認する。
3. 該当コンポーネントを確認し、必要なら表示をテストする。
4. npx @google/design.md lint DESIGN.md を実行し、コマンドと結果を残す。

このように、文章の規範、実装、検証記録を分けて残すと、仕様の説明だけでは見えにくい具体的な適用箇所と限界を読者が確認できます。

検証に使った資料

• google-labs-code/design.md

何が嬉しいのか — 一段引いて見ると

DESIGN.md の OSS 化は、AI エージェント時代のデザインシステム運用に対して 3 つの変化をもたらしました。

• ベンダーロックインの回避: Stitch だけで使える形式ではなく、どのエージェントにも食わせられるソースになった
• デザインのコード化が一段進んだ: 既存の DTCG はトークンのみだったが、DESIGN.md は「なぜその値か」という設計意図まで Markdown 本文に書ける
• AI と人間の両方が読める単一ソース: フロントマターは機械、本文は人間。ドキュメントとデータが分離せず同居する

特に 3 つ目は重要で、「デザイナーが書いたガイドライン PDF」と「実装で使われる JSON トークン」が乖離する従来の問題を構造的に解消します。AI エージェントが UI を生成する場面では、トークンだけでなく意図も必要だったため、この 2 層構造はちょうど噛み合います。

まとめ

• DESIGN.md は AI コーディングエージェント向けのデザインシステム記述フォーマット
• 2026 年 4 月に Google Labs が Apache 2.0 で OSS 化し、Stitch 専用ではなくなった
• CLI（lint / diff / export / spec）により、CI 統合・既存ツール連携・プログラマブル運用が可能に
• WCAG コントラスト自動チェック、Tailwind / DTCG への書き出し、コミュニティ拡張（日本語対応など）が実用段階
• 仕様は alpha のため、本番運用ではバージョン固定で

「デザインシステムを AI エージェントに伝えるための単一ソース」という発想は、Figma 中心のワークフローを置き換えるものではなく、コード生成エージェントとデザインシステムの間に挟まる新しいレイヤーとして定着していきそうです。

参考

• google-labs-code/design.md — GitHub
• DESIGN.md spec.md — GitHub
• Stitch's DESIGN.md format is now open-source — Google Blog
• Google's open-source DESIGN.md gives AI agents a prompt-ready blueprint — The Decoder
• awesome-design-md-jp — GitHub