DESIGN.md を試す — Google Labs が定めた “エージェント用デザイン仕様書” を AIGP に導入

Google Labs が 2026-04-21 に DESIGN.md のドラフト仕様をオープンソース化しました（リポジトリは google-labs-code/design.md）。3 月に AI デザインツール Stitch で導入された形式を、Stitch 外でも使える一般仕様として切り出したもの。

一言で言えば 「エージェントのための、デザインシステムの設計意図メモ」。YAML フロントマターに機械可読トークン、Markdown 本文にその なぜ を書き込み、Claude Code や Cursor がセッションを跨いで参照できるようにします。

この記事は、先週 UI UX Pro Max を AIGP に導入した記録 の続編。UUPM が「選択肢を広げる」スキルなら、DESIGN.md は「選んだ結果を固定する」置き場です。

DESIGN.md が解く問題

デザイン判断がプロジェクト内で散らばる状況は、AI コーディング支援ツールを使っていると特に顕著になります。AIGP の例を棚卸しするとこうでした:

• components.json に shadcn 設定（base-nova, neutral）
• src/app/globals.css に Tailwind v4 のブランド色（--color-aigp-pink #FF8CC3 ほか）
• memory/project_aigp_next.md（Claude の自動メモリ）にサイドバー順序と breakpoint
• src/app/admin/analytics/page.tsx にチャート色のハードコード #10b981 / #c7d2fe
• Slack / 議事録 / 頭の中に「なぜ純白 #fff を避けるのか」

次セッションで Claude Code が起動すると、この全部を再発見する必要があります。毎回探して、毎回「AIGP のブランド色は何？」と聞かれ、毎回答える。DESIGN.md は 1 枚読めば済む 状態を作るためのフォーマットです。

フォーマットの 2 層構造

DESIGN.md は上半分が機械、下半分が人間 (+AI) の領域です。

1. YAML フロントマター — 機械可読トークン

オプションで書けるトークン定義。仕様上は以下のグループが標準化されています:

• colors — 色トークン（hex、sRGB、# 必須）
• typography — フォント族・サイズ・ウェイト・行高・字間
• rounded — 角丸スケール（none / sm / md / lg / xl / full）
• spacing — 余白スケール
• components — ボタン・カードなど UI 原子の組み合わせルール

トークン参照は {colors.primary} のように書けます。値は Dimension（px / em / rem）もしくは hex。

2. Markdown 本文 — 設計意図と制約

仕様書が推奨するセクション順は以下:

1. Overview — ブランド人格、情緒的な意図 2. Colors — パレットとセマンティック役割 3. Typography — フォント戦略 4. Layout — グリッドとリズム 5. Elevation & Depth — 影 or コントラストの方針 6. Shapes — 角丸の哲学 7. Components — UI 原子のスタイリング指針 8. Do’s and Don’ts — 実務的なガードレール

重要なのは Do’s / Don’ts。「サーフェスに純白 #fff を使わない」「見出しは全て大文字」のような 肯定的・否定的な制約 を言語化する場所です。これが AI エージェントの持続的コンテキストメモリとして働きます。

4 つの CLI コマンド

@google/design.md パッケージで 4 つのサブコマンドが使えます（まだ alpha）。

コマンド	用途
lint	壊れたトークン参照、コントラスト比不足、見出し順序違反を検出
diff	2 つの DESIGN.md を比較。PR レビュー時のトークン単位差分検知に
export	Tailwind theme config または DTCG（W3C Design Tokens CG）JSON に変換
spec	仕様本体と lint ルール一覧を標準出力。AI に読ませる材料

Windows の注意: npx @google/design.md ... は .md が拡張子として解釈される問題があります。ローカルインストール後に node ./node_modules/@google/design.md/dist/index.js spec で叩く必要があります。仕様書にもこの注意書きが入っています。

UUPM との関係

先週 AIGP に入れた UI UX Pro Max は、デザインの選択肢を広げる「広辞苑」的なスキル。DESIGN.md はそこで選んだ結果を固定する「社内規定書」です。

運用としてはこう回ります:

1. 新しいコンポーネントやページ設計のとき、UUPM で候補を広辞苑的に検索 2. 採用した色・タイポ・ルールを DESIGN.md に追記し、Why: を Do’s/Don’ts に書き残す 3. 次セッションの Claude Code は DESIGN.md を先に読む ので、同じ問いを繰り返さない 4. 未決な領域に遭遇したら再び UUPM を参照

UUPM は毎回推論を走らせ直すので、結論を固定する先が必要でした。DESIGN.md はその置き場として自然にハマります。

AIGP の DESIGN.md を作った

AIGP 本体（Next.js 16 + shadcn/ui + Tailwind v4）のリポジトリ直下に DESIGN.md を新規作成しました。frontmatter は既存 globals.css の値と、先週のチャート刷新で決めた色をそのまま起こしたものです。

特徴的な部分を抜粋:

---
version: alpha
name: AIGP
colors:
  primary: "#8C90FF"         # AIGP brand purple
  accent-pink: "#FF8CC3"
  accent-green: "#8CFFB6"
  surface: "#FEFDF4"         # cream, never #fff
  on-surface: "#4D5156"
  chart-paid: "#10B981"      # emerald (決済済)
  chart-free: "#C7D2FE"      # indigo-200 (無料)
rounded:
  xl: 1.4rem                 # 管理画面カード
  2xl: 1.8rem                # 記事面カード
---

そして本文の Do’s / Don’ts には、意図を残しています:

• ✓ surface は必ず cream #FEFDF4 を使う — 純白は目が疲れる
• ✗ チャート色を直接 hex 指定せず、chart-paid / chart-free トークンを参照する
• ✗ shadow-md 以上を使わない（AIGP は border で階層を作る平面デザイン）
• ✗ サイドバーの 6 カテゴリ順序（広告・分析 → 投稿管理 → 自動化 → コミュニティ → コンテンツ → システム）は壊さない

これらは従来 Claude の自動メモリに散在していたルール。DESIGN.md に明文化することで、リポジトリを clone した時点で AI エージェントが読める状態になりました。

export フローで「単一ソース化」も目指せる

alpha が安定したらやりたいのが、export による単一ソース化です。

現状 AIGP は以下が二重管理:

• DESIGN.md（人間と AI が読む）
• globals.css の CSS 変数（ランタイムで参照する）

これを @google/design.md export --format=tailwind で tailwind.config.js を自動生成するようにすれば、DESIGN.md が唯一のソース になります。ただし @google/design.md 自体が alpha で破壊的変更が予告されているため、今は二重管理を許容しています。

向いていない使い方

• 超小規模プロジェクト — DESIGN.md のオーバーヘッドに対してリターンが見合わない。README に色を書いておけば十分。
• 複数デザイナーで頻繁に更新する大規模組織 — 現段階では Figma 連携のエコシステムが未成熟。Style Dictionary / Design Tokens CG の既存ツールと併用する形になる。
• CLI 自動化を即導入したい — まだ alpha。仕様・トークンスキーマ・CLI すべてが変わる可能性があると仕様書に明記されています。

まとめ

DESIGN.md は「AI エージェントに渡す設計書」として単純だけど決定的な価値があるフォーマットでした。AIGP のように 1 人運用で、Claude Code や Cursor を中心に開発するプロジェクトには特に刺さります。

今日やったこと:

• AIGP のリポ直下に初版 DESIGN.md を作成（約 160 行、frontmatter + 8 セクション本文）
• 既存の globals.css 変数とメモリに散在していたルールを統合
• Do’s / Don’ts に「なぜ」を書き残し、次セッションの AI が再発見する必要をなくした

今後は仕様が alpha → beta → stable と進むのを見ながら、export による単一ソース化と lint の CI 組み込みを検討していきます。UUPM と DESIGN.md の合わせ技で、デザイン判断を再現可能な資産に変える 運用を試していきます。

• 仕様: github.com/google-labs-code/design.md
• Google Blog 発表記事: Stitch’s DESIGN.md format is now open-source
• AIGP の DESIGN.md: master/DESIGN.md