experience-cms-brand-create

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a Brand for the Brand Toolkit

为Brand Toolkit创建品牌

Generates a Digital Experience brand — one

brand.json

file — from a user's description, and writes it where the VS Code Brand Toolkit will discover it, so the user can immediately load, edit, and preview the brand.

A brand is a single JSON object of design tokens: colors (

colorScheme

), a font catalog and base font (

fontFamily

baseFontFamily

), size/spacing/border scales, per-role

typography

, and

buttonStyleGroup

definitions. Most of it is fixed structure with internal references; you create a brand by starting from a known-good template and changing only the leaf values (colors, font choice, border radius, base size) plus a unique name.

The Brand Toolkit owns everything downstream: it computes derived hover colors, compiles the

--tm-*

CSS, and manages the active-brand config on Save. Your job is just the

brand.json

Related: This skill creates a new brand definition. To apply an existing brand's voice, tone, and guidelines to generated content, use the
experience-cms-brand-apply
skill instead.

根据用户描述生成Digital Experience 品牌（即一个

brand.json

文件），并将其写入VS Code Brand Toolkit可识别的位置，以便用户立即加载、编辑和预览该品牌。

品牌是一个包含设计令牌的单一JSON对象：颜色（

colorScheme

）、字体目录和基础字体（

fontFamily

baseFontFamily

）、尺寸/间距/边框比例、按角色划分的

typography

以及

buttonStyleGroup

定义。其大部分结构固定且包含内部引用；你需要从一个经过验证的模板开始，仅修改叶子节点的值（颜色、字体选择、边框半径、基础尺寸），并添加一个唯一名称来创建品牌。

Brand Toolkit负责所有下游工作：它会计算派生的悬停颜色、编译

--tm-*

CSS，并在保存时管理活跃品牌配置。你的任务仅需创建

brand.json

文件。

相关说明：此技能用于创建新的品牌定义。若要将现有品牌的语气、风格和准则应用于生成内容，请使用
experience-cms-brand-apply
技能。

Reference material

参考资料

Read each reference when its step arrives — don't inline everything up front:

assets/brand-template.json
— the known-good full brand to clone. This is your starting point for EVERY brand. Copy it, then change leaves.
references/brand-anatomy.md
— which fields are literals you should edit vs references you must leave intact; the
```
colorScheme
```
guide; the font catalog and which fonts actually render in the preview; the derived-colors rule. Read before editing values.
references/disk-contract.md
— exactly where the file goes (
```
.digitalExperience/brands/<slug>.brand.json
```
), the title→slug rule, and what the toolkit generates so you don't. Read before writing the file.

请在对应步骤到来时阅读相关参考资料，不要提前将所有内容内联：

assets/brand-template.json
— 可直接克隆的经过验证的完整品牌模板。这是创建所有品牌的起点。复制模板后仅修改叶子节点的值。
references/brand-anatomy.md
— 说明哪些字段是可编辑的字面量、哪些是必须保留的引用；
```
colorScheme
```
指南；字体目录及可在预览中渲染的字体；派生颜色规则。修改值前请阅读此文档。
references/disk-contract.md
— 文件的具体存放位置（
```
.digitalExperience/brands/<slug>.brand.json
```
）、标题转slug的规则，以及工具包会自动生成的内容（无需你手动创建）。写入文件前请阅读此文档。

Interactive flow

交互流程

Walk these steps in order. When you have an interactive user, ask before assuming and confirm the design back before writing; in a single-turn, headless, or CLI run with no user to answer, state the choices you inferred and write in the same run rather than waiting for a confirmation that cannot arrive (see Step 3). Steps 1–5 create the brand file and complete the task. After they finish, an optional post-completion action — opening the Brand Toolkit to preview/edit — is described in "After completion" below; it is not part of the required workflow.

请按顺序执行以下步骤。如果是与用户交互的场景，做出假设前先询问用户，并在写入前确认设计方案；如果是单轮、无头或CLI运行场景（无用户回应），请说明你推断出的选择并直接执行写入操作（详见步骤3）。步骤1-5用于创建品牌文件并完成任务。完成后，可选择执行后续操作——在VS Code中打开Brand Toolkit进行预览/编辑，具体说明见下文**“完成后操作”**；此操作不属于必需工作流程。

Step 1: Gather the brand intent

步骤1：收集品牌需求

Find out what the brand should feel like. If the user already gave a description ("a dark, premium fintech brand in deep purple"), extract from it; otherwise ask briefly for:

Name — a short, human-readable brand name (becomes
```
sfdc_cms:title
```
, must be unique in the project). If they don't offer one, propose one from the vibe.
Primary/brand color — the signature accent. Accept a hex, a named color, or a description ("Salesforce blue", "warm coral"). Convert to a
```
#rrggbb
```
hex.
Light or dark — does the page background read light or dark? This sets
```
root
```
and
```
contrast
```
.
Personality (optional) — corners (sharp vs rounded), font feel (clean sans, classic serif, techy mono), density. Map these to
```
borderRadius
```
,
```
fontFamily
```
choice, and
```
baseFontSize
```
.

If a logo or image is provided, sample its dominant color for

primaryAccent

and judge light/dark from its background. Keep it to a couple of questions — infer the rest from the vibe and confirm in Step 3.

明确品牌的风格定位。如果用户已提供描述（如“深色高端金融科技品牌，主色调为深紫色”），则从中提取信息；否则简短询问以下内容：

名称 — 简短的人类可读品牌名称（将作为
```
sfdc_cms:title
```
，在项目中必须唯一）。如果用户未提供，请根据风格提议一个名称。
主品牌色 — 标志性强调色。接受十六进制值、命名颜色或描述（如“Salesforce blue”“暖珊瑚色”）。将其转换为
```
#rrggbb
```
格式的十六进制值。
亮色或暗色 — 页面背景应为亮色还是暗色？这将设置
```
root
```
和
```
contrast
```
的值。
风格特征（可选） — 边角（尖锐或圆润）、字体风格（简洁无衬线、经典衬线、科技感等宽字体）、密度。将这些映射到
```
borderRadius
```
、
```
fontFamily
```
选择以及
```
baseFontSize
```
的值。

如果用户提供了标志或图片，提取其主色调作为

primaryAccent

，并根据背景判断亮色/暗色。仅需提问几个问题，其余内容根据风格推断，并在步骤3中确认。

Step 2: Build the brand from the template

步骤2：基于模板构建品牌

Read
```
assets/brand-template.json
```
— this is your base. Read
```
references/brand-anatomy.md
```
so you know which leaves are safe to change.
Copy the template and override ONLY leaf values:
- ```
sfdc_cms:title
```
  → the unique brand name.
- ```
colorScheme.root
```
  /
```
contrast
```
  → per light or dark (e.g. light:
```
#ffffff
```
  /
```
#000000
```
  ; dark: a dark bg /
```
#ffffff
```
  ).
- ```
colorScheme.primaryAccent
```
  → the brand color.
- ```
colorScheme.primaryAccentContrast
```
  → black or white, whichever is legible on the accent.
- ```
colorScheme.neutral
```
  → a mid gray that reads on
```
root
```
  .
- ```
baseFontFamily
```
  (and, to match, the
```
typography.heading.*.fontFamily
```
  entries) → a reference to a catalog key whose font actually renders in the preview (see the anatomy doc's font list).
- Optional personality:
```
borderRadius.round.value
```
  ,
```
borderWeight.thin.value
```
  ,
```
baseFontSize.value
```
  ,
```
fontWeight.normal
```
  .
Do NOT: add
```
*Derived
```
color keys, drop or rename any section/key, replace a
```
{!$brand....}
```
reference with a literal, or use a font name outside the renderable catalog. The structure must stay identical to the template.
Sanity-check contrast:
```
contrast
```
on
```
root
```
, and
```
primaryAccentContrast
```
on
```
primaryAccent
```
, must be legible. Prefer black/white for the contrast colors.

读取
```
assets/brand-template.json
```
— 这是你的基础模板。同时阅读
```
references/brand-anatomy.md
```
，了解哪些叶子节点可安全修改。
复制模板并仅覆盖叶子节点的值：
- ```
sfdc_cms:title
```
  → 唯一的品牌名称。
- ```
colorScheme.root
```
  /
```
contrast
```
  → 根据亮色/暗色设置（例如：亮色：
```
#ffffff
```
  /
```
#000000
```
  ；暗色：深色背景 /
```
#ffffff
```
  ）。
- ```
colorScheme.primaryAccent
```
  → 品牌主色调。
- ```
colorScheme.primaryAccentContrast
```
  → 黑色或白色，选择在主色调上更易辨认的颜色。
- ```
colorScheme.neutral
```
  → 在
```
root
```
  背景上清晰可见的中度灰色。
- ```
baseFontFamily
```
  （以及对应的
```
typography.heading.*.fontFamily
```
  项） → 引用字体目录中可在预览中渲染的字体（详见品牌结构文档中的字体列表）。
- 可选风格设置：
```
borderRadius.round.value
```
  、
```
borderWeight.thin.value
```
  、
```
baseFontSize.value
```
  、
```
fontWeight.normal
```
  。
禁止操作：添加
```
*Derived
```
颜色键、删除或重命名任何章节/键、将
```
{!$brand....}
```
引用替换为字面量、使用字体目录外的字体名称。结构必须与模板完全一致。
检查对比度：
```
contrast
```
在
```
root
```
背景上、
```
primaryAccentContrast
```
在
```
primaryAccent
```
上必须清晰可辨。优先选择黑色/白色作为对比色。

Step 3: Confirm the design (or, if headless, state it and proceed)

步骤3：确认设计方案（无头场景下直接说明选择并执行）

Assemble a compact summary of the concrete choices — name, the four or five hex colors (with a note on light/dark), the font, and any corner/size/weight tweaks. Then branch on whether a user can actually answer:

Interactive run (a user can reply): show the summary and ask the user to confirm or adjust. Iterate here rather than after the file is on disk.
Single-turn / headless / CLI / CI run (no user to confirm): do not pause for a confirmation that cannot arrive. State the choices you inferred and proceed straight to Step 4, writing the file in the same run.

When you can't tell which mode you're in, prefer stating your choices and proceeding over stalling — a written brand the user can adjust beats a hang.

整理具体选择的简要摘要：品牌名称、4-5个十六进制颜色（标注亮色/暗色）、字体、以及边角/尺寸/字重的调整。然后根据是否有用户回应分支处理：

交互场景（用户可回复）：展示摘要并请用户确认或调整。在此阶段迭代，而非文件写入磁盘后再修改。
单轮/无头/CLI/CI场景（无用户确认）：请勿等待无法获得的确认。说明你推断出的选择并直接进入步骤4，在同一轮操作中写入文件。

如果无法判断场景类型，优先说明选择并执行，因为用户可后续调整已写入的品牌文件，总比停滞不前要好。

Step 4: Write the brand file

步骤4：写入品牌文件

references/disk-contract.md

Derive
```
<slug>
```
from the confirmed title using the exact slug rule in that doc.

Ensure

<workspaceRoot>/.digitalExperience/brands/

exists.

If
```
<slug>.brand.json
```
already exists and this is a NEW brand, append the lowest free numeric suffix (
```
_2
```
,
```
_3
```
, …).
Write the brand object (unwrapped body, 2-space pretty-printed) to
```
<workspaceRoot>/.digitalExperience/brands/<slug>.brand.json
```
.
Do NOT write the
```
.css
```
or
```
activeBrand.json
```
— the toolkit generates those on Save.

遵循

references/disk-contract.md

的要求：

根据确认的标题，使用文档中的slug规则生成
```
<slug>
```
。

确保

<workspaceRoot>/.digitalExperience/brands/

目录存在。

如果
```
<slug>.brand.json
```
已存在且当前是创建新品牌，请添加最小可用的数字后缀（
```
_2
```
、
```
_3
```
……）。
将品牌对象（未包裹的主体内容，使用2空格缩进格式化）写入
```
<workspaceRoot>/.digitalExperience/brands/<slug>.brand.json
```
。
请勿写入
```
.css
```
或
```
activeBrand.json
```
— 工具包会在保存时自动生成这些文件。

Step 5: Validate the file

步骤5：验证文件

Run the verification checklist in

references/disk-contract.md

(valid JSON; unwrapped body; present + unique

sfdc_cms:title

; slug matches title; no hand-authored

*Derived

keys; fonts renderable).

执行

references/disk-contract.md

中的验证清单：JSON格式有效；内容未被包裹；存在唯一的

sfdc_cms:title

；slug与标题匹配；无手动编写的

*Derived

键；使用的字体可渲染。

After completion (optional): Open the Brand Toolkit to preview and edit

完成后操作（可选）：打开Brand Toolkit进行预览和编辑

The numbered workflow above is complete once Step 5 passes — the brand file is the deliverable and stands on its own. This section is a separate, optional action, not a workflow step, and only applies inside VS Code. Opening the Brand Toolkit is just a convenience for previewing/editing. Skip it entirely (the brand is already done — just tell the user where the file was written) when any of these hold:

The user isn't working in VS Code, or asked for the brand file only / "just create it" / "don't open anything" / a headless, scripted, or CI context.
There's no
```
.digitalExperience
```
project / VS Code workspace around the file (e.g. you wrote to a standalone folder outside a Salesforce DX project).
You can't tell you're in an interactive VS Code session (e.g. a plain CLI or agent run with no desktop) — don't fire the launcher speculatively; a
```
vscode://
```
deep link can otherwise cold-start or error out. When unsure, ask the user whether to open the Brand Toolkit rather than assuming.

Only when the user is in VS Code and wants to preview/edit, open the Brand Toolkit (Theme Preview) panel by running the terminal command that matches the user's operating system. All three open the SAME deep link — only the OS launcher differs; run exactly one (the one for the current OS):

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 routes the link to the Live Preview (ui-preview) extension, which opens the Brand Toolkit panel. Then tell the user:

The Brand Toolkit is open in VS Code. Your new brand "<title>" is in the Local tab — select it to preview and fine-tune it; the toolkit computes the hover colors and compiles the CSS, and Save persists your tweaks.

If the panel was already open, the new brand may need a refresh in the Local tab to appear. If nothing opens, the deep link requires the Live Preview extension (

salesforce.salesforcedx-vscode-ui-preview

) to be installed and active — fall back to telling the user to run SFDX: Open Theme Preview from the Command Palette.

步骤5通过后，上述编号工作流程即完成 — 品牌文件是交付成果，可独立使用。本节是单独的可选操作，不属于工作流程步骤，仅适用于VS Code环境。打开Brand Toolkit仅为方便预览/编辑。当出现以下任意情况时，请完全跳过此操作（品牌已创建完成，只需告知用户文件存放位置即可）：

用户未在VS Code中工作，或仅要求创建品牌文件/“只创建文件”/“不要打开任何东西”，或处于无头、脚本化或CI环境。
文件所在位置没有
```
.digitalExperience
```
项目/VS Code工作区（例如：你将文件写入了Salesforce DX项目外的独立文件夹）。
无法确定是否处于交互式VS Code会话（例如：纯CLI或代理运行，无桌面环境） — 请勿随意触发启动命令；否则
```
vscode://
```
深度链接可能会冷启动或报错。若不确定，请询问用户是否要打开Brand Toolkit，不要自行假设。

只有当用户在VS Code中且需要预览/编辑时，才根据用户操作系统运行终端命令打开Brand Toolkit（主题预览）面板。三个命令均指向同一个深度链接，仅启动方式因操作系统而异，请运行与当前系统匹配的命令：

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面板。然后告知用户：

Brand Toolkit已在VS Code中打开。你的新品牌“<title>”位于本地标签页中 — 选择它即可预览和微调；工具包会计算悬停颜色并编译CSS，点击保存即可保留你的调整。

如果面板已打开，可能需要在本地标签页中刷新才能显示新品牌。如果没有任何反应，说明深度链接需要安装并激活Live Preview扩展（

salesforce.salesforcedx-vscode-ui-preview

） — 请告知用户从命令面板运行SFDX: Open Theme Preview。

Guardrails

注意事项

Clone the template; don't write a brand from scratch. A hand-built brand almost always drops a key the editors/compiler/preview expect, and the failure is silent (wrong-looking preview, no error).
Edit literals, keep references. Changing a
```
colorScheme
```
color re-themes every button/accent that references it — that's the point. Replacing a reference with a literal breaks that link.
Never author derived colors.
```
primaryAccentDerived
```
/
```
primaryAccentContrastDerived
```
are computed by the toolkit on load. Omit them.
Only use fonts that render in the preview (system fonts + "Salesforce Sans"). Any other name silently falls back, so the preview misleads.
sfdc_cms:title
must be unique. Duplicate titles collapse into one entry in the toolkit's local list.
One file only. Write
```
<slug>.brand.json
```
; let the toolkit produce the
```
.css
```
and
```
activeBrand.json
```
.
The brand file is the deliverable; opening the toolkit is optional. Steps 1–5 fully complete the task. Only run the Brand Toolkit launcher (see "After completion" above) inside VS Code when the user wants to preview/edit — never fire a
```
vscode://
```
deep link in a headless, CLI, CI, or non-project context. When in doubt, skip it and tell the user where the file is.

克隆模板，不要从头编写品牌。手动构建的品牌几乎总会遗漏编辑器/编译器/预览所需的键，且故障无提示（预览显示异常，但无报错）。
修改字面量，保留引用。修改
```
colorScheme
```
颜色会重新设置所有引用该颜色的按钮/强调元素的主题 — 这正是其设计目的。将引用替换为字面量会破坏此关联。
切勿编写派生颜色。
```
primaryAccentDerived
```
/
```
primaryAccentContrastDerived
```
由工具包在加载时计算。请勿手动添加。
仅使用可在预览中渲染的字体（系统字体 + “Salesforce Sans”）。其他字体名称会自动回退，导致预览效果误导用户。
sfdc_cms:title
必须唯一。重复的标题会在工具包的本地列表中合并为一个条目。
仅创建一个文件。写入
```
<slug>.brand.json
```
即可；
```
.css
```
和
```
activeBrand.json
```
由工具包生成。
品牌文件是交付成果，打开工具包是可选操作。步骤1-5已完全完成任务。仅在VS Code环境中且用户需要预览/编辑时，才运行Brand Toolkit启动命令（见上文“完成后操作”） — 切勿在无头、CLI、CI或非项目环境中触发
```
vscode://
```
深度链接。若有疑问，请跳过此操作并告知用户文件位置。