AIのデザインを統一するDESIGN.mdの書き方
色や余白、使い方をAIと共有できるデザイン指針にまとめます。
AIが生成する画面の色や余白が毎回違うなら、プロンプトより先に共有するデザイン基準が必要かもしれません。DESIGN.mdは、機械が読めるトークンと人が読めるデザインの意図を一つのファイルにまとめ、コーディングエージェントが一貫したビジュアル方針を参照できるようにします。
この記事ではGoogle Labsが公開した形式をもとに、実務で使える文書の作り方と、現在の制約を紹介します。
デザイントークンとブランド原則
primary: '#2457D6'というトークンがあれば、エージェントは正確な色を知ることができます。しかし、その青を主要ボタンだけに使うのか、リンクやバッジにも使うのか、暗い背景ではどう変えるのかまでは分かりません。値だけを渡すと、指定は正確でもどこか不自然な画面ができることがあります。
GoogleのDESIGN.mdは、YAMLのトークンとMarkdownの説明を組み合わせます。トークンは色、文字、余白などの再利用可能な値を示し、文章はその値がどんな印象を生み、どの場面で使われるのかを説明します。たとえば「暖かみのある紙色の背景は長文を読む画面に使い、アクセントカラーは主要な操作一つに限る」といった意図も記せます。
DESIGN.mdの目的と対象
ファイルの先頭にデザインシステムの名前を書き、最初のセクションで製品とユーザーを説明します。画面の目的も具体的にしましょう。「モダンで洗練されたサービス」より、「運用担当者が毎日注文状況を確認する管理画面であり、装飾より素早い把握とミスの防止を優先する」という説明のほうが、エージェントの判断に役立ちます。
---
name: Northstar Console
colors:
primary: "#2457D6"
ink: "#172033"
surface: "#FFFFFF"
canvas: "#F4F6FA"
muted: "#667085"
border: "#D8DEE9"
typography:
heading:
fontFamily: Inter
fontSize: 1.5rem
fontWeight: 650
body:
fontFamily: Inter
fontSize: 1rem
lineHeight: 1.5
rounded:
control: 8px
panel: 12px
spacing:
xs: 4px
sm: 8px
md: 16px
lg: 24px
components:
button-primary:
backgroundColor: "{colors.primary}"
textColor: "#FFFFFF"
rounded: "{rounded.control}"
padding: 10px
---
## Overview
運用担当者が注文状況をすばやく見つけ、ミスを減らすための管理画面です。
落ち着いた情報密度の高い画面にし、強い色は主要な操作と選択状態に限って使います。
これは出発点です。チームで使う用語に合わせてトークン名や階層を決め、コードのCSS変数やコンポーネント名と対応させてください。既存のシステムに--color-actionやButton/Primaryという名前があるなら、文書でも同じ意味を保ちます。
色・タイポグラフィ・余白のトークン
blue-500やgray-100のように色だけを表す名前では、使い方の判断が実装者に残ります。primary、surface、border、mutedのような役割名なら、画面の要素に対応させやすくなります。それぞれの色の目的も文章で説明し、成功・警告・エラーの状態色や、文字と背景の組み合わせが必要な製品では、そのルールも定義します。
タイポグラフィも書体名だけで済ませず、見出し、本文、補足テキストといった実際の階層に分け、サイズ、太さ、行間を指定しましょう。レイアウトには基準となる余白やコンテンツ幅を、形状にはボタンやカードの角丸を記録します。画面ごとに任意の値が増えるのを抑えられます。
コンポーネントのデザインルール
すべてのコンポーネントを一度に定義すると、文書はすぐに大きくなります。まず主要ボタン、入力欄、カード、ナビゲーションなど、使用頻度が高く画面の印象を左右する要素から始めましょう。ボタンなら高さ、内側の余白、角丸、フォーカス表示、文字色を決めます。入力欄なら通常、エラー、無効の状態と、補助テキストの配置も記せます。
ルールはコードで実装し、確認できるレベルで書きます。「軽やかな印象に」だけでは不十分です。「通常のカードに影を付けず、選択されたカードにだけ2pxのアクセント枠を付ける」なら目で確認できます。一方、すべてのピクセルや例外をDESIGN.mdに複製する必要はありません。実際のコンポーネントAPIやデザインシステムの文書を参照してください。このファイルには生成や変更に必要なデザインの背景をまとめ、実装の詳細すべてを入れないようにします。
推奨事項と禁止事項
Do’s and Don’tsのセクションには、繰り返し起きる間違いを記録します。たとえば「一つの画面で強調する主要操作は一つにする」「無効状態を色だけで区別しない」「本文の補助テキストのコントラストを下げない」といったルールです。例外への判断に役立つなら、理由も短く添えます。
外部のブランドやデザインシステムを参考にした場合は、公開された公式ガイドと、自分たちの観察や調整を区別します。公式仕様、公開画面から観察した値、独自に調整した値は、同じ種類の根拠ではありません。独自の解釈であれば、公式実装や完全準拠とは表現しないようにしましょう。
DESIGN.mdの適用と検証
プロジェクトのルートにDESIGN.mdを置き、コーディングエージェントに読むよう伝えます。アプリ全体を一度に生成させず、小さなタスクで確認しましょう。たとえば「ルールに沿ってログインフォームのボタンと入力欄だけを実装し、使ったトークンを教えて」と依頼します。色、余白、フォーカス動作が曖昧ならルールを見直します。
Google LabsのCLIは文書の構造、解決できないトークン参照、一部の文字色と背景色の組み合わせについてWCAG AA基準のコントラスト比を確認できます。次のコマンドで実行できます。
npx @google/design.md lint DESIGN.md
この検査は文書と一部のルールを確認するものです。画面が意図どおりに実装されたか、操作がアクセシブルか、すべてのデザインルールが守られたかを保証するものではありません。実際のページを開き、デスクトップとモバイル、キーボード操作、コントラスト、状態変化を確認しましょう。
アルファ仕様と文書の管理
DESIGN.mdは具体的なビジュアルの背景をエージェントに伝え、生成結果のばらつきを抑える助けになります。ただしGoogle Labsは現在、この形式をalphaとして公開しており、仕様、トークンスキーマ、CLIは開発中です。正式な国際標準と呼んだり、すべてのコーディングエージェントが自動的に読むと考えたりするのは早すぎます。利用するツールがファイルを読み込むか確認し、必要ならタスクのプロンプトやAGENTS.md、CLAUDE.mdから参照してください。
良い文書はトークンを大量に並べたものではありません。デザイナーと開発者が同じ判断を同じ言葉で説明でき、エージェントが画面を作るときにその判断を再利用できる文書です。まず重要な画面で試し、レビューで見つかった曖昧さを次の版に反映しましょう。