AI エージェントが実際に従うデザイントーン仕様の書き方

使い方のルールを隣に添えないトークン表は、生成エージェントには食べ放題メニューのように読まれる。トーンは予算・ホワイトリスト・デフォルト・対比的な例として書き下す。

問題

デザインシステムは存在するもの ―― トークン、スケール、コンポーネント ―― を文書化しますが、「どれだけ」と「いつ」使うかは感覚に委ねてしまいます。人間のデザイナーはプロダクトを見ることで、その「どれだけ」を吸収します。しかし UI コードを書く生成エージェントはプロダクトを見ません。仕様を読むだけで、仕様が空けたままにしているすべての次元は、エージェントの学習時の事前分布（training prior）によって埋められます。この事前分布は中立ではありません。アクセントを多用し、角を丸め、影で浮き上がらせたダッシュボード UI を過剰に多く含んでいます。そのため、仕様が不十分なトーンは必ず同じ方向へとドリフト（drift）していきます。

ある実プロジェクトで記録された 2 つの失敗が、このパターンを示しています。

• スペーシング。 完全で強制力のあるスペーシングトークンスケールから組み立てたページが、窮屈な仕上がりになりました。どの値も規約に沿った正当なトークンでしたが、値同士の比率が間違っていたのです。修正策は、使い方のセクション ―― 比率のルール、レイヤーごとのデフォルト、目を細めて確認するテスト ―― をトークン表の隣に置くことでした（根底にあるルールは スペーシングの設計思想 が扱っています）。

• カラーとシェイプ。 正しいパレットを渡し、さらに「アクセントは控えめに使う」という文章での指示を添えて作らせたプロトタイプは、実サイトでの 1 ページあたり約 1 回のアクセント使用に対して、約 29 回のアクセント使用で仕上がってきました。しかも、スクエア（角丸なし）を基本とするブランドに対して 114 個もの radius 宣言が入っていました。形容詞は何の役にも立ちませんでした。「控えめに」は反証不可能です ―― エージェントが考える「控えめ」は、ブランドが意図するものの約 29 倍だったのです。

共通する根本原因はこうです。使い方のルールが隣に添えられていないトークン表は、LLM には対等な選択肢が並んだ食べ放題メニューのように読まれます。 accent を bg や surface の隣に並べれば、それらは対等なものとして提示されます。radius トークンを 4 つ並べれば、角を丸めることが当たり前のように提示されます。仕様の沈黙は、許可として読まれるのです。

解決方法

機械可読な制約を書くのと同じやり方でトーンを書き下します。すなわち、数値、閉じたリスト、明示されたデフォルト、そして例です。効果の大きい順に並べた 8 つのルールを示します。

1. 形容詞ではなく数値で

形容詞は検証できませんが、数はできます。仕様に含まれるトーンの形容詞は、すべて測定可能な記述に置き換えるべきです。

NG: "Use the accent color sparingly. Keep the design minimal and clean."

OK: "Accent budget: ≤ 2–3 accent elements visible per viewport; most
     viewports have zero. Max one filled-accent element per viewport.
     Radius default: 0. Box shadows: none on cards/panels."

2 つ目のバージョンなら、エージェントは従うことができ、それに照らして監査することもできます。1 つ目のバージョンは実プロジェクトで試され、先に挙げた約 29 倍のオーバーシュート（超過）を生みました。

2. 雰囲気ではなくホワイトリストで

コストの高い装飾表現 ―― アクセント、radius、シャドウ、大文字化、ディスプレイ書体（display type） ―― のそれぞれについて、使用を許可する役割を正確に列挙します。そしてリストを明示的に閉じます。

Accent is allowed on, and only on:
  - the primary CTA (max 1 per viewport)
  - active/selected/pressed states on small controls
  - focus indicators
  - one emphasized word or value per section
Everything not on this list is neutral by default.

最後の一文が、その重みのほとんどを担っています。「それ以外はすべてデフォルトでニュートラル」という一文がなければ、このリストは境界としてではなく、単なる例として読まれてしまいます。

3. デフォルトを先に、例外を後に述べる

強い事前分布を持つ軸 ―― radius、シャドウ、ホバー時の色 ―― については、トークンを列挙する前にデフォルトを述べなければなりません。さもなければ、トークンのリストそれ自体が事実上のデフォルトになってしまいます。

NG: "Radius tokens: xs (2px), sm (4px), md (6px), lg (8px)."

OK: "Default: square (no radius). Cards, badges, images, inputs,
     pagination carry no radius. Exceptions: dialogs md, mini-badges
     sm, icon-button circles. The tokens exist for the exceptions."

この宣言の完全版については シェイプ言語（shape language） を参照してください。

4. すべてのルールに対比例を添える

エージェントは、原則に従うよりも例を忠実に真似します。NG/OK のペアは、ルールを具体的なコードに結びつけ ―― そして決定的に重要なことに ―― 違反がどのようなものかを見せてくれます。これは文章ではめったにできないことです。

<!-- NG: accent as decoration — orange kicker, orange arrow, amber pill -->
<span class="text-accent uppercase">PICKUP</span>
<a class="hover:text-accent">View all →</a>
<span class="text-amber border-amber rounded-full">12 items</span>

<!-- OK: neutral chrome; accent stays in budget -->
<span class="text-muted uppercase">PICKUP</span>
<a class="link-invert">View all →</a>
<span class="text-muted">12 items</span>

ある失敗パターンは自ら招くものです。あなたの例が、ルールの求める抑制をきちんと体現しているか確認してください。 デモが塗りつぶしのアクセント CTA や 12px の角丸カードを使っている仕様は、ルールではなくデモを教えてしまいます。

最も効果の大きい対比ペアはホバーのルールです。ホバーはページ上のリンクの数だけ倍増するからです。

どちらの列も、静止状態ではまったく同じに見えます。左の列はカーソルが動くたびにアクセントを消費します。右の列は、予算に手をつけることなく同じフィードバックを返します。

5. 使い方のルールを、それが支配するトークン表と併置する

導入部に置かれ、表から離れているルールは、表に負けます ―― クラス名を拾い読みしているエージェントは表を読み、そこから上へ戻ることはありません。予算を示す一文は、それが制約する表の中か、すぐ隣に置きます。そして、例外トークンにあたる行には必ずその但し書きを繰り返します。

| Token    | Use                                                       |
| -------- | --------------------------------------------------------- |
| accent   | Scarce — pressed/selected/focus + rare emphasis.           |
|          | NOT the resting color of links or CTAs (links are white).  |

併置には、プロジェクト単位のバージョンもあります。仕様を、エージェントのコンテキストに必ず含まれる場所 ―― プロジェクトの指示ファイルや、自動で読み込まれるデザインシステムのスキル ―― に置くのです。エージェントが自分で取りに行くかどうかを判断しなければならない wiki ページではいけません。エージェントが一度も読み込まない完璧な仕様は、何も制約しません。

6. 仕様の中で失敗パターンを名指しする

ドリフトがわかっているなら、それを明記します ―― 特定の誤りに対して事前に警告しておくほうが、正しいルールを述べるだけよりもうまく機能します。

Known failure mode: generated output for this brand comes back
orange-heavy and rounded. This brand is neutral-dominant and
square-first. When in doubt: gray, square, flat.

7. 規範となるページと実測した比率に紐づける

そのトーンを体現している実際のページを 1 つか 2 つ指し示し、それらをそのものたらしめている測定済みの事実を述べます。事実は言い換えても生き残りますが、印象は生き残りません。

Canonical pages: / (home), /products/.
Measured ground truth: neutral:accent utility ratio ~10:1 in source;
0–3 accent chrome elements per rendered page; ~9 in 10 components
carry no radius; ~6 box-shadow usages site-wide.

8. 出力を最も変える 5 つのルールを冒頭に置く

長い仕様は、内容の欠如ではなく拾い読みによって破綻します。「絶対に譲れない項目（non-negotiables）」のブロック ―― 生成される出力を最も大きく変えるひと握りのルール ―― を、どの表よりも前、いちばん先頭に置き、10 行以内に収めます。

# Example from one square-first dark-catalog brand — illustrative, not universal
Non-negotiables:
1. Accent ≤ 2–3 elements per viewport; most viewports zero.
2. Hover = neutral inversion, never accent.
3. CTAs use the brand's declared CTA treatment, never raw accent fill.
4. Radius default 0. No pills.
5. No box shadows on cards/panels.

同じパレット、2 つの仕様

下のデモは、同じパレットから 1 つのコンポーネントを 2 回レンダリングしています。左の列は、曖昧な仕様（「モダンで、クリーンに、オレンジは控えめに」）が生み出したものです。右の列は、上で示した予算付きの仕様が生み出すものです。デザインを決めているのは、パレットではなく仕様です。

出力を監査する

トーン仕様は、リリース前の監査 ―― 好みではなく、機械的なチェック ―― とセットになります。

クイックリファレンス

AIがよくやるミス

このセクションは仕様の書き手に向けたものです ―― 以下のミスは仕様を書くときに犯されるもので、他の記事で説明されているドリフトを確実に引き起こします。

• 形容詞に制約させようとする。 「控えめに」は、実測されたケースで約 29 倍のアクセントのオーバーシュートを生みました。数えられないルールは、守られません。

• 存在するものだけを文書化する。 純粋なトークンの一覧は「何をタイプできるか？」には答えますが、「このページはどう見えるべきか？」については沈黙します ―― その沈黙は事前分布によって埋められます。

• 予算を、ドキュメントの別の場所で矛盾させる。 古くなった 1 つの表の行（「accent ―― リンク、CTA、インタラクティブ要素」）は、抑制を説く 1 段落の文章に勝ってしまいます。エージェントはまず表を拾い読みするからです。

• ルールに違反するデモ。 塗りつぶしのアクセントボタンや角丸カードを使ったサンプルコードは、ルールが禁じている美意識を教えてしまいます。例が勝ちます。

• ビルドが誤用を捕まえてくれると思い込む。 トークンの lint は語彙の誤りは捕まえますが、分量の誤りは捕まえません ―― しかも構成によっては、未知のユーティリティは何も出力せずに黙って消えます。予算に必要なのは監査であって、コンパイラではありません。

• 仕様を一度書いたきり、二度と測定しない。 真の基準となる比率（ビューポートあたりのアクセント数、radius を持つコンポーネントの割合）は、実際のプロダクトを監査することで得られます。プロダクトが進化したら、測定し直します。

使い分け

デザインシステムのドキュメントを書く、または刷新するとき

ドキュメントが生成エージェントに読まれるときは、常に 8 つのルールをすべて適用します ―― それは今日では、あらゆるデザインシステムのドキュメントを意味します。単一の変更で最も効果が大きいのは、冒頭に置く non-negotiables ブロックです。

繰り返されるトーンのドリフトを診断するとき

生成された出力が、いつも同じかたちでブランドを外し続けるなら（色が多すぎる、角が丸すぎる、窮屈すぎる）、仕様には明記されていないデフォルトか、予算が設定されていない軸があります。仕様が沈黙している次元を見つけてください。その沈黙こそがバグです。

ページ規模の作業を委譲する前に

プロトタイピングのセッションやページの一括生成は、仕様の穴を一度に多くの面へと増幅させます。まず仕様を締めましょう。ドリフトした 12 ページを監査するほうが、5 つの数値ルールを書くよりもコストがかかります。