experience-cms-brand-create

为 Brand Toolkit 创建品牌

根据用户的描述生成一个 Digital Experience 品牌——一个 brand.json 文件——并将其写入 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）、标题→slug 规则，以及工具包会生成哪些内容（避免重复生成）。写入文件之前请先阅读。

交互流程

按顺序执行以下步骤。与用户交互时，应先询问，不要擅自假设；写入前要向用户确认设计方案。如果是单轮、无头或 CLI 运行，无法等待用户回复，则应说明你推断出的选择，并在同一次运行中写入文件，而不是等待无法得到的确认（见步骤 3）。步骤 1–5 会创建品牌文件并完成任务。完成后，可选择执行后续操作——打开 Brand Toolkit 进行预览／编辑；详情见下文的**“完成后”**。此操作并非必需工作流的一部分。

步骤 1：了解品牌意图

了解品牌应呈现怎样的感觉。如果用户已经提供了描述（“深紫色、深色调的高端金融科技品牌”），就从中提取信息；否则，简要询问：

• 名称 — 简短易读的品牌名称（将成为 sfdc_cms:title，在项目中必须唯一）。如果用户没有提供名称，请根据品牌风格提议一个。
• 主色／品牌色 — 标志性的强调色。可以是十六进制值、颜色名称或描述（“Salesforce 蓝”“暖珊瑚色”）。将其转换为 #rrggbb 十六进制值。
• 浅色或深色 — 页面背景整体应呈现浅色还是深色？这会决定 root 和 contrast。
• 个性（可选）— 圆角风格（锐利或圆润）、字体感觉（简洁无衬线、经典衬线、科技感等宽字体）、密度。将这些映射到 borderRadius、fontFamily 选择和 baseFontSize。

如果用户提供了徽标或图片，请取其主色作为 primaryAccent，并根据背景判断浅色或深色。问题控制在一两个以内——其余信息根据品牌风格推断，并在步骤 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：确认设计（如果处于无头模式，则说明情况并继续）

整理一份简短摘要，列出具体选择——名称、四到五种十六进制颜色（注明浅色/深色）、字体，以及任何圆角/尺寸/字重调整。 然后根据用户是否能实际回复来选择后续步骤：

• 交互式运行（用户可以回复）： 展示摘要并请用户确认或调整。在文件写入磁盘前完成迭代，而不是等写入后再处理。
• 单轮 / 无头 / CLI / CI 运行（没有用户可供确认）： 不要等待不可能收到的确认。说明你推断出的选择，并直接进入步骤 4，在同一轮运行中写入文件。

如果无法判断当前属于哪种模式，应优先说明你的选择并继续，而不是停滞不前——写出的品牌方案可供用户调整，总比一直等待好。

步骤 4：写入品牌文件

遵循 references/disk-contract.md：

1. 根据已确认的标题，按照该文档中的精确 slug 规则生成 <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；slug 与标题匹配；没有 手动编写的 *Derived 键；字体可渲染）。

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

上文列出的编号工作流在 Step 5 通过后即告完成——品牌文件就是交付成果，本身即可独立使用。本节是单独的可选操作，不属于工作流步骤，且仅适用于 VS Code。打开 Brand Toolkit 只是为了方便预览和编辑。符合以下任一情况时，请完全跳过此操作（品牌已完成——只需告知用户文件写入位置）：

• 用户未在 VS Code 中工作，或只要品牌文件／要求“只创建文件”／“不要打开任何内容”／处于无头、脚本化或 CI 环境。
• 文件所在位置附近没有 .digitalExperience 项目或 VS Code 工作区（例如，你将文件写入 Salesforce DX 项目之外的独立文件夹）。
• 无法确认当前处于交互式 VS Code 会话中（例如，只有普通 CLI 或没有桌面的 Agent 运行）——不要贸然调用启动器；否则 vscode:// 深层链接可能会冷启动 VS Code 或报错。如不确定，请询问用户是否要打开 Brand Toolkit，而不要擅自假定。

只有当用户在 VS Code 中且希望预览／编辑时，才运行与用户操作系统相匹配的终端命令，打开 Brand Toolkit（Theme Preview）面板。以下三种方式都会打开同一个深层链接——只有操作系统启动器不同；请准确运行其中一种（当前操作系统对应的命令）：

• 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 中打开。你的新品牌“”位于 Local 选项卡中——选中它即可预览并微调；该工具包会计算悬停颜色并编译 CSS，点击 Save 即可保存你的调整。

如果面板之前已经打开，可能需要在 Local 选项卡中刷新，才能显示新品牌。如果没有打开任何内容，则说明此深层链接需要安装并启用 Live Preview 扩展（salesforce.salesforcedx-vscode-ui-preview）——请改为告知用户从命令面板运行 SFDX: Open Theme Preview。

注意事项

• 克隆模板；不要从头编写品牌文件。 手动编写的品牌文件几乎总会遗漏编辑器／编译器／预览功能所需的键，而且失败时不会给出提示（预览显示异常，也没有错误）。
• 编辑字面值，保留引用。 修改 colorScheme 颜色会重新设置所有引用它的按钮／强调色主题——这正是预期效果。将引用替换为字面值会断开这种关联。
• 切勿编写派生颜色。 工具包会在加载时计算 primaryAccentDerived／primaryAccentContrastDerived。请省略它们。
• 只使用可在预览中渲染的字体（系统字体和“Salesforce Sans”）。其他字体名称会静默回退，因此预览结果会产生误导。
• sfdc_cms:title 必须唯一。 标题重复时，工具包的本地列表会将它们合并为一个条目。
• 只写入一个文件。 写入 <slug>.brand.json；让工具包生成 .css 和 activeBrand.json。
• 品牌文件就是交付成果；打开工具包是可选操作。 步骤 1–5 已完整完成任务。只有当用户希望预览／编辑时，才在 VS Code 中运行 Brand Toolkit 启动器（见上文“完成后”）——在无头、CLI、CI 或非项目环境中，绝不要打开 vscode:// 深层链接。如不确定，请跳过，并告知用户文件所在位置。