experience-cms-brand-create

Create a Brand for the 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.

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.

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.

Step 1: Gather the brand intent

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.

Step 2: Build the brand from the template

1. Read assets/brand-template.json — this is your base. Read

references/brand-anatomy.md so you know which leaves are safe to change.

1. 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.

1. 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.

1. Sanity-check contrast: contrast on root, and primaryAccentContrast on

primaryAccent, must be legible. Prefer black/white for the contrast colors.

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

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.

Step 4: Write the brand file

Follow references/disk-contract.md:

1. Derive <slug> from the confirmed title using the exact slug rule in that doc.
2. Ensure <workspaceRoot>/.digitalExperience/brands/ exists.
3. If <slug>.brand.json already exists and this is a NEW brand, append the

lowest free numeric suffix (_2, _3, …).

1. Write the brand object (unwrapped body, 2-space pretty-printed) to

<workspaceRoot>/.digitalExperience/brands/<slug>.brand.json.

1. Do NOT write the .css or activeBrand.json — the toolkit generates those on

Save.

Step 5: Validate the file

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).

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

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.

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.