DESIGN.md とは？

どのプロジェクトにも、カラー、フォント、余白、コンポーネントスタイルといった視覚的アイデンティティがあります。従来、それは Figma ファイルやブランド PDF、デザイナーの頭の中にありました。しかし、これらはいずれも AI エージェントが読み取れるものではありません。

DESIGN.md はそれを変えます。 人間とエージェントの両方が読み、編集し、適用できるプレーンテキストのデザインシステム文書です。AGENTS.md のデザイン版と考えるとよいでしょう：

ファイル	読む人	定義する内容
README.md	人間	プロジェクトの内容
AGENTS.md	コーディングエージェント	プロジェクトの構築方法
DESIGN.md	デザインエージェント	プロジェクトの見た目と印象

得られるもの

Stitch のようなデザインエージェントが DESIGN.md を読み取ると、生成するすべての画面が、あなたのカラーパレット、タイポグラフィ、コンポーネントパターンという同じ視覚ルールに従います。これがなければ、各画面はそれぞれ独立した存在になります。これがあれば、画面同士がまとまりのあるものに見えます。

DESIGN.md は静的な設定ファイルではなく、生きた成果物です。デザインの進化に合わせて更新されます。エージェントが生成し、あなたが磨き上げ、イテレーションのたびに画面へ再適用されます。

内部では、すべての DESIGN.md が 2 つのレイヤーを持ちます。機械可読なデザイントークン（正確な hex 値、フォントプロパティ、余白スケール）を含む YAML front matter と、人間可読なデザインの根拠を提供する markdown 本文です。トークンはエージェントに正確な値を与えます。文章は、その値が なぜ 存在するのかを伝えます。完全なフォーマットについては仕様を参照してください。

設計思想

DESIGN.md の仕様は処方箋ではなく土台です。エージェント、ツール、チームが依拠できる共通の基盤、つまりカラー、タイポグラフィ、レイアウト、コンポーネントの共通語彙を提供しつつ、ドメイン固有のニーズに合わせてフォーマットを拡張する自由を保ちます。未知のセクションやカスタムトークンは拒否されず、受け入れられます。

作成方法

DESIGN.md を作る方法は 3 つあり、手軽なものから精密なものまであります。

Stitch

エージェントに生成させる

雰囲気を説明します。エージェントが美的意図をトークンとガイドラインに変換します。

Stitch が完全なデザインシステム（カラー、タイポグラフィ、余白、コンポーネントスタイル）を生成し、DESIGN.md として要約します。

ブランディングから導出する

すでにブランドがある場合は、URL や画像を提供します。エージェントがパレット、タイポグラフィ、スタイルパターンを抽出し、既存の要素から DESIGN.md を構築します。

Stitch

手書きで作成する

上級者は DESIGN.md を直接記述し、正確なデザインの好みをそのまま書き表せます。各セクションは markdown と、デザイントークン用の任意の YAML front matter だけです。標準の markdown と YAML 以外の特別な構文はありません。

例

以下は、ダークテーマの生産性アプリ向けの最小限の DESIGN.md です。YAML front matter が正確なトークン値を定義し、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 text

エージェントは、次の画面を生成するときにこれを読み取ります。フォーマット仕様の完全版は仕様を参照してください。DESIGN.md を仕様に照らして検証するには、CLI で検証するを参照してください。