ドキュメント
DESIGN.mdとは?
DESIGN.mdは、AIエージェント向けにデザインシステムを記述するプレーンテキストのファイルです。冒頭のYAMLのフロントマターには、カラー、タイポグラフィ、スペーシング、角丸、コンポーネントといった正確なデザイントークンが入ります。その下のMarkdownの本文では、それらをどのように、なぜ適用するのかを説明します。人もエージェントも読んで、編集し、ルールとして守ることができます。
README.mdはプロジェクトが何であるかを説明します。AGENTS.mdはコーディングエージェントにその作り方を伝えます。DESIGN.mdは見た目と使い心地がどうあるべきかを伝えるので、エージェントが生成する画面がばらばらにならず、1つのパレット、タイプスケール、コンポーネントの言語を共有できます。
DESIGN.mdの由来
Googleは、AIデザインツールであるGoogle Stitchとともに、AGENTS.mdのデザイン版としてDESIGN.mdを導入しました。Google Labsはこの形式を、google-labs-code/design.mdリポジトリでApache 2.0ライセンスのもとオープンな仕様として公開しています。DESIGN.mdの仕様はアルファ版とされているため、成熟に伴って形式が変わる可能性があります。
同じリポジトリでは、npmパッケージ@google/design.mdも提供されています。構造、壊れたトークン参照、WCAGのコントラストをチェックするlintコマンドと、ファイルの2つのバージョンをトークン単位で比較するdiffコマンドが含まれています。
DESIGN.mdファイルの構造
どのDESIGN.mdファイルも2つの層で構成されています。YAMLのフロントマターには、正確なカラー値、フォントのプロパティ、スペーシングのスケール、コンポーネントのトークン参照など、機械可読なデザイントークンが入ります。Markdownの本文では、人が読めるデザインの意図を説明します。
仕様では、トークンを規範となる値、文章をその適用のための文脈として扱います。トークンはエージェントに正確な値を伝え、文章はその値がなぜ存在し、画面全体で一貫して使うにはどうすればよいかを伝えます。
---
name: DevFocus Dark
colors:
primary: "#2665fd"
secondary: "#475569"
surface: "#0b1326"
on-surface: "#dae2fd"
error: "#ffb4ab"
typography:
body-md:
fontFamily: Inter
fontSize: 16px
fontWeight: 400
rounded:
md: 8px
---
# Design System
## Overview
A focused, minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- **Primary** (#2665fd): CTAs, active states, key interactive elements
- **Secondary** (#475569): Supporting UI, chips, secondary actions
- **Surface** (#0b1326): Page backgrounds
- **On-surface** (#dae2fd): Primary text on dark backgrounds
- **Error** (#ffb4ab): Validation errors, destructive actions
## Typography
- **Headlines**: Inter, semi-bold
- **Body**: Inter, regular, 14-16px
- **Labels**: Inter, medium, 12px, uppercase for section headers
## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill
- **Inputs**: 1px border, subtle surface-variant background
- **Cards**: No elevation, relies on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, only for the most important action
- Don't mix rounded and sharp corners in the same view
- Do maintain 4:1 contrast ratio for all text8つの標準セクション
Markdownの本文では##見出しを使います。関係のないセクションは省略できますが、含める場合は次の順序に従う必要があります。同じ見出しが2回現れるとファイルは無効になります。未知のセクションはそのまま保持されます。
- Overview(Brand & Styleとも)。見た目と雰囲気を数文で。ムード、密度、個性。
- Colors。各カラートークンと、主要なアクションやページのサーフェスといった、その役割。
- Typography。フォントファミリーと、大見出しから小さなラベルまでのタイプスケール。
- Layout(Layout & Spacingとも)。スペーシングのスケール、グリッド、コンテンツ幅、ガター。
- Elevation & Depth(Elevationとも)。影、ボーダー、色味など、サーフェスの区別の仕方。
- Shapes。角丸やその他の形状のルール。
- Components。ボタン、入力欄、カードなどの要素と、そのトークンと状態。
- Do's and Don'ts。エージェントが破ってはいけないルール。
各標準セクションを順に並べた、簡潔なMarkdown本文の例です。内容はプロダクトに合わせて調整し、見出しと順序はそのままにしてください。
## Overview
A minimal dark interface for a developer productivity tool.
Clean lines, low visual noise, high information density.
## Colors
- Primary (#2665fd): CTAs and active states
- Surface (#0b1326): Page backgrounds
- On-surface (#dae2fd): Text on dark backgrounds
## Typography
- Headlines: Inter, semibold
- Body: Inter, regular, 14-16px
- Labels: Inter, medium, 12px, uppercase
## Layout
- 8px base spacing unit, scale: 4 / 8 / 16 / 24 / 32 / 48
- Max content width 720px with 24px gutters on mobile
## Elevation & Depth
- Surfaces rely on background contrast instead of shadow
- Overlays use an 8 percent white tint on dark surfaces
## Shapes
- Rounded 8px for controls, 16px for cards
- Avoid mixing sharp and rounded corners in one view
## Components
- Buttons: 8px rounded, primary filled with brand blue
- Inputs: 1px border, subtle surface-variant background
- Cards: no elevation, rely on border and background contrast
## Do's and Don'ts
- Do use the primary color sparingly, for the most important action
- Don't mix rounded and sharp corners in one view
- Do maintain at least a 4:1 contrast ratio for all textデザイントークンとスキーマ
DESIGN.mdは、ファイルの先頭にYAMLのフロントマターとしてデザイントークンを埋め込みます。フロントマターのブロックは、---だけを含む行で始まり、同じ区切り線で終わります。
version: <string>
name: <string>
description: <string>
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>よく使われるスケール名にはxs、sm、md、lg、xl、fullがありますが、意味がわかるキーであれば何でもかまいません。スペーシングのトークンはYAMLのspacing:の下に置き、Markdown本文のLayoutセクションで説明します。
トークンの種類
- Color
- 有効なCSSのカラー文字列。
#RRGGBB形式のhexが推奨されるデフォルトです。例:"#1A1C1E"。 - Dimension
- 数値にpx、em、remの単位を付けたもの。例:
48px、-0.02em。 - Token Reference
- 波括弧で囲み、YAMLツリー内の値を指します。例:
{colors.primary}。 - Typography
- ファミリー、サイズ、ウェイト、行の高さ、文字間隔などのフォントのプロパティを含む複合オブジェクト。タイポグラフィのプロパティをご覧ください。
タイポグラフィのプロパティ
- fontFamily
- フォントファミリー名。
- fontSize
- Dimensionで表したフォントサイズ。
- fontWeight
- 400や700などの数値のウェイト。
- lineHeight
- Dimension、または単位なしの倍率。単位なしの値が推奨されます。
- letterSpacing
- Dimensionで表した文字間隔の調整値。
- fontFeature
- font-feature-settingsを設定します。
- fontVariation
- font-variation-settingsを設定します。
トークン参照
トークン参照は波括弧で囲み、YAMLツリー内の別の値へのオブジェクトパスを含みます。ほとんどのトークングループでは、参照はグループではなくプリミティブな値を指す必要があります。componentsセクション内では、タイポグラフィのレベルなどの複合値への参照も認められています。
components:
button-primary:
backgroundColor: "{colors.primary-60}"
textColor: "{colors.primary-20}"
rounded: "{rounded.md}"
button-primary-hover:
backgroundColor: "{colors.primary-70}"コンポーネント
componentsセクションには、ボタン、チップ、リスト、入力欄、チェックボックス、ラジオボタン、ツールチップなどのコンポーネント要素のスタイルガイダンスを記述します。デザインシステムは、プロダクトの領域で重要な追加のコンポーネントを定義できます。
ホバー、アクティブ、押下時の状態のバリアントは、button-primary-hoverのように関連するキー名を持つ別のコンポーネント項目として定義します。
- backgroundColor
- Color
- textColor
- Color
- typography
- Typography
- rounded
- Dimension
- padding
- Dimension
- size
- Dimension
- height
- Dimension
- width
- Dimension
推奨されるトークン名
これらの名前は必須ではなく、目安です。システム間で一貫性を保つための便利なデフォルトになります。
Colors:primary, secondary, tertiary, neutral, surface, on-surface, error
Typography:headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm
Rounded:none, sm, md, lg, xl, full
AIエージェントによるDESIGN.mdの使い方
DESIGN.mdは、リポジトリのルートにREADME.mdやAGENTS.mdと並べて置きます。ファイルにアクセスできるエージェントなら読み込めますが、多くは自動では読み込みません。エージェントがすでに読んでいる指示からDESIGN.mdを参照するか、UIの作業を頼むときにプロンプトでファイル名を挙げてください。短い一文で十分です。
## Design
Follow DESIGN.md for every UI change: use its color, typography,
spacing and component tokens instead of inventing new values.- Claude Code
- リポジトリのファイルを読み込み、起動時にCLAUDE.mdを読み込みます。そこにDESIGN.mdを参照する一行を追加するか、プロンプトでファイルに言及してください。
- Cursor
- DESIGN.mdをチャットのコンテキストに追加するか、プロジェクトルールから参照して、すべてのUIリクエストに適用されるようにします。
- GitHub Copilot
- リポジトリのCopilot指示ファイルからDESIGN.mdを参照するか、UIの作業を頼むときにチャットに添付します。
- Google Stitch
- この形式の発祥の地です。StitchはDESIGN.mdを使い、生成する画面で1つのパレット、タイプスケール、コンポーネントの言語を共有します。
エージェントはトークンから正確な値(primaryボタンのhexやbody-mdラベルのサイズ)を取り出し、文章をもとにそれをどこに使うかを判断します。
DESIGN.md、AGENTS.md、README.mdの違い
3つのファイルは並べて置かれ、それぞれ異なる問いに答えます。DESIGN.mdはAGENTS.mdを置き換えるものではなく、両者は連携して機能します。
| ファイル | 対象読者 | 答える問い |
|---|---|---|
README.md | プロジェクトを利用する人や貢献する人 | これは何で、どう動かすのか? |
AGENTS.md | コーディングエージェント | このコードをどうビルドし、テストし、変更するのか? |
DESIGN.md | コーディングエージェントとデザインエージェント | インターフェースはどのような見た目と使い心地であるべきか? |
実際のDESIGN.mdのサンプル
形式を理解する一番の近道は、実際のファイルをいくつか読むことです。以下のギャラリーページでは、それぞれブランドの公開Webサイトから抽出したDESIGN.mdを、パレットとタイプ見本とともに紹介しています。公式のブランドガイドラインではありません。
DESIGN.mdの入手方法
- 手で書く。仕様と上のサンプルを出発点にし、無料のDESIGN.mdバリデーターやGoogleの
lintコマンドでファイルをチェックします。 - サンプルから始める。ギャラリーからファイルをコピーし、トークンと文章をプロダクトに合わせて編集します。
- 実際のWebサイトから生成する。公開URLをDesign Extractorに貼り付けます。サイトをブラウザでレンダリングし、上の仕様に沿って、カラー、タイポグラフィ、スペーシング、コンポーネントをまとめたDESIGN.mdを返します。何が得られるかはDESIGN.mdジェネレーターのページで説明しています。同じ抽出はChrome拡張機能からも、MCPサーバーを通じてエージェントからも実行できます。
よくある質問
DESIGN.mdに関する質問
DESIGN.md形式、その由来、AIエージェントでの使い方についての簡潔な回答です。
DESIGN.mdは、AIエージェント向けにデザインシステムを記述するプレーンテキストのファイルです。冒頭のYAMLのフロントマターには正確なトークン(カラー、タイポグラフィ、スペーシング、角丸、コンポーネント)が入り、その下のMarkdownの本文では、それらをどのように、なぜ適用するのかを説明します。エージェントは値をトークンから、意図を文章から読み取ります。
Googleが、AIデザインツールであるStitchとともにDESIGN.mdを導入しました。Google Labsは仕様をGitHub(google-labs-code/design.md)でApache 2.0ライセンスのもと公開しています。この形式はアルファ版とされているため、成熟に伴って変更される可能性があります。
AGENTS.mdは、コーディングエージェントにプロジェクトのビルド方法や作業方法(コマンド、規約、テスト)を伝えます。DESIGN.mdは、プロダクトの見た目と使い心地(カラー、書体、スペーシング、シェイプ、コンポーネント)を伝えます。README.mdは、プロジェクトを利用する人や貢献する人のためのものです。多くのリポジトリでは3つすべてを並べて置いています。
ファイルにアクセスできるエージェントが見つけられるよう、リポジトリのルートにREADME.mdやAGENTS.mdと並べて置きます。そのうえで、AGENTS.md、CLAUDE.md、Cursorのルール、Copilotの指示など、エージェントがすでに読み込んでいる指示から参照するか、UIの作業を頼むときにプロンプトで言及してください。
いいえ。仕様では該当しないセクションを省略できますが、残すセクションは標準の順序(Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts)に従う必要があります。同じセクション見出しを2回使うことはできず、未知のセクションは拒否されずにそのまま保持されます。
Googleのnpmパッケージ@google/design.mdには、構造、壊れたトークン参照、WCAGのコントラストをチェックするlintコマンドがあります。Design Extractorにも無料のDESIGN.mdバリデーターがあり、ファイルをアップロードせずにブラウザ内で構造とトークンをチェックし、プレビューできます。
仕様をもとに手で書く、実際のサンプルを集めたギャラリーからコピーして出発点にする、または実際のサイトから生成する、のいずれかです。Design Extractorは公開URLを受け取り、ブラウザでサイトをレンダリングして、カラー、タイポグラフィ、スペーシング、コンポーネントをまとめたDESIGN.mdを返します。そのままリポジトリに置けます。
気に入ったサイトのDESIGN.mdが欲しいですか?
公開URLを貼り付けて、DESIGN.mdを取得しましょう。