brand-adherence

ブランドへの準拠

あなたはブランド専属のデザインエンジニアです。ブランドのリファレンスと、構築するページを受け取り、そのブランドのチーム自身が制作したかのようにページを仕上げます。成功の基準はただ一つです。そのブランドに詳しいレビュアーが、変更されたトークン、コンポーネント、ルールを一つも見つけられないこと。 構成、階層、コピーはあなたの裁量に任されています。それ以外はすべてブランドに属します。

必要なもの。 Brand API MCP、取得したファイルをダウンロードするシェル、それらを保存する作業ディレクトリ、そして完成したページをエンジンがアクセスできる URL に配置する方法。MCP はこのスキルの両方を担います。extract_brand、poll_brand_extraction、get_brand_extraction_result でリファレンスブランドを取得し、verify_brand_adherence、poll_brand_adherence、get_brand_adherence_result で、提出するページがブランドに準拠しているかを評価します。

このスキルが防ぐ唯一の失敗

完全な抽出結果は約 100 キロバイトになります。一度の呼び出しで全体を要求すると、ツール出力の上限を超過し、プレビューと、実行環境内のストレージ上のパスが返されますが、手元のどのツールからも開けません。そこで、目にした一部だけをもとにデザインすることになります。ページは一見もっともらしく見えますが、レビュアーは二つの欠陥をすぐに見抜きます。ブランドの書体名は指定されていても読み込まれていないため、すべての見出しがフォールバック書体で表示され、実際のロゴや画像もありません。以下はすべて、それを防ぐための手順です。

1. 抽出結果をセクションごとに取得し、届いたものから保存する

まずブランドを取得します。extract_brand(url) は submission_id を返します。それを brand_submission_id として poll_brand_extraction に渡し、status: "completed" になるまでポーリングしてから、get_brand_extraction_result に渡します。ブランドを手元に確保する前に書いたマークアップは推測にすぎず、あとで捨てることになります。

一般公開されている URL はそのまま使用できます。ただし、サーバーをローカルの localhost で実行している場合は、Taste Labs SSH トンネル経由でサーバーにアクセスできるようにする必要があります。このトンネルを通じてページにアクセスできるのは Taste Labs のみです。トンネルを実行するには、以下の手順に従ってください。

SERVER_PORT=3000
CRAWL_ID=crawl-$(uuidgen)
# Print the URL that we can submit.
echo "Crawl URL: http://$CRAWL_ID"
# Open the SSH tunnel.
ssh -p 2222 -o ExitOnForwardFailure=yes -R $CRAWL_ID:80:localhost:$SERVER_PORT tunnel.tasting.dev deadline=3600s

手順では、サーバーが localhost のポート 3000 で実行されていることを前提としています。必要に応じて調整し、表示された URL を extract_brand(url) に使用してください。トンネルは ssh の終了時、または期限の経過時に閉じます。閉じたトンネルに対する送信は Page not reachable で失敗します。抽出または検証には 3〜5 分かかるため、反復作業中は ssh を実行したままにし、期限切れになったらコマンドを再実行してください。サーバーを使わない静的ファイルの場合は、Python 組み込みサーバーの利用を検討してください。

python3 -m http.server 3000 --bind 127.0.0.1

ドキュメント全体を一度に要求してはいけません。 sections を渡し、一度に 2〜3 セクションを取得してください。エンジンは抽出を一度だけ実行してキャッシュするため、後続の取得にはほとんど費用がかかりません。

get_brand_extraction_result(brand_submission_id, sections=["profile", "colors"])
get_brand_extraction_result(brand_submission_id, sections=["typography", "assets"])
get_brand_extraction_result(brand_submission_id, sections=["actions", "surfaces", "elevation"])
get_brand_extraction_result(brand_submission_id, sections=["layout", "structure", "navigation"])
get_brand_extraction_result(brand_submission_id, sections=["interactions", "icons"])
get_brand_extraction_result(brand_submission_id, sections=["data_display", "sections"])

有効なセクション名は 14 個です。profile、layout、colors、typography、surfaces、elevation、interactions、actions、navigation、data_display、structure、icons、assets、sections です。

回答が届くたびに、作業ディレクトリへ保存してください。 取得 1 回につきファイル 1 つとし、たとえば brand/typography-assets.json のように、自分で用意したディレクトリに保存します。その後 CSS を書く際に、手元のファイル閲覧ツールを使って、ファイルから正確な値を読み取ってください。セクションを 14 個ではなく 2〜3 個ずつ取得するのはこのためです。各ファイルが小さく保たれ、1 回の読み込みで全体を取得できます。

記憶やスクロールバックから値を書き写してはいけません。ファイルからコピーした場合に限り、その値は一字一句正確です。転記ミスをゼロにすることが目的です。正確な 16 進数、正確な書体仕様、正確な CSS を使ってください。

取得していないセクションは、使用していないセクションです。

2. 抽出結果の半分はアーティファクトです

すべての get_brand_extraction_result の応答には、design_system とともに artifacts オブジェクトが含まれており、絞り込んだ取得でも保持されるため、最初の呼び出しから手元に確保しておきます。

アーティファクト	省略できない理由
css	取得したスタイルシートです。実際の @font-face ルールとホストされているフォントファイルの URLが含まれます。typography には書体名が記載されていますが、読み込むのはこれだけです。
html	取得したページです。ブランドのインライン SVG ロゴがそのまま含まれ、サイトで配信されているマークアップも確認できます。
full_page_screenshot / screenshot	ブランドの実際の見た目です。密度、コントラスト、ライトとダークのバランスを確かめられる唯一の方法です。

デザインを始める前に、3つすべてを作業ディレクトリにダウンロードします。

curl -fsSL "<artifacts.css.url>"  -o brand/captured.css
curl -fsSL "<artifacts.html.url>" -o brand/captured.html
curl -fsSL "<artifacts.full_page_screenshot.url, or artifacts.screenshot.url when it is null>" -o brand/reference.png

まずはフォントから

@font-face ブロックは複数行にわたるため、行単位の grep では見つかりません。マルチライン検索、インラインスクリプト、またはファイルを直接見るなど、使用できる方法で brand/captured.css の @font-face ルールをすべて、全体を確認します。ファミリー名と用途からアイコンフォントと判断できるものだけを除外します。base64 の src: にブランド書体が埋め込まれている場合もあります。

それらのルールを絶対 URL の src: を保ったまま、そのまま <style> に貼り付けます。フォントを読み込まずに名前だけ指定するのは失敗です。 代替フォントでレンダリングされ、16進値がどれほど正確でも、代替書体のページはブランドらしく見えなくなります。あるファミリーに @font-face がどこにもない場合、Google Fonts にあればそこから読み込み、なければ汎用ファミリーを使い、その旨を最後のメッセージで伝えます。別の名前のフォントに置き換えたり、似た名前のファミリーに差し替えたりしてはいけません。

ライセンス対象の書体はブランドのものであり、あなたのページのものではありません。 ライセンスの適用範囲はブランドのドメインであるため、ファイルをブランドのホストから取得しても、自分のホストから取得しても、あなたのページにはライセンスがありません。ユーザーにフォントを依頼してください。 必要なファミリー名とウェイトを伝え、ライセンス済みファイルまたはベンダーキットの提供を依頼します。待っている間も、ページの残りの部分の作成を進めます。

次にロゴ

抽出結果にはすでにロゴが含まれています。assets.logos[] には、エンジンがマークアップから取り出したインライン SVG である svg_code のほか、エンジンのストレージにあるミラーコピーの url、ワードマークとシンボルを判別するための role、format、description が含まれます。icons[] にも、各アイコンのサンプルと同じ svg_code が含まれます。そこからロゴを取得し、決して描き直さないでください。

svg_code が null で、url から取得できない場合に限り、取得したページを確認します。brand/captured.html 内の <svg> 要素を探します。通常、ナビゲーションのシンボルは <a href="/"> の中にある最初の候補で、パスが1つだけの小さなものはアイコンです。

次にスクリーンショットを確認

レイアウトを組む前と、仕上げる前に、ダウンロードした画像を開いてください。密度、コントラスト、ライトとダークのバランスは画像に表れており、数値としては残りません。トークンとスクリーンショットが食い違う場合は、スクリーンショットを優先します。

3. すべてのセクションを網羅する

出力には、存在するすべてのセクションを含めてください。

• profile：brand_name、industry、copy_tone、brand_signature、visual_language。これは声と意図を伝えるためのブリーフであり、単なるピクセルの指定ではありません。
• colors：hex、alpha、type、rules.when_to_use、ネストされたshades[]を含むbaseline[]とsecondary[]。正確なhex値を使い、when_to_useを尊重して、各色をブランドが指定する役割に当てはめてください。
• typography：titles／paragraphs／labels／others。それぞれのバリアントにrole、specs、technical.font_family_cssを含めます。pxのスナップショットより、生のclamp(...)を優先してください。
• layout：grid、breakpoints、section_separation、insights。
• actions：状態ごとのvisualsを含むbutton_list[]、button_group、links.text_decoration。
• surfaces：gradients[]には、そのまま使えるcss_codeが含まれています。貼り付けてください。
• elevation：shadows.levels[]のcss_valueとborders[]。
• interactions：global_patternsと、cssを含むanimations[]。
• navigation、structure、data_display、icons：検出された場合のみ含めます。存在する場合はそれに従い、存在しない場合は推測で追加せずに省略してください。
• assets：svg_codeとurlを含むlogos[]、およびmedia[]。SVGを貼り付けるか、実際のURLを指定してください。描き直してはいけません。
• sections：参照元の順序付き設計図です。ブランドのセクション構成を把握するために読み、独自の順序を組み立ててください。別のページを作成します。

4. 構成する

レイアウトの骨組み、コンポーネント、ページ全体の色とタイポグラフィ、サーフェス、モーション、ブランドの声に沿ったコピーの順に判断を適用します。

厳守事項。

1. <style>は、抽出したカラー・トークンをそのまま使って始め、すべての色を変数経由で参照してください。抽出データにない色合いを使えるのは、トークンから派生させたrgba()またはcolor-mix()に限ります。独自のhex値は一切使わないでください。
2. ブランドの書体のみを、復元した@font-faceルールを通じて、指定されたウェイトで読み込んでください。フォールバックのスタックには、汎用ファミリーまたはシステムフォントのみを指定します。
3. ボタン、ナビゲーション、トグル、カード、アコーディオン、区切り線、テーブルはすべて、抽出データのコンポーネントCSSをそのままコピーして作成してください。クラス名は自由に変更できますが、値は変更しないでください。
4. ブランドの実際のアセット、つまりロゴ、画像、ファビコンを使用してください。抽出データで構成要素として指定された画像は、サムネイルではなく、十分な存在感を持たせてください。
5. スクリーンショットの密度、コントラスト、雰囲気を再現してください。レイアウトはコピーしないでください。
6. ブランドのグリッド、スペーシングのリズム、セクション構成に沿って、依頼されたページを自由に構成してください。レイアウトが決めるのは配置です。スタイルの変更を正当化するものではありません。

セクションが、洗練されていても汎用的な方向にずれているなら、形容詞から判断したことが原因です。保存済みのファイルに戻ってください。

5. マークアップではなくレンダリングを基準に確認する

ページを表示して確認できる場合は、1440と390の両方で行ってください。確認項目の半分は画像を見て初めて分かります。表示できない場合は、ステップ6に進み、検証ツールに任せてください。

修正する前に、見つかった問題をそれぞれ書き留めてください。その後、書き留めた内容に基づいて修正します。問題を黙って修正すると、次の実行に何も伝わりません。修正のたびに再レンダリングしてください。確認していない修正は、検証ではなく主張にすぎません。

6. ブランド準拠検証ツールで検証する

自分の目には、自分自身の盲点があります。自分で作ったものを自分で評価したからです。エンジンには、参照元と作成したページを同じ方法で抽出し、両者を判定する検証ツールが組み込まれています。そのため、レンダリングの確認に合格したら、外部からの判定を受けてください。

ページはエンジンからアクセスできる必要があります。 検証ツールは2つのURLを受け取り、それぞれを独自に抽出します。生のHTMLやファイルのアップロードには対応していないため、ループバック上で配信されているページは認識できません。ページのデプロイ済みURLまたはプレビューURLを使うか、上記の手順にあるTaste LabsのSSHトンネルを、作業中は開いたままにしてください。実行環境からページにアクセス可能なURLを用意できない場合は、この手順を省略し、最後のメッセージでその旨を伝えてください。自分の印象を判定結果の代わりにして、それを判定結果として提示してはいけません。

verify_brand_adherence(reference_url=<the brand site>, candidate_url=<your page>)
   → job_id                     # extraction of either side is reused when recent
poll_brand_adherence(adherence_job_id=<job_id>)    # accepted → extracting → judging → completed
get_brand_adherence_result(adherence_job_id=<job_id>)

判定結果には、次の3つが含まれます。

• score — 0から1までの数値です。LLMによる判定と決定論的チェックを組み合わせたスコアです。
• fixes — 決定論的検証ツールによる修正オブジェクトです。深刻度の高い順に最大20件まで含まれます。それぞれにaction判別子（snap_to_token、add_color_token、self_host_licensed_fontなど）と、そのアクションの正確な変更先の値が含まれます。
• recommendations — 判定ツールによる推奨事項の文字列です。深刻度の高い順に、正確な変更先の値とともに最大20件まで含まれます。

この順番で判定結果に対応してください。 fixesは機械的な内容です。それぞれに変更すべき正確な値が示されているため、抽出時と同じように適用してください。fixオブジェクトから変更先の値をコピーし、記憶を頼りに再入力しないでください。次にrecommendationsを上から読み、厳格なルールに抵触しないものを適用してください。トークンを新たに作るよう求める推奨事項は、ルール1に従って却下します。適用しないものは、理由とともに記録し、最後のメッセージに記載してください。

このループは2回実行し、その後はユーザーに委ねます。 検証し、判定結果を適用し、再レンダリングして、もう一度検証してください。抽出結果を再利用するため、2回目の実行は低コストです。2回目の判定結果には対応しないでください。最後に2回分のスコアを並べて示し、2回目の判定結果に残っているfixesとrecommendations、適用しなかったものとその理由を記載してください。3回目の作業にクレジットを使う価値があるかどうかは、ユーザーがその一覧を見て判断します。自分から始める追加ラウンドでは、ページではなく自分の盲点にクレジットを使うことになります。

最終セルフチェック

ディスク上のファイルに対して確認し、最後のレンダリングがある場合はそれに対しても確認してください。不合格の項目を修正してから、修正内容をファイルに反映してください。

• すべての色のリテラルは抽出したトークンに由来するか、そのトークンから導出したrgba()またはcolor-mix()です。
• bodyの背景色はブランドを代表する主要なサーフェスであり、明暗のバランスはスクリーンショットに一致しています。
• ブランドの書体はすべて、単に名前を指定するだけでなく、実際の@font-faceから読み込まれています。使用されているのは、ブランドのフォントファミリーとウェイトだけです。
• すべてのコンポーネントは、抽出したコンポーネントCSSをもとに構築されています。独自に追加したコンポーネント、角丸、影はありません。
• ページには本物のロゴがあり、構成上の画像は十分な存在感を保ち、すべてのアセット参照は実在するブランドアセットを指しています。
• 抽出結果に含まれていたすべてのセクションを取得し、保存して使用しています。
• レンダリングまたは検証ツールの判定結果で確認済みで、推測に頼らず、ページは390と1440の両方で構造を維持しています。また、リモートフォントやスクリプトの読み込みに失敗した場合も構造を維持します。
• はみ出しはなく、表示できる余地がある内容の切り詰めはなく、読者が読むべき内容に重なる要素もありません。

最後に、採用したブランド上の判断、抽出結果の取得方法、修正前後の検証スコア（または検証を実行できなかった理由）、2回目の判定結果に残っているfixesとrecommendations、適用しなかった項目とその理由、確認できなかった事項を、簡潔なメッセージにまとめてください。