Vercel が[design.md]を使って、あらゆるシーンでブランドのトーンに合ったデザインを生成する方法

解決すべき二つの主要な課題

• 内部と外部のギャップ: リポジトリ内の product-design スキルには、実際のコンポーネント、クラス名、デザインシステム、プロダクトガイド、公開済みのケーススタディが周囲にあり、抽象的な仕様を既存のオブジェクトに直接適用できます。しかし、提案書、レポート、スタンドアロンの単一ページなど、リポジトリ外のタスクではこれらのコンテキストを読むことができず、モデルが画一的で焦点の定まらない一般的な SaaS ダッシュボードを生成しやすくなります。
• 主観的な説明の限界: 「ページをクリーンに、簡潔に、階層的に」とモデルに伝えるだけでは、実行可能な境界が与えられません。モデルは依然としてフォント、余白、コンポーネント、情報の順序、証拠の関係性を自分で発明する必要があります。異なるモデルは同じ言葉を異なるレイアウトに変換し、さらにはコンテキストに根拠のないデザインルールを追加し続けることさえあります。

Vercel は、その統合プロンプトを拡張し続けるのではなく、リポジトリ外で使用できるデザインファイルをゼロから書き直しました。チームは同時に、七種類の実際のタスクと模擬入力を固定しました。使用状況とパフォーマンスレポート、契約更新提案、ベンチマークレポート、インタラクティブな計画ページ、自社開発か購入かの提案書、セキュリティガバナンスの提案書、プレゼンテーション資料です。プロンプト、データ、レンダリング設定は変更せず、デザインコンテキストのみを変更することで、出力の違いの原因を追跡可能にしました。

最初の契約更新提案の比較では、同じ環境、モデル、データ、ビューポートを使用し、両方とも一回だけ生成し、より良いバージョンを選択することはありませんでした。design.md を読み込んでいないページは、一般的な SaaS ダッシュボードに近いものでした。読み込んだ後は、ページはまず契約更新の推奨事項を示し、ビジネス上の根拠を同じグリッドに配置し、同種の数値を統一された尺度にまとめ、詳細な情報は要約に従属させました。

この比較は、リポジトリ外のエージェントに欠けているものが、ブランドカラーだけではないことを示しています。読者が最初に何を見るか、証拠をどのように組み合わせるか、詳細をどのように後退させるかという判断のための環境も欠けているのです。

システムの三つの柱

エージェントがさまざまなツールや実行環境で Vercel のブランドトーンに合ったページを生成できるようにするため、チームはソリューションを三つの層に分けました。

1. design.md: 主観的な判断と戦略的ガイダンスを担当。
2. 公開の vercel-brand.css: 機械的な視覚的制約を担当。
3. 評価ループ: ルールが機能しているかどうかを検証し、新しい問題を適切なルール層に戻す。

1. design.md: デザイン判断を公開仕様として記述

design.md は、まず読者がページに来て何を理解し、何を決定するのかを問いかけ、次にページが最も強力な根拠に基づく回答と、結論を変える可能性のある制約を示すことを要求します。これは、エージェントが情報を整理し、視覚的な階層を構築し、抑制の効いた具体的な文章を書くことをガイドし、繰り返し発生する生成デザインの悪い習慣に名前を付けます。

同じページで二つの異なる深さの読解をサポートする必要があります。管理者は結論と次のステップをすぐに把握でき、レビュー担当者は証拠、比較、制約に沿って詳細を検証できます。これにより、「シンプル」は詳細を削除することではなく、異なる深さの情報にそれぞれの場所を与えることになります。

このファイルは、ページをまたいで移行できる判断を記述しています。重要な結論をどこに置くか、証拠がテキストとどのように相互に支え合うか、どのコンテンツを補足的な詳細に格下げすべきかなどです。個々のページは依然としてそれぞれの読者のタスクに応じて構成されるべきであり、この仕様がすべてのページを同じテンプレートに押し込むことはありません。

2. 公開 CSS: 繰り返されるメカニズムをプリミティブとして固定化

エージェントはこれまで、フォント、余白、テーブル、統計バー、チャートスタイルを繰り返し発明してきました。Vercel はこれらの決定を、境界のあるクラスとトークンに変換しました。design.md はエージェントに HTML でどの名前を使用するかだけを指示します。スタイルシートはブラウザのレンダリング時に読み込まれるため、モデルは複雑な CSS をすべてコンテキストに読み込む必要がありません。

これにより、二種類の無駄が削減されます。モデルはページごとに基本スタイルを説明するためにコンテキストを再消費する必要がなくなり、ブランドとは無関係な独自の余白、フォント、レイアウトパラメータを自由に作成することも難しくなります。モデルのコンテキストは、読者のタスク、証拠、構成の判断に残すことができます。

3. 評価ループ: 人間の判断と決定的なチェック

各固定プロンプトと模擬入力が一つのシナリオを構成します。現在のファイルを使用してすべてのシナリオを再生成し、一ラウンドとします。完全なラウンドは、Claude Opus 4.8 と Codex with GPT-5.5 でそれぞれ七つのシナリオを実行します。ルールがテーブルにのみ影響する場合、チームは関連するシナリオまたは単一のモデルだけを再テストして、反復サイクルを短縮できます。

コードチェックは、テーブルが利用可能な幅を使用していない、コンテンツがはみ出しているなどの機械的な失敗を検出します。人間は、階層、構成、コピー、ページが読者の質問に答えているかどうかを判断します。Vercel はまた、ローカルレビューアプリを作成し、毎回の実行のプロンプト、入力、モデル設定、design.md のバージョン、完全なページスクリーンショット、フィードバックを保存し、ブラインド A/B テストをサポートします。

design.md のルールは、個人の好みだけで追加することはできません。各ガイドラインは、固定シナリオで明らかになった具体的な問題に由来します。チームは修正を受け入れ、それを適切なルール層にコード化し、影響を受けるシナリオを再実行して、修正が維持され、他の成果物が劣化していないことを確認します。この評価チェーンを通過していないルールはファイルに追加されません。

この三つの層は、モデルが自由に発明できる範囲を狭めると同時に、特定の資料に基づいて判断する余地を残します。判断の変化は design.md に入り、ページをまたいで再利用されるメカニズムは CSS に入り、安定して検出できる問題はコードチェックに入り、評価フレームワーク自体の問題はハーネスに残ります。

実際の効果とデータ

• 構造レベルの変化: design.md を読み込んだ後、モデルは色やフォントを置き換えるだけにとどまらず、読者のタスクに応じてページを再構成し始めました。契約更新提案はまず意思決定の推奨事項を示し、次にビジネス上の根拠を比較可能な構造に配置します。インタラクティブな計画ページは、コントロールを中央に配置し、ユーザーが数値を変更して結果を観察できるようにします。
• 既知の機械的失敗が約 57% 減少: Vercel は三つのデスクトップシナリオを選択し、Codex with GPT-5.5 を design.md を読み込んだ場合と読み込まない場合のそれぞれで一回だけ生成させました。六つのページすべてで最初の結果を保持し、再抽選は行いませんでした。決定的チェッカーは、読み込みなしグループで91件の既知の失敗を検出し、読み込みグループで39件を検出しました。

design.md の構築プロセスでは、完全なラウンド、対象を絞ったチェック、ドライラン、失敗した試行を含め、累計 200 回以上の実行がありました。91 対 39 という結果は、チームが明確に名前を付けてコード化した機械的な問題が再発しにくいことを示しています。

この数値は、既知の機械的な失敗のみをカバーしています。チェッカーは、全体的な構成、情報の価値、美的品質を判断することはできません。また、三つのシナリオと六つのページは、長期的な信頼性を推定するには不十分です。より直接的な限界は、design.md の有無にかかわらず、六つのページのそれぞれに、公開を妨げるような重大な問題が少なくとも一つはまだあることです。

決定的チェッカーは既知の機械的な下限を守り、ブラインド評価と人間によるレビューが引き続き階層、構成、読者にとっての価値を担当します。Vercel はプロセスにモデル審査員による批判の生成を残しつつ、最終的な変更は人間がレビューすることを明確に要求しています。

持続的なメンテナンスと反復の方法

日常的なフィードバック収集

Vercel は Slack で eve ベースの @design-agent を使用しています。同僚がディスカッションスレッドでデザイン批評、代替コピー、アイコン提案、レポートウェブサイトのリクエストを行うと、エージェントは現在の design.md を読み取り、公開スタイルシートを使用してページを構築し、完全なスクリーンショットとデプロイリンクをスレッドに返信します。

毎週、チームは Slack でのディスカッション、GitHub のレビュー、Figma のコメントを集計します。自動化が最初に重複する苦情をグループ化し、人間が既存のシステムがすでにカバーしているかどうかを確認します。ユーザーが未テストの新しいページタイプを要求し始めた場合、そのようなタスクは新しい固定シナリオになります。

精密な振り分けによる修正

• 主観的な判断、情報階層、コピーの問題 → design.md に記述。
• ページをまたいで再利用できるタイポグラフィメカニズム → 公開 CSS クラスまたはトークンとして固定化。
• 明確で測定可能なフォーマット上の欠陥 → 決定的なコードチェックとして記述。
• 評価フレームワーク自体の保存、レンダリング、比較のエラー → ハーネスを修正。
• 単一のモデルでのみ断続的に発生し、他のモデルでは再現しない問題 → 一時的に観察し、一度の異常のためにグローバルな制約を追加しない。

「テーブルが窮屈」という例は、この振り分けがどのように機能するかを示しています。初期の契約更新提案では、ビジネス条件のテーブルが本文と同じ狭い幅に押し込められていました。チームはこれを観察可能な動作に書き換えました。「証拠テーブルは利用可能な全幅を使用する必要があります。」その後、design.md はエージェントが構成時にテーブルにより多くのスペースを積極的に与えるようにし、コードチェックはテーブルが利用可能な幅を無視していないかを測定します。

チームはまた、類似した作業において、各タイプの苦情が発生する頻度を追跡します。修正が有効になると、同様の苦情は減少するはずです。減少しない場合、その原因は、ルールが十分に明確でない、ファイルが正しく読み込まれていない、CSS に表現可能なプリミティブがない、またはこの問題がさらなるテキストではなくコードチェックを必要とする、のいずれかである可能性があります。

一般的なチームが独自のデザインループを構築する方法（6ステップ実践法）

1. 高頻度のシナリオを一つ選ぶ。 繰り返し発生し、実際の読者と実際の入力を持つレポート、提案書、ベンチマークページ、またはミニサイトから始めます。簡潔な受け入れ基準を書き留めます。事実が保持されているか、読者が行うべき決定が明確か、最も頻繁に発生する手動修正が解決されているか。
2. 初期ベースラインを保持する。 デザインコンテキストを追加する前に、モデルを素の状態で一回実行し、プロンプト、入力、設定、スクリーンショットを保存します。実行フレームワークに障害がない場合は、最初の結果を保持し、最も見栄えの良いバージョンを選択しないでください。
3. 日常の不満を観察可能なルールに変換する。 最近のデザインフィードバックを十件集め、「テーブルが窮屈」を「データテーブルは利用可能な全幅を使用する必要がある」に書き換えます。適用範囲、読者のタスク、観察可能な決定、利用可能なプリミティブに基づいて、design.md の最初のバージョンを構成します。
4. スタイルの決定を収束させる。 繰り返されるフォント、余白、レイアウトメカニズムを CSS クラスとトークンとして固定化し、利用可能な名前を Agent に明確に提供します。判断はテキスト仕様に残し、機械的な繰り返しは CSS またはチェッカーに任せます。
5. マッチしたブラインドテスト比較を行う。 同じ入力、モデル、ビューポートを使用して再生成し、ベースラインと新しい結果をシャッフルし、同じ受け入れ基準でレビューします。一回の比較で大きなエラーを明らかにできます。信頼性を判断するには、複数回の独立した初回生成が必要です。
6. 実際の修正に基づいて継続的に反復する。 ユーザーがまだ繰り返し調整している点を確認し、仕様の欠落、CSS で表現できない、機械的チェックとして記述できる、のいずれかを判断します。システムに書き込む前に、もう一度自問します。この修正は現在の出力を超えて一般化できるか？ できない場合は、一時的な調整をグローバルルールに昇格させないでください。一般化可能な修正を最も狭いルール層に送り、次のマッチした比較を行います。

手動ループにメリットがあることが証明されたら、隠れたホールドアウト、モデルとルールのバージョン記録、自動チェック、複数のブラインドレビュー担当者を追加します。毎回の更新で、同じ検証可能な質問に立ち返ります。実際の作業において、同様の苦情は減少したか？