DESIGN.md とは

Claude Code や Cursor などの AI コーディングエージェントに、ブランドのデザインシステムを正確に伝えるためのファイル仕様です。Google のデザインツール Stitch のために開発され、2026年4月に Google Labs が Apache-2.0 ライセンスでオープンソース化しました。

プロジェクトに1つ置いておくだけで、どのツールやモデルでもそれを読み、ブランドに沿った UI を生成できるようにする。

特別なツールや Figma エクスポートは不要で、ただの Markdown ファイルである点が特徴です。

2 層構造:トークンと意図

ファイルは2つの層で構成されます。

YAML フロントマター には色・タイポグラフィ・余白・コンポーネントなどの「機械可読なデザイントークン」を正確な値で記述します。これがエージェントにとっての規範となります。

---
name: Heritage
colors:
  primary: "#1A1C1E"
  tertiary: "#B8422E"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
spacing:
  sm: 8px
  md: 16px
---

Markdown 本文 には「なぜその値なのか」という設計意図を散文で書きます。#1A1C1E とだけ書くのではなく「見出し用の深いインク色で、編集的な厳格さを表現する」まで記述するという思想です。見出しは Overview → Colors → Typography → Layout → Components → Do's and Don'ts の順が定められており、省略は可能ですが順番は守ります。

この2層の組み合わせが、エージェントに「正確な値」と「使い方の文脈」を同時に伝えます。

CLI ツール

@google/design.md という npm パッケージで4つのコマンドが提供されています。

コマンド 役割
lint 仕様適合チェック。壊れたトークン参照の検出や WCAG AA 基準 (4.5:1) のコントラスト比検証まで行う
diff 2バージョン間のトークン差分と劣化 (regression) を検出
export Tailwind v3/v4 や W3C Design Tokens Format (DTCG) など他フォーマットへ変換
spec 仕様そのものを出力。エージェントのプロンプトに仕様コンテキストを注入する用途に使う 
npx @google/design.md lint
npx @google/design.md export --format tailwind

W3C Design Token Format との関係は「競合」ではなく「補完」で、DTCG がツール連携のための機械的精度を優先するのに対し、DESIGN.md はブランドの文脈を人間とエージェントの両方に伝えることを優先しています。

広がるエコシステム

有名ブランドのデザインシステムを DESIGN.md 形式で配布する awesome-design-md のようなコミュニティリポジトリが登場しており、既成のデザインシステムを AI ツールにドロップインで使える仕組みが整い始めています。

現状のバージョンは 0.1.1、ステータスは alpha。仕様・トークンスキーマ・CLI はいずれも活発に開発中で、フォーマットが変わる可能性があるとされています。

まとめ

  • DESIGN.md は AI コーディングエージェント向けにデザインシステムを伝えるための Markdown ベースの仕様
  • YAML フロントマターに機械可読なトークン、本文に設計意図の散文という2 層構造
  • CLI (lint / diff / export / spec) で品質検証・フォーマット変換・仕様注入が可能
  • W3C DTCG と競合せず補完する位置づけで、コミュニティエコシステムも拡大中