---
name: vitedocs:brand
description: Configure colors, fonts, logo, and favicon for VitePress docs.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - AskUserQuestion
---

## Mode: brand

### Step 1 — Locate docs paths

Check the manifest(s) to find all configured docs folders. If no manifest exists, scan for `.vitepress/config.mjs` files across the known focus paths. Present what was found so the user can confirm before proceeding.

### Step 2 — Shared or per-path branding

If more than one docs path is found, ask:

- header: "Branding scope"
- question: "How should branding be applied across your docs?"
- options:
  - "Same brand across all docs"
  - "Different brand per path — I'll configure each one separately"

If per-path: complete all brand questions for path 1 before moving to path 2 — never ask about two paths simultaneously.

### Step 3 — Brand questions

Ask these once (shared) or once per path (per-path). Always label the header with the path name when in per-path mode so the user knows which repo they're configuring.

**B-Q1 — Primary brand color** (plain text): Ask — "What is the primary brand color? (hex, e.g. `#E63946`). This becomes the link, button, and accent color throughout the docs."

From this single hex value, derive the full VitePress brand palette automatically:
- `--vp-c-brand-1`: the base hex
- `--vp-c-brand-2`: 15% lighter
- `--vp-c-brand-3`: 30% lighter
- `--vp-c-brand-soft`: the hex at 12% opacity (for backgrounds)

Also derive dark mode variants — slightly brighter versions of each to account for dark backgrounds. Present the derived palette to the user before writing anything.

**B-Q2 — Logo:**
- header: "Logo"
- question: "Do you have a logo to use in the docs nav?"
- options:
  - "Yes — I'll provide the path to the file"
  - "Text only — use the site title"
  - "Skip for now"

If yes: ask as plain text — "What is the path to the logo file? (SVG or PNG recommended, e.g. `public/logo.svg`)"

**B-Q3 — Favicon:**
- header: "Favicon"
- question: "Do you have a favicon?"
- options:
  - "Yes — I'll provide the path"
  - "Use the logo as favicon"
  - "Skip for now"

If yes: ask as plain text — "Path to favicon? (e.g. `public/favicon.ico` or `public/favicon.svg`)"

**B-Q4 — Font:**
- header: "Font"
- question: "What font should the docs use?"
- options:
  - "VitePress default (Inter)"
  - "System font stack (no external load)"
  - "Google Font — I'll tell you which"
  - "Custom — I'll provide the CSS import"

If Google Font: ask as plain text — "Which Google Font family? (e.g. `Outfit`, `DM Sans`)"
If custom: ask as plain text — "Paste your @import or @font-face CSS."

**B-Q5 — Dark mode:**
- header: "Dark mode"
- question: "How should dark mode colors work?"
- options:
  - "Auto-derive from brand color (recommended)"
  - "I want to set a custom dark mode accent color"
  - "Use VitePress default dark mode"

If custom: ask as plain text — "What hex color for dark mode accent?"

### Step 4 — Preview palette

Before writing any files, present the full derived palette as a markdown table with inline color chips. Use this format exactly — the `<span>` renders in Claude's markdown output and in VitePress:

| Token | &nbsp; | Light | &nbsp; | Dark |
|---|---|---|---|---|
| `--vp-c-brand-1` | <span style="display:inline-block;width:14px;height:14px;background:#E63946;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#E63946` | <span style="display:inline-block;width:14px;height:14px;background:#F05A64;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F05A64` |
| `--vp-c-brand-2` | <span style="display:inline-block;width:14px;height:14px;background:#EB5E6A;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#EB5E6A` | <span style="display:inline-block;width:14px;height:14px;background:#F47980;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F47980` |
| `--vp-c-brand-3` | <span style="display:inline-block;width:14px;height:14px;background:#F28B93;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F28B93` | <span style="display:inline-block;width:14px;height:14px;background:#F7A0A5;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F7A0A5` |
| `--vp-c-brand-soft` | <span style="display:inline-block;width:14px;height:14px;background:#E6394620;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#E6394620` | <span style="display:inline-block;width:14px;height:14px;background:#F05A6420;border-radius:2px;vertical-align:middle;border:1px solid rgba(0,0,0,.12)"></span> | `#F05A6420` |

Substitute real derived hex values in place of the examples above.

Then ask:

- header: "Palette"
- question: "Does this palette look right?"
- options:
  - "Yes — apply it"
  - "Adjust the base color — I'll give you a new hex"
  - "Manually tweak individual values"

If adjust: take the new hex and re-derive. If manual: ask as plain text for each value to change.

### Step 5 — Write brand files

For each docs path being branded:

**`.vitepress/theme/index.css`** — append the brand variables block. Do not remove existing entries — only add or update the brand vars:

```css
:root {
  --vp-c-brand-1: HEX1;
  --vp-c-brand-2: HEX2;
  --vp-c-brand-3: HEX3;
  --vp-c-brand-soft: HEXSOFT;
  /* FONT_VARS if custom font selected */
}

.dark {
  --vp-c-brand-1: DARK_HEX1;
  --vp-c-brand-2: DARK_HEX2;
  --vp-c-brand-3: DARK_HEX3;
  --vp-c-brand-soft: DARK_HEXSOFT;
}
```

If a Google Font was selected, add the `@import` at the top of the CSS file and set `--vp-font-family-base`.

**`.vitepress/config.mjs`** — add to `themeConfig`:
- `logo` field if a logo was provided
- `favicon` via `head` entry if a favicon was provided

Read the existing config before editing. Make only targeted additions — do not rewrite unrelated sections.

### Step 6 — Summary

```
Branded X docs path(s).

Files updated:
  PATH/.vitepress/theme/index.css  — brand palette + font
  PATH/.vitepress/config.mjs       — logo, favicon

Run the local dev server to preview: npm run dev

Next: run /vitedocs:capture if you have pending screenshots or videos, or /vitedocs:sync to check for code drift.
```