DESIGN.md：Codex にデザインシステムを渡す。

DESIGN.md は、AI エージェントにデザインシステムを伝えるためのプレーンテキストのファイルです。正確な色、文字、余白、コンポーネントと、その理由を書きます。リポジトリに 1 つ置いておけば、Codex は新しい画面をすべて同じビジュアル言語でデザインします。

2026年11月2日更新 · 約 8 分で読めます

DESIGN.md とは？

DESIGN.md は、ビジュアルアイデンティティをコーディングエージェントに伝えるための、Google Labs によるオープンなフォーマットです。Google Stitch から生まれ、Apache 2.0 ライセンスで公開されています。仕様はまだ alpha とされているので、今後変わる可能性があります。

DESIGN.md ファイルは 2 つの層でできています。

YAML のデザイントークン。 色、タイポグラフィ、角の半径、余白、コンポーネントのスタイルを、機械が読める正確な値で書きます。トークンが基準となる値です。
Markdown の文章。 理由を書く部分です。プロダクトがどんな印象であるべきか、それぞれの色をいつ使うか、何を避けるか。文章は、トークンをどう適用するかをエージェントに伝えます。

こうしたファイルがないと、エージェントは画面を頼むたびに新しい青の色合いや新しいボタンのスタイルを選んでしまいます。ファイルがあれば、50 枚目の画面も 1 枚目と揃います。

DESIGN.md に書くこと

トークンはファイル先頭の YAML フロントマターに書くことも、各セクション内の yaml コードブロックに書くこともできます。スキーマには 5 つのトークングループがあります。

グループ	内容	例
`colors`	任意の CSS カラー。少なくとも `primary` は必須	`primary: "#1F3D2B"`
`typography`	フォントファミリー、サイズ、太さ、行の高さ	`body-md: { fontSize: 16px, ... }`
`rounded`	角の半径のスケール	`md: 12px`
`spacing`	余白のスケール	`md: 16px`
`components`	トークンを参照するコンポーネントのスタイル	`backgroundColor: "{colors.primary}"`

文章は ## のセクションで書きます。どのセクションも省略できますが、入れる場合は次の順番にします：Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do’s and Don’ts。

完全な記入例

この DESIGN.md は、モバイルアプリのプロンプトのページで使っている読書アプリを記述したものです。リポジトリのルートに DESIGN.md として保存します。

---
version: alpha
name: Pagely
description: Calm, bookish UI for a reading-habit app.
colors:
  primary: '#1F3D2B'
  on-primary: '#FAF6EE'
  secondary: '#E8735A'
  tertiary: '#F2C14E'
  neutral: '#FAF6EE'
  surface: '#FFFFFF'
  on-surface: '#1F2A22'
typography:
  headline-lg:
    fontFamily: Georgia
    fontSize: 32px
    fontWeight: 400
    lineHeight: 1.15
  body-md:
    fontFamily: system-ui
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
  label-caps:
    fontFamily: system-ui
    fontSize: 13px
    fontWeight: 500
    letterSpacing: 0.12em
rounded:
  md: 16px
  lg: 22px
  full: 9999px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: '{colors.primary}'
    textColor: '{colors.on-primary}'
    rounded: '{rounded.md}'
    padding: 18px
---

## Overview

Quiet, warm, and bookish, like a café with good light. Screens feel spacious and
unhurried; one clear next step per screen.

## Colors

- **Primary (#1F3D2B):** Deep forest green for primary actions and the streak card.
- **Secondary (#E8735A):** Coral for progress and small highlights only.
- **Tertiary (#F2C14E):** Warm yellow for streak and goal indicators.
- **Neutral (#FAF6EE):** Cream background for every screen, never pure white.

## Typography

Georgia for headlines gives a literary voice. System UI for everything else keeps
body text crisp. Labels are uppercase with wide letter spacing.

## Layout

24px side margins on phones. Spacing follows an 8px scale. Primary actions sit in
the lower half of the screen, within thumb reach.

## Elevation & Depth

No heavy shadows. Depth comes from white cards with a 1px warm border on the cream
background.

## Shapes

Soft and rounded: 16px for buttons and inputs, 22px for cards.

## Components

Primary buttons are full-width, deep green, 18px padding. One primary button per screen.

## Do's and Don'ts

- Do keep text contrast at WCAG AA or better.
- Do use coral sparingly: progress bars and one highlight per screen.
- Don't use pure black or pure white.
- Don't put more than two type sizes in a single card.

Codex に守らせる方法

Codex は AGENTS.md を自動で読みます。リポジトリのルートから、作業中のフォルダまで順にたどります。DESIGN.md は自分では探さないので、AGENTS.md から参照させましょう。

## Design

- Before any UI work, read DESIGN.md and use only its tokens.
- If a screen needs a value that DESIGN.md doesn't define, ask before inventing one.
- After editing DESIGN.md, run `npx @google/design.md lint DESIGN.md` and fix any errors.

あとはいつもどおり画面を頼むだけです。プロンプトでファイルに触れると、意図がはっきり伝わります。

DESIGN.md に沿ってデザイン

DESIGN.md に従って、[設定] 画面を 390×844 の自己完結した HTML ファイル 1 つでデザインしてください。色、文字サイズ、角の半径、余白は DESIGN.md にあるものだけを使い、定義されていないものが必要になったら教えてください。

Codex に DESIGN.md を書いてもらう

ファイルを手で書く必要はほとんどありません。すでにプロダクトがあるなら、コードから Codex に抽出してもらいましょう。

コードから DESIGN.md を作る

Tailwind の設定、グローバル CSS、よく使われているコンポーネント上位 5 つを読み、リポジトリのルートに DESIGN.md を書いてください。まず `npx @google/design.md spec` を実行し、そのフォーマットに従ってください。トークンは YAML フロントマターに書き、続けて Overview、Colors、Typography、Layout、Elevation & Depth、Shapes、Components、Do's and Don'ts のセクションを書きます。値はコードに実在するものだけを使ってください。最後に `npx @google/design.md lint DESIGN.md` を実行し、エラーがあれば修正してください。

新しいプロダクトなら、キャンバスで承認したモックアップや参考スクリーンショットなど、気に入った方向性から始めましょう。

デザインから DESIGN.md を作る

これが承認された画面デザインです [スクリーンショットを添付するか、HTML ファイル名を指定]。その色、文字、余白、角の半径、ボタンのスタイルをとらえた DESIGN.md を書いてください。どんな印象であるべきかを短くまとめた Overview と、Do's and Don'ts を 5 つ入れてください。フォーマットは `npx @google/design.md spec` の DESIGN.md 形式に従ってください。

コマンドラインツール @google/design.md では、lint でコントラスト比や壊れたトークン参照をチェックし、diff で 2 つのバージョンを比べ、export でトークンを Tailwind のテーマや W3C デザイントークンに変換することもできます。

DESIGN.md、SKILL.md、AGENTS.md の違い

この 3 つのファイルは同じリポジトリに置かれることが多く、それぞれ役割が違います。

ファイル	エージェントに伝えること	例
`DESIGN.md`	プロダクトの見た目	色、文字、余白、コンポーネントのスタイル
`SKILL.md`	ある種類のタスクのやり方。必要なときに読み込まれる	デザインレビューのチェックリストやワークフロー
`AGENTS.md`	プロジェクトの常設の指示。毎回読まれる	ビルドコマンド、規約、「DESIGN.md を読むこと」

3 つは組み合わせるとうまく働きます。デザインスキルで「何かをデザインする前に DESIGN.md を読むこと」と指示し、AGENTS.md でスキルがなくても必ずそうなるようにします。スキルについて詳しくは Codex のプラグインとスキルの違いを参照してください。

記入例の探し方

オープンソースのコレクション awesome-design-md には、有名な Web サイトのデザインシステムを記述した DESIGN.md ファイルが、それぞれプレビューページ付きで集められています。ほかの人が色、文字、コンポーネントをどう記述しているかを学ぶのに役立ちます。構成の参考として使い、他社のブランドをコピーする手段にはしないでください。

よくある質問

DESIGN.md は公式の標準ですか？

Google Labs によるオープンな仕様で、Google Stitch で使われ、GitHub で公開されています。仕様はまだ alpha で、ドキュメント自体にもフォーマットは変わると書かれています。

Codex は DESIGN.md に対応していますか？

Codex はリポジトリ内のどんなファイルでも読んで従えます。特別な設定はありません。上で紹介したように、AGENTS.md やプロンプトから DESIGN.md を参照させてください。

DESIGN.md は Figma やデザインシステムの代わりになりますか？

なりません。DESIGN.md は、エージェントが読めるようにデザインシステムをテキストでまとめたものです。正となる情報を Figma やコードで管理しているチームは、そこから DESIGN.md を生成し、システムが変わったら更新できます。