@salesforce/afv-skills 1.41.0 → 1.43.0

package/skills/{experience-lwc-accessibility-validate → experience-accessibility-validate}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: experience-lwc-accessibility-validate
+name: experience-accessibility-validate
 description: "Use this skill to determine whether a Lightning Web Component (LWC) is accessible and meets WCAG accessibility guidelines. TRIGGER when the user asks \"is my component accessible?\", \"does my LWC meet accessibility guidelines?\", \"is this component WCAG compliant?\", \"find accessibility problems in this LWC\", \"is this LWC keyboard accessible?\", \"does this component work with a screen reader?\", \"does this component have sufficient color contrast?\", \"check ARIA usage in this LWC\", or \"WCAG 2.2 accessibility check\". Also TRIGGER when the user wants to fix or improve accessibility (a11y, WCAG, ARIA) in an LWC's HTML, JS, or CSS — semantic markup, focus, keyboard nav, contrast, screen-reader labels, WCAG 2.2 SC. Produces `a11y-review.md` with WCAG-cited findings. DO NOT TRIGGER for general LWC generation (use `experience-lwc-generate`) or SLDS visual/design review not focused on accessibility (use `design-systems-slds-validate`)."
 metadata:
   version: "1.1"

package/skills/experience-cms-brand-apply/SKILL.md

@@ -4,6 +4,9 @@ description: "Extracts, retrieves, and applies CMS brand guidelines (voice, tone
 metadata:
   version: "1.0"
   domains: ["Experience"]
+  relatedSkills:
+    - "experience-cms-brand-create"
+    - "experience-content-media-search"
 ---
 
 # Applying CMS Brand
@@ -24,7 +27,7 @@ Universal skill for searching, extracting, and applying CMS brand guidelines to
 
 **DO NOT use this skill when the user wants to:**
 - Search for images or media (use experience-content-media-search skill)
-- Create a new brand from scratch
+- Create a new brand from scratch (use experience-cms-brand-create skill)
 - Edit brand definitions in CMS
 - Generate logos or visual brand assets
 

package/skills/experience-cms-brand-create/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: experience-cms-brand-create
+description: "Author a Salesforce Digital Experience brand (a \"brand.json\") so the VS Code Brand Toolkit can load, edit, and preview it. Use this skill whenever someone wants to: create a brand, make a new brand, generate a brand from a description or a color/logo/mood, add a brand to a project so the Brand Toolkit picks it up, scaffold a brand.json, theme a Digital Experience site, or turn a brand idea (\"a dark luxury brand\", \"match our logo\", \"coral + rounded + friendly\") into a loadable brand. Also use it when the user mentions \"Brand Toolkit\", \"theme manager brand\", \"brand token\", \"colorScheme\", \"primaryAccent\", \".digitalExperience/brands\", \"sfdc_cms:title\", or a \"brand.json\" that should show up in the Brand Toolkit. Do NOT use this skill to apply an existing brand's voice, tone, or guidelines to generated content (use experience-cms-brand-apply), to search Salesforce CMS for existing brands, or to search for images, media, or logos (use experience-content-media-search)."
+metadata:
+  version: "1.0"
+  domains: ["Experience"]
+  relatedSkills:
+    - "experience-cms-brand-apply"
+    - "experience-content-media-search"
+---
+
+# 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.
+2. 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`.
+3. 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.
+4. 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`, …).
+4. Write the brand object (unwrapped body, 2-space pretty-printed) to
+   `<workspaceRoot>/.digitalExperience/brands/<slug>.brand.json`.
+5. 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.

package/skills/experience-cms-brand-create/assets/brand-template.json

@@ -0,0 +1,329 @@
+{
+  "sfdc_cms:title": "REPLACE_WITH_UNIQUE_BRAND_NAME",
+  "baseFontSize": {
+    "value": 16,
+    "unit": "px"
+  },
+  "baseFontFamily": "{!$brand.fontFamily.arial}",
+  "fontSize": {
+    "xSmall": {
+      "value": 0.625,
+      "unit": "rem"
+    },
+    "small": {
+      "value": 0.8125,
+      "unit": "rem"
+    },
+    "medium": {
+      "value": 1,
+      "unit": "rem"
+    },
+    "large": {
+      "value": 1.125,
+      "unit": "rem"
+    },
+    "xLarge": {
+      "value": 1.5,
+      "unit": "rem"
+    },
+    "xxLarge": {
+      "value": 2,
+      "unit": "rem"
+    }
+  },
+  "fontFamily": {
+    "arial": {
+      "name": "Arial",
+      "category": "sans-serif",
+      "fallbacks": ["Helvetica"]
+    },
+    "arialBlack": {
+      "name": "Arial Black",
+      "category": "sans-serif",
+      "fallbacks": ["Gadget"]
+    },
+    "comicSansMs": {
+      "name": "Comic Sans MS",
+      "category": "sans-serif",
+      "fallbacks": ["cursive"]
+    },
+    "calibri": {
+      "name": "Calibri",
+      "category": "sans-serif",
+      "fallbacks": ["Candara", "Segoe", "Segoe UI", "Optima", "Arial"]
+    },
+    "courierNew": {
+      "name": "Courier New",
+      "category": "monospace"
+    },
+    "georgia": {
+      "name": "Georgia",
+      "category": "serif"
+    },
+    "impact": {
+      "name": "Impact",
+      "category": "sans-serif",
+      "fallbacks": ["Charcoal"]
+    },
+    "lucidaConsole": {
+      "name": "Lucida Console",
+      "category": "monospace",
+      "fallbacks": ["Monaco"]
+    },
+    "lucidaSansUnicode": {
+      "name": "Lucida Sans Unicode",
+      "category": "sans-serif",
+      "fallbacks": ["Lucida Grande"]
+    },
+    "palatinoLinotype": {
+      "name": "Palatino Linotype",
+      "category": "serif",
+      "fallbacks": ["Book Antiqua", "Palatino"]
+    },
+    "tahoma": {
+      "name": "Tahoma",
+      "category": "sans-serif",
+      "fallbacks": ["Geneva"]
+    },
+    "timesNewRoman": {
+      "name": "Times New Roman",
+      "category": "serif",
+      "fallbacks": ["Times"]
+    },
+    "trebuchetMs": {
+      "name": "Trebuchet MS",
+      "category": "sans-serif"
+    },
+    "verdana": {
+      "name": "Verdana",
+      "category": "sans-serif",
+      "fallbacks": ["Geneva"]
+    }
+  },
+  "letterSpacing": {
+    "normal": "normal",
+    "wide": {
+      "value": 6,
+      "unit": "px"
+    },
+    "compact": {
+      "value": -1,
+      "unit": "px"
+    }
+  },
+  "fontWeight": {
+    "light": 300,
+    "normal": 400,
+    "bold": 700
+  },
+  "spacing": {
+    "none": {
+      "top": { "value": 0, "unit": "rem" },
+      "bottom": { "value": 0, "unit": "rem" },
+      "left": { "value": 0, "unit": "rem" },
+      "right": { "value": 0, "unit": "rem" }
+    },
+    "xSmall": {
+      "top": { "value": 0.5, "unit": "rem" },
+      "bottom": { "value": 0.5, "unit": "rem" },
+      "left": { "value": 0.5, "unit": "rem" },
+      "right": { "value": 0.5, "unit": "rem" }
+    },
+    "small": {
+      "top": { "value": 0.75, "unit": "rem" },
+      "bottom": { "value": 0.75, "unit": "rem" },
+      "left": { "value": 0.75, "unit": "rem" },
+      "right": { "value": 0.75, "unit": "rem" }
+    },
+    "medium": {
+      "top": { "value": 1, "unit": "rem" },
+      "bottom": { "value": 1, "unit": "rem" },
+      "left": { "value": 1, "unit": "rem" },
+      "right": { "value": 1, "unit": "rem" }
+    },
+    "large": {
+      "top": { "value": 1.5, "unit": "rem" },
+      "bottom": { "value": 1.5, "unit": "rem" },
+      "left": { "value": 1.5, "unit": "rem" },
+      "right": { "value": 1.5, "unit": "rem" }
+    },
+    "xLarge": {
+      "top": { "value": 2, "unit": "rem" },
+      "bottom": { "value": 2, "unit": "rem" },
+      "left": { "value": 2, "unit": "rem" },
+      "right": { "value": 2, "unit": "rem" }
+    }
+  },
+  "colorScheme": {
+    "root": "#ffffff",
+    "contrast": "#000000",
+    "primaryAccent": "#0176d3",
+    "primaryAccentContrast": "#ffffff",
+    "neutral": "#747474"
+  },
+  "borderWeight": {
+    "none": { "value": 0, "unit": "rem" },
+    "thin": { "value": 0.0625, "unit": "rem" },
+    "medium": { "value": 0.125, "unit": "rem" },
+    "thick": { "value": 0.1875, "unit": "rem" }
+  },
+  "borderRadius": {
+    "square": { "value": 0, "unit": "rem" },
+    "round": { "value": 0.25, "unit": "rem" }
+  },
+  "typography": {
+    "heading": {
+      "heading1": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.xxLarge}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "heading2": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.xLarge}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "heading3": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.large}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "heading4": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.medium}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "heading5": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.small}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "heading6": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.xSmall}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      }
+    },
+    "paragraph": {
+      "paragraph1": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.medium}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      },
+      "paragraph2": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.small}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      }
+    },
+    "button": {
+      "button1": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.medium}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      }
+    },
+    "input": {
+      "input1": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.medium}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      }
+    },
+    "label": {
+      "label1": {
+        "fontFamily": "{!$brand.fontFamily.arial}",
+        "fontSize": "{!$brand.fontSize.small}",
+        "lineHeight": 1.5,
+        "fontWeight": "{!$brand.fontWeight.normal}",
+        "letterSpacing": "normal",
+        "textTransform": "none"
+      }
+    }
+  },
+  "buttonStyleGroup": {
+    "primary": {
+      "lightning:buttonColorGroup": {
+        "backgroundColor": "{!$brand.colorScheme.primaryAccent}",
+        "textColor": "{!$brand.colorScheme.primaryAccentContrast}",
+        "borderColor": "{!$brand.colorScheme.primaryAccent}",
+        "backgroundHoverColor": "{!$brand.colorScheme.primaryAccentDerived}",
+        "textHoverColor": "{!$brand.colorScheme.primaryAccentContrastDerived}",
+        "borderHoverColor": "{!$brand.colorScheme.primaryAccentDerived}"
+      },
+      "lightning:borderRadius": "{!$brand.borderRadius.round}",
+      "lightning:borderWidth": "{!$brand.borderWeight.thin}",
+      "lightning:typography": "{!$brand.typography.button.button1}",
+      "lightning:padding": {
+        "top": { "value": 0.5, "unit": "rem" },
+        "bottom": { "value": 0.5, "unit": "rem" },
+        "left": { "value": 1, "unit": "rem" },
+        "right": { "value": 1, "unit": "rem" }
+      }
+    },
+    "secondary": {
+      "lightning:buttonColorGroup": {
+        "backgroundColor": "{!$brand.colorScheme.primaryAccentContrast}",
+        "textColor": "{!$brand.colorScheme.primaryAccent}",
+        "borderColor": "{!$brand.colorScheme.primaryAccent}",
+        "backgroundHoverColor": "{!$brand.colorScheme.primaryAccentContrastDerived}",
+        "textHoverColor": "{!$brand.colorScheme.primaryAccentDerived}",
+        "borderHoverColor": "{!$brand.colorScheme.primaryAccentDerived}"
+      },
+      "lightning:borderRadius": "{!$brand.borderRadius.round}",
+      "lightning:borderWidth": "{!$brand.borderWeight.thin}",
+      "lightning:typography": "{!$brand.typography.button.button1}",
+      "lightning:padding": {
+        "top": { "value": 0.5, "unit": "rem" },
+        "bottom": { "value": 0.5, "unit": "rem" },
+        "left": { "value": 1, "unit": "rem" },
+        "right": { "value": 1, "unit": "rem" }
+      }
+    },
+    "tertiary": {
+      "lightning:buttonColorGroup": {
+        "textColor": "{!$brand.colorScheme.primaryAccent}",
+        "textHoverColor": "{!$brand.colorScheme.primaryAccentDerived}"
+      },
+      "lightning:borderRadius": "{!$brand.borderRadius.round}",
+      "lightning:borderWidth": "{!$brand.borderWeight.none}",
+      "lightning:typography": "{!$brand.typography.button.button1}",
+      "lightning:padding": {
+        "top": { "value": 0.5, "unit": "rem" },
+        "bottom": { "value": 0.5, "unit": "rem" },
+        "left": { "value": 1, "unit": "rem" },
+        "right": { "value": 1, "unit": "rem" }
+      }
+    }
+  }
+}

package/skills/experience-cms-brand-create/references/brand-anatomy.md

@@ -0,0 +1,120 @@
+# Brand anatomy — what to edit and what to leave alone
+
+A brand is one JSON object (the `contentBody` of a CMS brand, saved **unwrapped**
+— no envelope). Its shape is fixed: the Brand Toolkit's editors, the CSS
+compiler, and the preview all expect every top-level section (`colorScheme`,
+`fontFamily`, `fontSize`, `typography`, `buttonStyleGroup`, …) to be present with
+the same keys as the template. **Start from `assets/brand-template.json` and
+change only leaf values** — never drop a section, rename a key, or invent a new
+one. A missing or misspelled key doesn't error; it silently falls back, so the
+preview looks wrong with no explanation.
+
+## The two kinds of values
+
+1. **Literals** — the actual design values. These are the ONLY things you should
+   change to create a new brand:
+   - Colors: `colorScheme.*` (hex strings)
+   - Base font: `baseFontFamily` (a reference — see below), `baseFontSize.value`
+   - Corner rounding: `borderRadius.round.value`
+   - Border thickness: `borderWeight.thin.value`, etc.
+   - Per-role font sizes, weights, transforms inside `typography.*` if you want
+     finer control (usually leave these as references to the shared scale).
+
+2. **References** — strings like `"{!$brand.fontFamily.arial}"` or
+   `"{!$brand.colorScheme.primaryAccent}"`. These are POINTERS into other parts
+   of the same brand. The toolkit resolves them at load time. This is why editing
+   one color (e.g. `colorScheme.primaryAccent`) automatically re-themes every
+   button and accent that points at it. **Keep the references intact** — don't
+   replace a reference with a hard-coded literal, or you break the live-edit link
+   that makes the brand cohesive. To change what a button looks like, change the
+   `colorScheme` color it points to, not the button.
+
+## Colors — `colorScheme` (edit these)
+
+| Key                    | Meaning                                             | Typical |
+| ---------------------- | --------------------------------------------------- | ------- |
+| `root`                 | Page/background color                               | `#ffffff` (light) / a dark color (dark) |
+| `contrast`             | Main text color on `root`                           | `#000000` (light) / `#ffffff` (dark) |
+| `primaryAccent`        | Brand color — primary buttons, links, emphasis      | the brand's signature color |
+| `primaryAccentContrast`| Text/icon color that sits ON `primaryAccent`        | usually `#ffffff` or `#000000`, whichever reads on the accent |
+| `neutral`              | Muted borders, secondary text, dividers             | a mid gray |
+
+**Do NOT hand-author `primaryAccentDerived` or `primaryAccentContrastDerived`.**
+The toolkit computes them from `primaryAccent`/`primaryAccentContrast` on load (a
+darker hover shade + a WCAG-contrast-checked hover text color) and rewrites them.
+The template intentionally OMITS them; leave them out. The `{!...Derived}`
+references inside `buttonStyleGroup` still resolve correctly because the toolkit
+fills the derived values in before resolving.
+
+Contrast matters: `contrast` must be legible on `root`, and `primaryAccentContrast`
+must be legible on `primaryAccent`. When in doubt, pick black or white for the
+contrast colors — whichever has the higher contrast ratio against its background.
+
+Use 6-digit `#rrggbb` hex. (The toolkit normalizes to 8-digit `#rrggbbaa`
+internally; 6-digit in and out is fine.)
+
+## Fonts — `fontFamily` + `baseFontFamily` (choose from the catalog)
+
+`fontFamily` is a **catalog** of available fonts; `baseFontFamily` and every
+`typography.*.fontFamily` is a **reference** into that catalog
+(`"{!$brand.fontFamily.<key>}"`).
+
+To change the brand's font, point `baseFontFamily` (and, if you want headings to
+match, the `typography.heading.*.fontFamily` entries) at a different catalog key.
+Prefer changing `baseFontFamily` and leaving the rest referencing it through the
+scale.
+
+**Preview fidelity — important.** The preview only renders web-safe system fonts
+plus "Salesforce Sans". Any other font name falls back to its generic category
+(sans-serif/serif/monospace), so the preview won't show it. Stick to these
+catalog keys, which all render:
+
+- Sans-serif: `arial`, `verdana`, `tahoma`, `trebuchetMs`, `calibri`,
+  `lucidaSansUnicode`, `arialBlack`, `impact`
+- Serif: `georgia`, `timesNewRoman`, `palatinoLinotype`
+- Monospace: `courierNew`, `lucidaConsole`
+
+If a brand truly needs a custom/brand font, keep it as an aspiration in the brand
+name/description, but pick the closest system font from the list above for the
+`fontFamily` value so the preview is honest. Don't add a new `fontFamily` entry
+with a name that has no web source — it will silently fall back.
+
+## Sizes, weights, spacing, borders
+
+These are shared scales referenced by name throughout `typography` and
+`buttonStyleGroup`. Sensible edits:
+
+- `baseFontSize.value` — the root font size in px (default 16). Bump to 17–18 for
+  a more spacious feel.
+- `borderRadius.round.value` — corner rounding in rem. `0` = sharp/square,
+  `0.25` = default, `0.5`+ = pill-ish.
+- `borderWeight.thin.value` — default border thickness in rem.
+- `fontWeight.normal` — 400 by default; some brands prefer 300 (lighter) or a
+  heavier body.
+
+Leave the `spacing`, `letterSpacing`, and `fontSize` scale keys in place — the
+editors and preview reference them by name. Change the `.value` inside a scale
+entry if you must, but don't remove or rename the entries.
+
+## `typography` and `buttonStyleGroup` — mostly references, edit sparingly
+
+`typography` maps each text role (heading1–6, paragraph1–2, button, input, label)
+to a font family, size, weight, line-height, letter-spacing, and transform — all
+as references into the scales above. `buttonStyleGroup` (primary/secondary/
+tertiary) maps button colors to `colorScheme` references and picks border radius/
+width/typography.
+
+For most brands you should NOT touch these — they inherit correctly from the
+colors and fonts you set above. Edit them only for a deliberate deviation (e.g.
+uppercase buttons via `textTransform: "uppercase"` on `typography.button.button1`,
+or a square primary button via a different `lightning:borderRadius` reference).
+When you do, change the reference target or the literal in place — keep the key
+structure identical to the template.
+
+## The one field that defines identity: `sfdc_cms:title`
+
+`sfdc_cms:title` is the brand's display name AND its identity in the toolkit's
+local list. It **must be unique** among the project's local brands — two brands
+with the same title collapse into one entry in the gallery. Give every generated
+brand a distinct, human-readable title (e.g. `"Sunset Coral"`, `"Acme Dark"`).
+See `references/disk-contract.md` for how the title maps to the on-disk filename.