AIエージェントは「言われたことを高速に形にする」のは得意ですが、人間のように暗黙の了解(行間)を読むのは苦手です。そのため、次の2つが欠けていると、もっともらしいけれど意図とはズレたアウトプットを量産してしまいます。
- 言語化されたデザインコンセプト:なぜ、どんな体験を目指すのか
- 実現手段の明確化:具体的な制約・実装手順・完了条件
この記事では、この2つをAIエージェントが正確に解釈・実行できる形で文書化する手法を整理します。そのうえで、concept.md / tokens.json / spec.md の3ファイル構成を紹介します。さらに、それを使って仕様駆動のループを回す手順を、検証コードつきで示します。後半ではその中核になる W3C DTCG 形式のデザイントークン を、$description をAIへの指示として書く前提で具体例つきで解説します。
デザインコンセプトを文書化する手法
デザインの思想やトーン&マナー、視覚的なルールを、AIが迷わず参照できる形に落とし込むための手法です。
デザイン原則とトーン&マナーの定義
「おしゃれに」「シンプルに」といった抽象的な言葉ではなく、トレードオフの判断基準を言語化します。
- 情報密度よりも視認性の高さを優先する
- 親しみやすさよりも信頼感を重視する
こう書いておけば、AIがレイアウトや表現で迷ったときの判断軸になります。「AもBも大事」ではなく「AとBが衝突したらAを取る」と書くのがポイントです。
デザイントークン(W3C DTCG フォーマット)
色・余白・タイポグラフィ・角丸などのデザイン要素を、ツールやプラットフォームに依存しない JSON で構造化する仕様です。W3C の Design Tokens Community Group(DTCG)が策定しており、2025年10月に初の安定版(2025.10)が公開されました。
単なるカラーコード(#0066CC)ではなく、color.brand.primary のように意味・役割を表す名前を付けられます。さらに $description で、どんな場面で使うかもセットで記述できます。つまり、コンセプト(意味)と具体的な値を直結させた状態でAIに読み込ませられます。具体的な書き方は後半で扱います。
コンテキストファイル(AGENTS.md / CLAUDE.md など)
プロジェクトのルートに置き、AIエージェントに常に参照させる Markdown 形式のファイルです。ブランドの世界観、禁止事項(アンチパターン)、使用するコンポーネントの原則などを書いておきます。
なお、Cursor の .cursorrules も同じ役割のファイルですが、現在は旧形式の扱いで、.cursor/rules/ 配下のプロジェクトルールへの移行が推奨されています。
実現手段を明確化する手法
コンセプトを具体的なタスクや仕様に落とし込み、AIに自律的に実行・検証させるための手法です。近年は「仕様駆動開発(Spec-Driven Development)」という考え方が広まっています。その代表的な手法を次の表にまとめます。
| 手法・標準 | 役割・特徴 | AIエージェント活用でのポイント |
|---|---|---|
| PRD(プロダクト要求仕様書) | 「誰の・どんな課題を・なぜ解決するか」を定義する伝統的なドキュメント | 背景の長い説明よりも、スコープ(やること・やらないこと)の境界線を明確に伝える役割を担う |
| Spec(実行可能な仕様書) | PRD をもとに「具体的にどう振る舞うべきか」「何をもって完了とするか」を定義する | 検証可能な完了条件(Acceptance Criteria、受け入れ基準)を書くことで、AI自身がアウトプットを自己評価・修正できる |
| BDD(振る舞い駆動開発 / Gherkin 記法) | Given(前提条件)/ When(ユーザー操作)/ Then(期待される結果)の定型文で振る舞いを記述する | 自然言語でありながら論理構造が明確なので LLM と相性が良く、画面遷移やインタラクションの定義に使いやすい |
| WBS / タスク分解(Plan フェーズ) | 大きなゴールを、AIが一度に処理できる小さなサブタスクに分割する | 1パスで全部作らせると破綻しやすいので、「構造設計 → トークン定義 → コンポーネント作成 → 画面結合」のようにステップを切る |
たとえば Gherkin 記法なら、完了条件を次のように書けます。後半で定義するデザイントークンの名前をそのまま使えば、spec.md と tokens.json がつながります。このアカウント削除の例は、後の「仕様駆動のループ」で最後まで追います。
Feature: アカウント削除
Scenario: 削除ボタンを押すと確認ダイアログが出る
Given ログイン済みのユーザーが設定画面を開いている
When 「アカウントを削除」ボタンを押す
Then 取り消せない操作であることを示す確認ダイアログが表示される
And ダイアログの実行ボタンは semantic.color.action.destructive の色で表示される
AIエージェントに渡すドキュメント構成
AIエージェントに UI デザインやフロントエンド実装を任せるときは、人間向けの分厚い企画書を1つ作るのではなく、役割ごとにファイルを分離して渡すのが効果的です。
| ファイル | 中身 |
|---|---|
concept.md | ターゲットユーザー、提供価値、デザインの判断基準(優先順位)、避けるべき表現(NG例) |
tokens.json | カラーパレット、フォントサイズ、余白のスケールなど(W3C DTCG 準拠の構造化データ) |
spec.md | 作るべき画面や要素の一覧、ユーザーフロー(Given-When-Then 形式)、レスポンシブやアクセシビリティの制約、完了条件 |
「思想(Why / What)」と「契約・手順(How / 完了条件)」を分けて言語化しておくことで、AIエージェントの自律性とアウトプットの精度を引き出せます。
人間が最初に用意するのはこの3つです。次の節で出てくる plan.md は、spec.md をもとにAIが生成する作業用のファイルで、人間はレビューだけを担います。
実現手段をどう回すか:仕様駆動のループ
PRD・Spec・BDD・タスク分解は、並べて用意するだけでは機能しません。順番に回し、各段階で「誰が」「何を成果物にし」「何をもって合格とするか」を決めておきます。そうすることで、AIに任せられる範囲が広がります。全体の流れは次のとおりです。
ポイントは、人間の判断が要るのは主に「境界を決める」「計画を承認する」「自動では測れないものを見る」の3種類で、それ以外はAIと自動検証の間で回ることです。例外として、AIのやり直しが続いたときと、検証コードを変えるときは人間に戻します(⑤⑥で後述)。
以下、アカウント削除の機能を例に、段階ごとに見ていきます。見出しの丸数字は図の番号に対応しています。
① PRD:やらないことを先に書く
PRD は人間が書きます。AIに対して特に効くのは、スコープの「やらないこと」です。
## スコープ
### やること
- 設定画面に「アカウントを削除」ボタンを追加する
- 削除の前に確認ダイアログを表示する
### やらないこと
- 削除したアカウントの復元機能
- 管理者による代理削除
AIは書かれていない部分を「気を利かせて」補います。やらないことを明記しておかないと、頼んでいない復元機能や設定項目が実装に紛れ込みます。
② spec.md:受け入れ基準と検証方法をセットで書く
受け入れ基準の下書きはAIに任せてかまいません。PRD と concept.md を渡して Gherkin で書かせ、人間が確定させます。このとき、基準ごとに何で確かめるかまで決めるのがポイントです。
## 受け入れ基準
| ID | 基準 | 検証方法 |
| ---- | ---------------------------------------------------------- | ---------------------------------- |
| AC-1 | 削除ボタンを押すと確認ダイアログが出る | E2E テスト(Playwright) |
| AC-2 | 実行ボタンは semantic.color.action.destructive の色 | E2E(計算済みスタイルを確認) |
| AC-3 | 色・余白にハードコードした値を使わない | Stylelint |
| AC-4 | 確認ダイアログに WCAG 2.1 AA の自動検査で違反がない | axe-core |
| AC-5 | 取り消せない操作であることが一目で伝わる | 人間のレビュー(concept.md と照合)|
表は受け入れ基準の索引です。AC-1 のような振る舞いの詳細は、前半の例のような Gherkin のシナリオとして同じ spec.md に書きます。検証方法の列にある E2E テストは、ブラウザで画面を実際に操作して確かめるエンドツーエンドのテストのことです。
検証方法が書けない基準は、AIが自己評価できないので、完了条件として機能しません。逆に AC-5 のように自動化できないものは、無理に自動化せず「人間が見る」と明記しておきます。自動で測れるものと人間が見るものを最初に分けておくと、後段のレビューで見るべき範囲が絞れます。
③④ plan.md:AIに分解させ、人間は粒度と順番を見る
spec.md が決まったら、AIにタスクを分解させます。
## タスク
- [ ] T1: semantic.color.action.destructive をトークンに追加する(AC-3)
- [ ] T2: ConfirmDialog コンポーネントを作る(AC-2, AC-4)
- [ ] T3: 設定画面に削除ボタンを置き、ダイアログと結合する(AC-1, AC-5)
人間のレビューで確かめるのは、中身の正しさよりも次の3点です。
- 粒度:1タスクが、1回の検証で合否を出せる大きさになっているか
- 対応:どのタスクにも、対応する受け入れ基準の ID が付いているか(付いていないタスクは、終わったかどうかを判定できない)
- 順番:トークン → コンポーネント → 画面のように、依存される側から作る順になっているか
⑤⑥ 実装と自動検証:1タスクずつ、検証が通るまで
AIには1タスクずつ実装させ、終わるたびに spec.md に書いた検証方法をそのまま実行させます。図の「a11y」はアクセシビリティ(accessibility)の略で、ここでは axe-core による検査を指します。たとえば AC-3 は Stylelint の組み込みルールで機械的に検査できます。
{
"ignoreFiles": ["src/styles/tokens.css"],
"rules": {
"color-no-hex": true,
"color-named": "never",
"function-disallowed-list": ["rgb", "rgba", "hsl", "hsla"],
"unit-disallowed-list": ["px"]
}
}
tokens.json から Style Dictionary などのツールで CSS 変数に書き出したファイル(ここでは tokens.css)だけは生の値を持つので、ignoreFiles で除外します。それ以外のファイルでは #DC2626 や 16px を書くとエラーになり、var(--color-action-destructive) のようなトークン経由の参照しか通りません。
AC-1・AC-2・AC-4 は、Playwright と axe-core(@axe-core/playwright)で書けます。
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
// AC-1, AC-2
test('削除ボタンを押すと確認ダイアログが出る', async ({ page }) => {
await page.goto('/settings/');
await page.getByRole('button', { name: 'アカウントを削除' }).click();
const dialog = page.getByRole('dialog');
await expect(dialog).toBeVisible();
await expect(dialog).toContainText('取り消せません');
// semantic.color.action.destructive(#DC2626)で塗られているか
await expect(dialog.getByRole('button', { name: '削除する' }))
.toHaveCSS('background-color', 'rgb(220, 38, 38)');
});
// AC-4
test('確認ダイアログに WCAG 2.1 AA の自動検査で違反がない', async ({ page }) => {
await page.goto('/settings/');
// 閉じたダイアログは検査対象にならないので、開いてから検査する
await page.getByRole('button', { name: 'アカウントを削除' }).click();
const results = await new AxeBuilder({ page })
.withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa'])
.analyze();
expect(results.violations).toEqual([]);
});
AC-2 のテストが rgb(220, 38, 38) を直書きしているのは意図的です。ハードコード禁止は実装側のルールで、テスト側では期待値を生の値で書いておくと、トークンの値が意図せず変わったときにも気づけます。
AC-4 は、画面を開いただけで検査すると、肝心のダイアログ内のコントラスト不足を見逃したまま合格してしまいます。実際に実行ボタンの背景を淡い赤(#FCA5A5)に変えると、このテストは失敗し、axe はコントラスト比 1.89:1 の違反を報告します。
検証に落ちたら、AIに失敗ログを読ませて直させます。ここで決めておきたいルールが2つあります。
- やり直しに上限を設ける:同じタスクで3回落ちたら止めて人間に渡します(回数は目安です)。何度も落ちる原因は、実装よりも
spec.mdやトークンの側の矛盾であることが多く、AIに直させ続けても解決しません - 検証コードの変更は人間の承認制にする:AIはテストを緩めて合格させることがあります。期待値の書き換えやテストの削除は、実装の修正とは別に人間が確認します
⑦ 意匠面のレビュー:ズレの原因に応じて直す文書を変える
自動検証が通っても、「警告が強すぎて怖い」「全体に窮屈」といった印象の問題は残ります。ここは人間が concept.md の判断基準と照らしてレビューします。すべてのタスクで行う必要はなく、AC-5 のように人間が見る受け入れ基準が紐づいたタスク(この例では T3)だけで十分です。plan.md で各タスクに AC の ID を付けておくのは、このためでもあります。
画面を実際に触るので、spec.md の漏れによる振る舞いのズレもここで見つかります。大事なのは、指摘をチャットでAIに伝えて直させるだけで終わらせないことです。チャットで直した内容はそのタスク限りで、次のタスクでは同じズレが再発します。ズレの種類に応じて、元になった文書のほうを直します。
| ズレの種類 | 例 | 直す文書 |
|---|---|---|
| 振る舞いが違う | キャンセルしてもダイアログが閉じない | spec.md(受け入れ基準を追加する) |
| 値の使い方がばらつく | セクションごとに余白が違う | tokens.json($description に使い分けを書く) |
| 判断の方向が違う | 警告の表現が強すぎて怖い印象になる | concept.md(判断基準を追記する) |
文書を直してから再実装させれば、その修正は以降のすべてのタスクに効きます。全タスクが終わり、すべての受け入れ基準が合格した時点がループの終わりです。
このループで最も頻繁に参照され、AIの出力のブレに最も直結するのが tokens.json です。次で掘り下げます。
W3C DTCG 形式のデザイントークンをAI向けに書く
CSS 変数や単なるカラーコードの羅列と違い、W3C DTCG 形式では次の3つをセットで構造化できます。
$value:値$type:データ型$description:意味・用途の説明
値だけでなく「何のための値か」が同じ場所に書かれているので、LLM が文脈を推論しやすくなります。
記述例:プリミティブとセマンティックの2層構造
AIが最も迷わず使えるのは、プリミティブ(生の値)とセマンティック(役割・意味)の2層をエイリアス参照でつないだ JSON です。安定版 2025.10 の書式で書くと次のようになります。
{
"primitive": {
"color": {
"$type": "color",
"blue": {
"500": { "$value": { "colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066CC" } },
"600": { "$value": { "colorSpace": "srgb", "components": [0, 0.298, 0.6], "hex": "#004C99" } }
},
"neutral": {
"50": { "$value": { "colorSpace": "srgb", "components": [0.9725, 0.9804, 0.9882], "hex": "#F8FAFC" } },
"900": { "$value": { "colorSpace": "srgb", "components": [0.0588, 0.0902, 0.1647], "hex": "#0F172A" } }
},
"red": {
"500": { "$value": { "colorSpace": "srgb", "components": [0.8627, 0.149, 0.149], "hex": "#DC2626" } }
}
},
"spacing": {
"$type": "dimension",
"4": { "$value": { "value": 4, "unit": "px" } },
"16": { "$value": { "value": 16, "unit": "px" } },
"24": { "$value": { "value": 24, "unit": "px" } }
}
},
"semantic": {
"color": {
"$type": "color",
"bg": {
"canvas": {
"$value": "{primitive.color.neutral.50}",
"$description": "アプリケーション全体の背景色。純白(#FFFFFF)ではなく、目の疲れを防ぐためにこれを使用する。"
}
},
"text": {
"primary": {
"$value": "{primitive.color.neutral.900}",
"$description": "見出しや本文のメインテキスト色。背景(bg.canvas)に対してWCAG AAA基準のコントラスト比を確保する。"
}
},
"action": {
"primary": {
"$value": "{primitive.color.blue.500}",
"$description": "画面内で最も重要なCTAボタンやアクティブ状態の要素にのみ使用する。1画面に1〜2箇所まで。"
},
"primaryHover": {
"$value": "{primitive.color.blue.600}",
"$description": "action.primaryのホバー時およびプレス時の状態色。"
},
"destructive": {
"$value": "{primitive.color.red.500}",
"$description": "データの削除やアカウント解約など、取り消せない危険なアクションにのみ使用する。"
}
}
},
"spacing": {
"$type": "dimension",
"componentGap": {
"$value": "{primitive.spacing.16}",
"$description": "カード内部の要素間や、フォームの入力項目同士の標準的な余白。"
},
"sectionGap": {
"$value": "{primitive.spacing.24}",
"$description": "異なる意味を持つコンテンツブロックやセクション間の余白。"
}
}
}
}
読み方のポイントは次のとおりです。
- エイリアス:
{primitive.color.neutral.50}のように波括弧でパスを書くと、別のトークンの値を参照します - 型の継承:グループに書いた
$typeは配下のトークンに引き継がれるので、トークンごとに繰り返す必要はありません - 値の書式:2025.10 では、color は
colorSpaceとcomponentsを持つオブジェクト、dimension はvalueとunitを持つオブジェクトです。"#0066CC"や"16px"のような文字列は旧ドラフトの書式で、安定版では無効です。hexは任意のフォールバックとして併記できます
ちなみに、テキスト色 #0F172A と背景色 #F8FAFC のコントラスト比は約17:1で、$description に書いた WCAG AAA の基準(7:1)を十分に満たします。
AI向けデザイントークン設計の5つのポイント
人間向けのデザインシステムと違い、AIに読み込ませる場合は次の5点を意識します。そうすれば「勝手に変な色を使う」「余白がバラバラになる」といった事故を防げます。
1. $description を「AIへの指示書」として書く
人間向けなら「プライマリカラー」と一言書けば通じますが、AIに対しては「どこで使うべきか(Do)」と「どこで使ってはいけないか(Don’t)」を具体的に書きます。
// 悪い例
"$description": "メインの青色"
// 良い例
"$description": "最も重要なCTAボタンにのみ使用。装飾目的のアイコンや背景には使用禁止。"
2. 必ずセマンティック層を参照させる
生のカラーコード(#0066CC)やプリミティブ名(blue.500)を直接使わせると、AIは文脈を無視して色を選び始めます。AGENTS.md などのコンテキストファイルに、次のような制約を書いておくのが鉄則です。
## デザイントークンの利用ルール
- UI の実装時は必ず `semantic.*` のトークンのみを参照する
- `primitive.*` や、ハードコードされた値(カラーコードや px 値)は一切使わない
3. 命名規則を予測可能にする
LLM はトークンのキー名(パス)からも意味を強く推論します。semantic の下を 種類.対象.役割 のような一般的な UI の命名パターンに揃えると、AIが正しいトークンを選びやすくなります。
- 良い例:
semantic.color.text.disabled、semantic.color.border.focus - 避ける例:
brandColor1、specialBox(意味が読み取れず、誤った推測を招く)
記述例の primaryHover のように、状態を役割名に付けて1つのキーにしているのは、DTCG ではトークンが子を持てないためです。primary をトークンにしたまま primary.hover と階層を切ることはできないので、状態の表し方はどちらか一方に揃えておきます。
4. $type を明記して解釈ミスを防ぐ
DTCG 仕様では、親グループまたは各トークンに $type(color、dimension、fontFamily、shadow、duration など)を指定できます。明記しておけば、AIが CSS やコードに変換するときに単位(px、rem、ms)を取り違えにくくなります。
5. コンポーネント固有トークン(第3層)は最小限にとどめる
大規模なデザインシステムでは button.primary.bg.color のようにコンポーネント単位のトークンまで細かく作ることがあります。しかしAIに読み込ませる場合は、JSON が肥大化してコンテキストウィンドウを圧迫します。どれを使うべきか迷う原因にもなります。
まずはプリミティブとセマンティックの2層に絞り、どうしても例外が必要なコンポーネントだけを別途定義するほうが、一貫性の高いデザインを生成できます。
tokens.json をAIに渡すときのプロンプト例
ポイント2のルールをコンテキストファイルに書けない場面、たとえばチャットで tokens.json を添付して渡すときは、冒頭に次のような短いルール文を添えておくと確実です。
添付の tokens.json は W3C DTCG 形式のデザインシステムです。UI を生成する際は、必ず semantic 配下のトークンを使用し、各トークンの $description に記載された使用条件と制約を厳密に遵守してください。
まとめ
- AIエージェントに意図どおりのデザインを作らせるには、「コンセプトの言語化」と「実現手段の明確化」の両方が要る
- コンセプトはデザイン原則(トレードオフの判断基準)とデザイントークン、コンテキストファイルで文書化する
- ファイルは
concept.md/tokens.json/spec.mdのように役割で分ける - 実現手段は「PRD →
spec.md(受け入れ基準と検証方法)→plan.md→ 1タスクずつ実装と自動検証 → 意匠面のレビュー」のループで回し、検証可能な完了条件まで落とし込む - AIのやり直しには上限を設け、検証コードの変更は人間が承認する
- レビューで見つけたズレはチャットで直さず、原因に応じて
concept.md・tokens.json・spec.mdを直す - デザイントークンは W3C DTCG 形式(2025.10)で書き、
$descriptionをAIへの指示として使い、セマンティック層だけを参照させる
