DESIGN.md入門

2026年9月21日

DESIGN.mdとは

背景: AIエージェントとデザインシステム

AIエージェントがUIを生成する際に、根本的な課題がある。デザインシステムに対する持続的で構造化された理解を維持できないのである。各セッションはゼロから始まる。どの色が何を意味するのか、タイポグラフィのスケールはどのように関係するのか、ブランドの個性は何か——これらの判断を毎回説明し直すか、あるいはエージェントの解釈に任せるしかない。

プロジェクト間、セッション間、プラットフォーム間でデザインルールを共有する標準的な手段は存在しない。

解決策

DESIGN.mdは、デザインシステムを人間とAIの両方が読み・理解し・更新できる形で表現する、自己完結的なプレーンテキストフォーマットである。ブランドとプロダクトのビジュアルアイデンティティを定義し、デザインセッションをまたいで、異なるAIエージェントやツール間で、スタイルの選択が一貫して守られることを保証する。

オープンで人間が読めるフォーマットであるDESIGN.mdファイルは、特定のツールやプラットフォームに依存しない、デザインシステムの信頼できる唯一の情報源（SSoT）となる。

特徴

• 2層構造 — 機械が読むデザイントークン（YAMLフロントマター）と、人間が読むデザイン判断の根拠（Markdown本文）を併せ持つ。トークンは正確な値をエージェントに与え、本文はその値が存在する理由と適用方法を説明する。
• ツール非依存 — オープンフォーマットであり、あらゆるツール・プラットフォームで使える。
• 意図+値 — トークンのみを持つファイルと異なり、DESIGN.mdは各デザイン判断の背後にある理由も捉える。エージェントは色値が #B8422E であることだけでなく、それが「インタラクションを駆動する唯一の色」であることも知っている。
• 相互運用性 — W3Cデザイントークンフォーマットから着想し、tokens.json、Figma変数、Tailwindテーマ設定と相互変換可能。

ファイルの構造

2つの層

DESIGN.mdファイルは2つの層からなる。

1. YAMLフロントマター — ファイル先頭の --- で囲まれた機械可読なデザイントークン。これが規範的値である。
2. Markdown本文 — ## セクションで構成された人間可読なデザイン判断の根拠。トークンをどう適用するかを示す文脈を提供する。

トークンは「何であるか」を定義し、本文は「なぜそうするか」「どう使うか」を定義する。

具体例

以下は簡潔なDESIGN.mdファイルの例である。

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. The UI evokes a
premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors

The palette is rooted in high-contrast neutrals and a single accent color.

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

このファイルを読んだエージェントは、Public Sansによる深いインクのヘッドライン、純白より柔らかい石灰色の背景、ボストンクレイのCTAボタンを持つUIを生成する。推測したからではなく、ファイルが各値の意味と適用方法を正確に伝えているからである。

デザイントークン

概念

DESIGN.mdはYAMLフロントマター内に構造化されたデザイントークンを埋め込む。トークンシステムはW3Cデザイントークンフォーマットから着想を得て、型付きトークングループ（colors, typography, spacing）の概念と、値のクロスリファレンス用の {path.to.token} 参照構文を採用している。

トークンは型付きグループに組織される。

• colors — トークン名から色値へのマップ
• typography — トークン名からタイポグラフィプロパティへのマップ
• spacing — スケールレベルからディメンション値へのマップ
• rounded — スケールレベルからディメンション値へのマップ
• components — コンポーネント名からサブトークングループへのマップ

スキーマ

version: <string>          # optional, current: "alpha"
name: <string>             # required
description: <string>      # optional
omitted: <string[] | OmittedSection[]>  # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

必須フィールドは name のみ。version、description、omitted は任意である。

トークンの型

• Color — 有効なCSSカラー値のいずれか。16進数（#1A1C1E）、名前付き（red）、関数（rgb(), hsl()）、広色域（oklch(), lab()）、混色（color-mix()）。シンプルさとツール対応の広さから、16進数が推奨されるデフォルトである。
• Dimension — 単位付きの数値（px, em, rem）。
• トークン参照 — 別のトークンへの参照。{path.to.token} の形式で書く（例: {colors.primary}）。
• Typography — fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, fontFeature, fontVariation を持つオブジェクト。

コンポーネントトークン

コンポーネントは、名前をサブトークンプロパティのグループにマッピングし、そのコンポーネントの外観を定義する。

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

利用可能なコンポーネントプロパティ: backgroundColor, textColor, typography, rounded, padding, size, height, width。

UI状態バリアント（hover, active, pressed）は、関連するキー名で別のコンポーネントエントリとして定義する。エージェントはすべてのバリアントを考慮して、適切なスタイル判断を行う。

本文セクション

セクションの順序

全セクションは ## 見出しを使う。関連しない場合は省略できるが、存在する場合は以下の順序で並ぶこと。

1. Overview（別名: Brand & Style）
2. Colors
3. Typography
4. Layout（別名: Layout & Spacing）
5. Elevation & Depth（別名: Elevation）
6. Shapes
7. Components
8. Do’s and Don’ts

各セクションの役割

• Overview — プロダクトの外観・印象の全体像。ブランドの個性、対象読者、UIが喚起すべき感情（遊び心かプロフェッショナルか、密か広やかか）を記述する。具体的なルールやトークンが定義されていない場合の基礎的な文脈として機能する。
• Colors — パレットを定義し、それぞれに意味的役割を割り当てる。最低限 primary 色を定義する必要がある。
• Typography — タイポグラフィレベル（通常9〜15レベル）と各レベルのフォント戦略を定義する。
• Layout — レイアウトとスペースの戦略を記述する。グリッドベース、流動的グリッド、あるいはそれ以外のアプローチ。
• Elevation & Depth — 視覚的階層をどう表現するか記述する。影、トーンレイヤー、ボーダー、コントラストなど、デザインスタイルに応じた方法。
• Shapes — 形状言語を記述する。角丸の大きさ、エッジの扱い、それらが創り出す美意識。
• Components — コンポーネント原子（ボタン、チップ、リスト、ツールチップ、入力フィールドなど）のスタイルガイドを提供する。
• Do’s and Don’ts — 実践的なガイドラインとよくある落とし穴。デザイン制作時の手引きとして機能する。

本文とトークンの関係

本文とトークンは協働するが、役割は異なる。

• 本文は説明的な色名（例: “Midnight Forest Green”）を使い、体系的なトークン名（例: primary）に対応させる。
• トークンは規範的値であり、本文は適用の文脈を提供する。
• エージェントは正確な値にはトークンを、トークンでは表現できない判断には本文を使う。

相互運用性

DESIGN.mdのトークンは、既存のデザイントークンエコシステムとの相互変換を前提に設計されている。

• W3Cデザイントークンフォーマット（DTCG） — tokens.json と互換
• Tailwind v3 — theme.extend JSON設定
• Tailwind v4 — CSSカスタムプロパティを使う @theme { ... } ブロック
• Figma変数 — 直接変換に対応

export コマンドが変換を行う。

npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json
npx @google/design.md export --format css-tailwind DESIGN.md > theme.css
npx @google/design.md export --format dtcg DESIGN.md > tokens.json

ツール

CLI

DESIGN.mdのCLI（@google/design.md）は4つのコマンドを提供する。

• lint — DESIGN.mdファイルの構造的正确性を検証する。トークン参照、WCAGコントラスト比、セクション順序などをチェックする。出力はエージェントが行動できる構造化JSONである。
• diff — 2つのDESIGN.mdファイルを比較し、トークンレベルと本文レベルの変更を報告する。レグレッション（後のファイルでエラーや警告が増えている）を検出する。
• export — DESIGN.mdのトークンを他フォーマット（Tailwind v3 JSON, Tailwind v4 CSS, DTCG tokens.json）にエクスポートする。
• spec — DESIGN.mdのフォーマット仕様を出力する。エージェントのプロンプトに仕様文脈を注入する際に有用。

全コマンドはファイルパスまたは -（標準入力）を受け取り、出力はJSONがデフォルトである。

リントルール

リンターは解析されたDESIGN.mdに対してルールを適用する。各ルールは固定の重要度レベルで検出結果を生成する。

• Error（ブロック）— broken-ref: 定義されたトークンに解決できないトークン参照
• Warning — missing-primary（primary色がない）、contrast-ratio（WCAG AA 4.5:1未満）、orphaned-tokens（定義されているが参照されていない）、missing-typography（タイポグラフィトークンがない）、section-order（標準順序から外れている）、unknown-key（タイポの可能性）、token-like-ignored（トークン風の値を持つ未知キー）
• Info — token-summary（セクションごとのトークン数）、missing-sections（任意セクションの欠如）、omitted-rules（omitted 設定の検証）

プログラムAPI

リンターはライブラリとしても利用可能である。

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

拡張性

DESIGN.mdは前方互換性を前提に設計されている。読み取り側が仕様で定義されていないコンテンツに出会った場合:

• 未知のセクション見出し、トークン名、コンポーネントプロパティは受け入れられる（未知のコンポーネントプロパティには警告）。
• 重複するセクション見出しのみがエラーとなり、ファイルが拒否される。
• omitted フィールドにより、セクションの意図的な省略が可能であり、該当セクションのリント警告を抑制する。

つまり、カスタムセクションやトークンでDESIGN.mdを拡張しても、互換性を壊さない。

現状

DESIGN.mdフォーマットはアルファバージョンである。仕様、トークンスキーマ、CLIは活発に開発が進められている。成熟につれてフォーマットが変わることを期待してよい。

参考文献

• Stitch’s DESIGN.md format is now open-source so you can use it across platforms (Google)
• DESIGN.md (GitHub)