experience-cms-brand-create

Brand Toolkit 用のブランドを作成する

ユーザーの説明から Digital Experience ブランド（brand.json ファイル 1 つ）を生成し、VS Code の Brand Toolkit が検出できる場所に書き込みます。これにより、ユーザーはすぐにブランドを読み込み、編集し、プレビューできます。

ブランドは、デザイントークンをまとめた単一の JSON オブジェクトです。色（colorScheme）、フォントカタログとベースフォント（fontFamily / baseFontFamily）、サイズ／間隔／境界線のスケール、役割ごとの typography、および buttonStyleGroup の定義が含まれます。その大部分は内部参照を含む固定の構造です。ブランドを作成する際は、実績のあるテンプレートを使い、葉の値（色、フォントの選択、境界線の角丸、ベースサイズ）と一意の名前だけを変更してください。

Brand Toolkit が、それ以降のすべてを担います。派生ホバーカラーを計算し、--tm-* CSS をコンパイルし、保存時にアクティブブランドの設定を管理します。あなたの作業は brand.json の作成だけです。

関連項目： このスキルは新しいブランド定義を作成します。既存ブランドのボイス、トーン、ガイドラインを生成コンテンツに適用するには、代わりに experience-cms-brand-apply スキルを使用してください。

参照資料

各ステップに進んだら、その都度参照資料を読んでください。最初にすべてをまとめて読み込まないでください。

• assets/brand-template.json — 複製する、実績のある完全なブランドです。すべてのブランドで、このファイルを出発点にします。コピーしてから、葉の値を変更してください。
• references/brand-anatomy.md — 編集すべきリテラル値と、そのまま残す必要がある参照の見分け方、colorScheme のガイド、フォントカタログとプレビューで実際に描画されるフォント、派生カラーのルールが記載されています。値を編集する前に読んでください。
• references/disk-contract.md — ファイルの保存先（.digitalExperience/brands/<slug>.brand.json）、タイトルからスラッグを決めるルール、ツールキットが生成するもの（自分で生成する必要はありません）が記載されています。ファイルを書き込む前に読んでください。

対話フロー

以下のステップを順番に進めてください。ユーザーと対話できる場合は、決めつける前に質問し、書き込む前にデザインを確認してください。ユーザーが応答できない単一ターン、ヘッドレス、または CLI での実行では、推測した選択内容を伝え、確認を待たずに同じ実行内で書き込んでください（ステップ 3 を参照）。ステップ 1〜5 でブランドファイルを作成し、タスクを完了します。完了後に任意で実行できるアクションとして、プレビューや編集のために Brand Toolkit を開く方法を、以下の**「完了後」**に説明しています。この操作は必須のワークフローには含まれません。

ステップ 1：ブランドの方向性を確認する

ブランドにどのような印象を持たせたいかを確認します。ユーザーがすでに説明（「深い紫を使った、ダークで高級感のあるフィンテックブランド」など）をしている場合は、その内容から要点を読み取ります。説明がない場合は、次の項目を簡潔に尋ねてください。

• 名前 — 短く、人にわかりやすいブランド名（sfdc_cms:title になります。プロジェクト内で一意である必要があります）。名前が提示されなければ、ブランドの雰囲気に合うものを提案します。
• プライマリカラー／ブランドカラー — ブランドを象徴するアクセントカラーです。16 進数、色名、または説明（「Salesforce ブルー」「温かみのあるコーラル」など）を受け付けます。#rrggbb 形式の 16 進数に変換してください。
• ライトかダークか — ページの背景を明るくするか暗くするかです。これにより root と contrast が決まります。
• 個性（任意） — 角の形（シャープか丸みがあるか）、フォントの印象（すっきりしたサンセリフ、クラシックなセリフ、テクニカルな等幅など）、情報密度です。これらを borderRadius、fontFamily の選択、baseFontSize に反映します。

ロゴや画像が提供されている場合は、主要な色をサンプリングして primaryAccent に設定し、背景からライト／ダークを判断してください。質問は 2、3 個にとどめ、残りは雰囲気から推測してステップ 3 で確認します。

ステップ 2：テンプレートからブランドを作成する

1. assets/brand-template.json を読みます。これがベースになります。どのリーフを安全に変更できるか把握するため、references/brand-anatomy.md も読んでください。
2. テンプレートをコピーし、リーフ値のみを上書きします。
   • sfdc_cms:title → 固有のブランド名。
   • colorScheme.root / contrast → ライトまたはダークに応じた値（例：ライトは #ffffff / #000000、ダークは暗い背景色 / #ffffff）。
   • colorScheme.primaryAccent → ブランドカラー。
   • colorScheme.primaryAccentContrast → アクセントカラー上で読みやすいほうの黒または白。
   • colorScheme.neutral → root 上で読みやすい中間グレー。
   • baseFontFamily（および、合わせて typography.heading.*.fontFamily の項目）→ プレビューで実際に表示できるフォントを含むカタログキーへの参照（フォント一覧は anatomy ドキュメントを参照してください）。
   • 任意の個性付け：borderRadius.round.value、borderWeight.thin.value、baseFontSize.value、fontWeight.normal。
3. 次のことはしないでください：*Derived カラーキーの追加、セクションやキーの削除・名前変更、{!$brand....} 参照のリテラルへの置き換え、描画可能なカタログにないフォント名の使用。構造はテンプレートと同一に保つ必要があります。
4. コントラストを確認します。root 上の contrast と、primaryAccent 上の primaryAccentContrast は読みやすくなければなりません。コントラストカラーには黒または白を優先してください。

ステップ 3：デザインを確認する（または、ヘッドレスの場合はその旨を示して続行する）

具体的な選択内容を簡潔にまとめます。名前、4〜5 個の16進数カラーコード（ライト／ダークの注記付き）、フォント、角丸・サイズ・ウェイトの調整内容を記載してください。 その後、ユーザーが実際に回答できるかどうかに応じて進め方を分けます。

• 対話型の実行（ユーザーが返信できる）： まとめを提示し、確認または調整を依頼します。ファイルをディスクに保存してからではなく、この段階で調整を繰り返してください。
• 単一ターン／ヘッドレス／CLI／CI の実行（確認するユーザーがいない）： 届くことのない確認を待つために中断しないでください。推測した選択内容を示し、同じ実行内でファイルを書き込んでステップ 4 に進みます。

どちらのモードか判断できない場合は、進行を止めるよりも、選択内容を示して続行してください。ユーザーが後から調整できるブランド案を文章で残すほうが、何もせず待つより有用です。

ステップ 4：ブランドファイルを書き込む

references/disk-contract.md に従ってください。

1. 同ドキュメントの厳密なスラッグ規則に従い、確定したタイトルから <slug> を導出します。
2. <workspaceRoot>/.digitalExperience/brands/ が存在することを確認します。
3. <slug>.brand.json がすでに存在し、これが新しいブランドの場合は、空いている最小の数値サフィックス（_2、_3、…）を付けます。
4. ブランドオブジェクト（ラッパーなしの本文、2スペースのインデントで整形）を <workspaceRoot>/.digitalExperience/brands/<slug>.brand.json に書き込みます。
5. .css や activeBrand.json は書き込まないでください。保存時にツールキットが生成します。

ステップ 5：ファイルを検証する

references/disk-contract.md の検証チェックリストを実行します（有効な JSON、ラッパーなしの本文、sfdc_cms:title が存在し一意であること、スラッグがタイトルと一致すること、手動作成の *Derived キーがないこと、フォントが描画可能であること）。

完了後（任意）：Brand Toolkit を開いてプレビューおよび編集する

上記の番号付きワークフローは、ステップ 5 に合格した時点で完了です。ブランドファイルが成果物であり、それだけで完成しています。このセクションはワークフローのステップではなく、別途行う任意の操作で、VS Code 内でのみ該当します。Brand Toolkit を開くのは、プレビューや編集を手軽に行うためです。次のいずれかに当てはまる場合は、完全にスキップしてください（ブランドはすでに完成しています。ファイルの保存先をユーザーに伝えるだけです）。

• ユーザーが VS Code で作業していない、またはブランドファイルだけが必要／「作成するだけでいい」／「何も開かないで」／ヘッドレス、スクリプト、CI のコンテキストである。
• ファイルの周辺に .digitalExperience プロジェクトや VS Code ワークスペースがない（例：Salesforce DX プロジェクト外の単独フォルダーに書き込んだ）。
• 対話型の VS Code セッション内にいると判断できない（例：デスクトップ環境のない通常の CLI やエージェント実行）。推測でランチャーを起動しないでください。そうしないと、vscode:// ディープリンクによって VS Code がコールドスタートしたり、エラーになったりする可能性があります。判断に迷う場合は、決めつけずに Brand Toolkit を開くかユーザーに確認してください。

ユーザーが VS Code を使用していて、プレビュー／編集を希望している場合に限り、ユーザーのオペレーティングシステムに対応するターミナルコマンドを実行して、Brand Toolkit（Theme Preview）パネルを開きます。3 つのコマンドはすべて同じディープリンクを開きます。異なるのは OS のランチャーだけです。現在の OS に対応するものを 1 つだけ実行してください。

• macOS： open "vscode://salesforce.salesforcedx-vscode-ui-preview/open-brand-manager"
• Linux： xdg-open "vscode://salesforce.salesforcedx-vscode-ui-preview/open-brand-manager"
• Windows（PowerShell）： Start-Process "vscode://salesforce.salesforcedx-vscode-ui-preview/open-brand-manager"

VS Code はこのリンクを Live Preview（ui-preview）拡張機能に渡し、Brand Toolkit パネルを開きます。その後、ユーザーに次のように伝えてください。

VS Code で Brand Toolkit が開きました。新しいブランド「」は Local タブにあります。選択するとプレビューや微調整ができます。Toolkit はホバーカラーを計算して CSS をコンパイルし、Save をクリックすると調整内容が保存されます。

パネルがすでに開いていた場合は、新しいブランドを表示するために Local タブの更新が必要になることがあります。何も開かない場合、このディープリンクを使用するには Live Preview 拡張機能（salesforce.salesforcedx-vscode-ui-preview）がインストールされ、有効になっている必要があります。その場合は、コマンドパレットから SFDX: Open Theme Preview を実行するようユーザーに伝えてください。

ガードレール

• テンプレートを複製してください。ブランドをゼロから作成しないでください。 手作業で作成したブランドは、エディター／コンパイラー／プレビューが想定するキーをほぼ必ず欠落させます。また、失敗しても通知されないため（プレビューの表示がおかしくなるだけで、エラーは出ません）。
• リテラルを編集し、参照は維持してください。 colorScheme の色を変更すると、それを参照するすべてのボタンやアクセントのテーマが変わります。それが目的です。参照をリテラルに置き換えると、その連携が失われます。
• 派生色は決して設定しないでください。 primaryAccentDerived／primaryAccentContrastDerived は、読み込み時に Toolkit が計算します。これらは省略してください。
• プレビューで表示されるフォントのみ使用してください（システムフォントと「Salesforce Sans」）。それ以外の名前は通知なく代替フォントに置き換わるため、プレビューが実際と異なる表示になります。
• sfdc_cms:title は一意である必要があります。 タイトルが重複すると、Toolkit のローカルリストでは 1 つの項目にまとめられます。
• ファイルは 1 つだけにしてください。 <slug>.brand.json を書き込み、.css と activeBrand.json は Toolkit に生成させてください。
• 成果物はブランドファイルです。Toolkit を開くかどうかは任意です。 ステップ 1～5 でタスクは完全に完了します。ユーザーがプレビュー／編集を希望する場合に限り、VS Code 内で Brand Toolkit ランチャー（上記「完了後」を参照）を実行してください。ヘッドレス、CLI、CI、またはプロジェクト外のコンテキストで vscode:// ディープリンクを起動してはいけません。判断に迷う場合はスキップし、ファイルの保存先をユーザーに伝えてください。