Brand guide builder

Brand guide builder

Writes brand.md: one page a person can read in three minutes and a tool can parse. It starts from what already exists (the site's CSS, logo files, the user's own words) so the guide describes the real brand, not a wish list.

When to use

• No brand guide yet, or it lives in a PDF nobody opens.
• /brand, on-brand-check, brand-tokens-export, or social-image-templates could not find brand.md.
• Updating the guide after a refresh: "we changed our accent color", "add our new logo".

Steps

1. Check for an existing guide (brand.md, docs/brand.md). If one exists, ask whether to update it or start fresh. Updating keeps every section the user does not mention.

2. Look before asking. Scan what the project already uses, quietly and quickly:

   • Colors: the most frequent hex values in CSS files and the colors in tailwind.config.*. Ignore pure grays used once.
   • Fonts: font-family values and font imports.
   • Logos: files named like logo* in assets/, public/, or brand/. Show what you found as a short list and ask the user to confirm roles ("Is #1F7A5C your main brand color?").

3. Interview, one question at a time, at most eight. Skip any the scan already answered.

   1. In one sentence, what do you make and for whom?
   2. Three words for how you want to come across (for example warm, plain, expert).
   3. Three words you never want to sound like (for example corporate, hype, cute).
   4. Main brand color, and one accent color, if any.
   5. Heading and body fonts. Suggest a safe pair if they have none (a characterful heading font plus a highly readable body font, both free).
   6. Logo files and any rules you already follow (white background only, minimum size).
   7. Words or phrases to avoid, and words you like.
   8. A sentence of copy you love that sounds like you.
4. Fill gaps with good defaults and mark each one (default, change me): ink #1B1F23, paper #FFFFFF, a muted gray with 4.5:1 contrast on white, a type scale of 14, 16, 20, 28, 44 px, spacing of 4, 8, 16, 24, 40 px, radius 4 and 10 px.
5. Check contrast of text colors on their backgrounds. Body text must reach 4.5:1. If the primary color fails as a background for white text, say so and note "large text only" in the guide.
6. Write brand.md using the template below. Keep it to one screen per section. Show the user the color roles and voice section and ask "anything to change?" before you finish.
7. Suggest next steps: brand-tokens-export for CSS and Tailwind, /brand to apply it to a page.

Template

examples/brand.md is a complete example. The structure, in order:

# <Name> brand guide

<One sentence: what you make and for whom.>

## Tokens

```yaml tokens
name: <Name>
color:
  primary: "#......"
  accent: "#......"
  ink: "#1B1F23"
  paper: "#FFFFFF"
  muted: "#......"
font:
  heading: [<Heading font>, Georgia, serif]
  body: [<Body font>, system-ui, sans-serif]
text: { sm: 14px, base: 16px, lg: 20px, xl: 28px, display: 44px }
space: { "1": 4px, "2": 8px, "3": 16px, "4": 24px, "5": 40px }
radius: { sm: 4px, md: 10px }
logo:
  primary: assets/logo.svg
  min-width: 96px
voice:
  avoid: [<word>, <word>]
```

## Colors        (role of each color, and what never to do)
## Type          (where each font goes, casing, one display size)
## Logo          (versions, clear space, minimum size, never list)
## Voice         (three words, do and do not, two example lines)
## Spacing       (the scale and how to use it)

Either style works in the tokens block: one key per line (as in examples/brand.md) or short { inline: maps } like above. Use spaces, never tabs.

Guardrails

• Never invent brand facts. A default is fine only when labeled (default, change me).
• Hex values in the tokens block must be quoted ("#1F7A5C"), or YAML reads them as comments.
• Do not touch logo files or stylesheets. This kit only writes brand.md.
• Ask before overwriting an existing brand.md; show what will change.

Brand guide builder

Get a clear, one-page brand guide in about ten minutes. Claude looks at the colors, fonts, and logos your site already uses, asks you a few short questions, and writes brand.md.

Who it is for: small teams and solo founders who have "a brand" in their heads and scattered hex codes in their CSS, but nothing written down.

Example

You say: "Make a brand guide for us."

Claude finds #1F7A5C used 41 times in your CSS, Inter as your body font, and public/logo.svg. It confirms those with you, asks about your voice ("three words for how you want to come across?"), and writes a brand.md with:

• Color roles (primary for actions, accent sparingly, ink for text) with contrast checked
• Type, logo rules, voice with words to avoid, and a spacing scale
• A tokens block that brand-tokens-export, social-image-templates, on-brand-check, and /brand all read

See examples/brand.md for a finished guide.

What it can access

• Reads your stylesheets, tailwind.config.*, and logo folders (assets/, public/, brand/) to find what you already use.
• Writes one file: brand.md.
• No scripts, no network.

Setup

None. Works in Claude Code, Codex, and Cursor.