DESIGN.md とは──AIにブランドを守らせるデザイン仕様ファイル（Google Labs）の役割と作り方

Claudeスキル・MCP デザイン・UI
DESIGN.md のアイキャッチ

AIにUIを作らせると、放っておけば“それっぽい汎用デザイン”になりがちです。DESIGN.md は、自社の配色・フォント・余白などのデザインシステムを1ファイルにまとめ、AIエージェントに毎回参照させるための仕様ファイル。Google Labs がオープンソースで公開した形式で、CLAUDE.md / AGENTS.md の“デザイン版”にあたります。役割と作り方を詳しく解説します。

DESIGN.md とは

DESIGN.md は、デザインシステムをコーディングエージェントに伝えるための、単一でバージョン管理できるファイルです。Google の AIデザインツール Google Stitch に2026年3月導入され、その後ツールから独立してオープンソースのドラフト仕様（google-labs-code/design.md、Apache-2.0）として公開されました。

狙いはシンプルで、AIが汎用的なUIに逃げず、自社のブランドどおりに生成するようにすること。エンジニアリングの文脈を CLAUDE.md / AGENTS.md が持続的に与えるのと同じ役割を、デザイン（見た目）の文脈で果たします。セッションをまたいで残り、リポジトリに付いて回る“持続的な契約”です。

ファイル構造：YAML＋Markdownの二層

1つのファイルの中に、機械可読のデザイントークン（YAMLフロントマター）と、人間可読のデザインの意図（Markdown本文）を同居させます。トークンが「正確な値」を、本文が「なぜ・いつ使うか」を伝えます。

---
# YAMLフロントマター（機械可読のトークン）
name: Heritage
colors:
  primary: "#1A1C1E"
  background: "#F7F3EC"
  tertiary: "#B8422E"
typography:
  headline:
    fontFamily: "Inter"
    fontSize: 48
    fontWeight: 700
spacing:
  scale: [4, 8, 16, 24, 32]
---

## Overview
建築的なミニマリズムと、報道的な重厚さの融合。

## Colors
- Primary (#1A1C1E): 見出しと本文の主役となる濃いインク色。
- Tertiary (#B8422E): 操作要素だけに使う唯一のアクセント。

トークンは colors（HEX）、typography（family / size / weight / lineHeight / letterSpacing）、spacing、角丸スケール、コンポーネントのプロパティ対応などをカバー。トークンの相互参照は {colors.primary} のような記法で書けます。

本文の見出しは“順序まで決まっている”

Markdown本文の ## 見出しは、規定された順序で並べます。これにより、どのDESIGN.mdも同じ構造になり、AIが迷わず読めます。

セクション書く内容
Overviewデザインの全体方針・世界観
Colors各色の役割（“primaryは見出し用”など意味づけ）
Typographyフォント・サイズ・太さ・行間の規則
Layoutレイアウト・グリッドの原則
Elevation & Depth影・奥行きの扱い
Shapes角丸・形状
Componentsボタン等コンポーネントのプロパティ対応
Do’s and Don’tsやってよいこと・避けること（意味的ルール）

付属CLIで“AIが自分の出力を検証”できる

このフォーマットの目玉が、公式CLI @google/design.md です。とくに lint は、AIエージェントがコードを書く前に、自分のデザイン変更をWCAG（アクセシビリティ）基準などで自己検証するループを可能にします。たとえば配色のコントラスト比が本文の最低基準を下回ると lint が検知し、エージェントは色を選び直す（または理由があれば上書きする）――という流れです。

コマンド役割
npx @google/design.md lint DESIGN.md壊れた参照・WCAG AAコントラスト・孤立トークン・セクション順序・タイポ欠落をチェック
npx @google/design.md diff DESIGN.md DESIGN-v2.mdバージョン間のトークン差分を検出（退行があれば終了コード1）
npx @google/design.md export --format tailwind DESIGN.mdトークンを Tailwind 設定や DTCG（W3C Design Tokens）形式へ書き出し
npx @google/design.md specフォーマット仕様を出力（エージェントのプロンプトに仕様を注入する用）

「AIが読んで終わり」ではなく「AIが頼れる・自分で検証できる」ファイルになっているのが、従来のスタイルガイドとの大きな違いです（“検証”の重要性は Claude Codeスキル『9つの型』の知見とも一致します）。

作り方：3つのルート

  1. Stitchで自動生成：「ミニマルで青と白、Inter、クリーンなカード」のような説明から初期版を生成。変更時もStitchが更新してくれる。
  2. テンプレートから書く：仕様のテンプレを取得して埋める。
  3. 手書き・既存資産から移植：Figmaのトークン、Tailwind設定、既存スタイルガイドがあれば、そのままDESIGN.md形式へ翻訳する。独自スキーマを覚える必要はなく、ただのMarkdown。

運用面では、テキストファイルなのでGitに自然に乗ります。トークンの変更履歴をコミットで追い、プルリクでレビューする――コードと同じ流れでデザインの決定を管理できます。迷った判断や例外を追記して、少しずつ育てていくのが基本です。

なぜMarkdownなのか

JSON/YAML単体のトークンファイルは機械可読でも人には読みにくく、スタイルガイド文書は人には読めても機械処理できません。DESIGN.md は両方を満たすうえ、LLMが学習済みのMarkdownなのでそのまま理解されやすく、コンテキスト消費も軽い（おおむね数千トークン）という利点があります。すでにビルドパイプラインでデザイントークンを使っている場合も、置き換えではなくexportで共存できます。

注意点

  • まだ alpha 版：仕様・トークンスキーマ・CLIは活発に開発中で、形式が変わる可能性があります。最新は公式リポジトリで確認を。
  • 万能ではない：DESIGN.md は“見た目の規約”。機能の要件や実装手順は別ファイル（requirements / design / tasks など）や AGENTS.md の役割です。1ファイル1役割で分けるのがコツ。

主な情報源

DESIGN.md は Google Labs によるオープンソース仕様（公開時点で alpha）。仕様・コマンドは変更される可能性があります。収集・要約はAI、公開判断は人。