Brand Guidelines

---
name: brand-guidelines
description: "Extract a brand's visual and verbal identity into an applicable guideline kit — tokens, voice rules, and do/don't pairs — then apply it consistently to any artifact. Use when asked to apply brand guidelines to a document/deck/page, to extract a brand kit from existing materials or a website, to keep AI-produced artifacts on-brand, or to write lightweight brand guidelines for a startup. Produces a compact brand kit (visual tokens + voice rules + application examples) and/or an artifact restyled to it. For a creator's personal voice use creator-brand-kit; for building new UI systems use frontend-design."
---

# Brand Guidelines Skill

Brand consistency dies at the edges — the sales deck someone made at midnight, the AI-generated one-pager in default blue. This skill works both directions: **extract** a usable kit from whatever brand evidence exists (a website, a deck, a logo folder), and **apply** it so any artifact — deck, doc, landing page, social card — looks and sounds like it came from the same company.

## What This Skill Produces

- A **brand kit**: visual tokens (color roles with hex, type choices, spacing/radius feel, logo rules) + **voice rules** (register, vocabulary, banned phrases) + do/don't pairs
- Or an **artifact application**: the given document/deck/page restyled to the kit, with a conformance note

## Required Inputs

Ask for (if not already provided):
- **Mode**: extract a kit, apply an existing kit, or both
- **Brand evidence** (extract mode): the website URL/screenshots, existing decks, the logo files — 2-3 real artifacts beat a mission statement
- **The artifact and its audience** (apply mode): what's being branded and for whom
- **The formality of truth**: is there an official guidelines doc this must defer to, or is this creating the de-facto one?

## Programmatic Helper

Extract mode says "the exact hex values, not memory". Reading them off a
screenshot *is* memory. Read them off the site:

```bash
npx --yes notugly steal example.com        # palette with usage counts, fonts, radii, shadows
npx --yes notugly spec example.com         # the same, as a table you can paste in
npx --yes notugly name "#4f76b6"           # "Hydrangea" — a name a stakeholder can argue with
```

`steal` parses the real stylesheets and returns each colour with **how many
times it is used**, which is what separates a brand colour from a one-off in a
footer. `spec` adds a measured contrast ratio and an inferred role per colour.

For Apply mode, `npx notugly fix "#fg" "#bg"` gives the nearest passing colour
to the brand's own — same hue, same chroma — which is how you honour rule 3
below without abandoning the palette.

Deterministic, zero dependencies, **no model call**. It reads the stylesheets a
browser fetches on first load, so it sees what a browser sees and not what
JavaScript adds later — a partial sample, honestly labelled.

## Extract Method

1. **Mine artifacts, not aspirations.** Pull from what the brand actually ships: the exact hex values (from the site's CSS/screenshots, not memory), the real font stack, how much whitespace they genuinely use, how their headlines are actually written. The "About" page says "bold and human"; the evidence says what that means in practice.
2. **Reduce color to roles with rules.** Primary (and its ONE job), neutrals, functional colors — each with hex, and the usage rule that makes it applicable: "primary on CTAs and key numbers only; never as body backgrounds." A palette without usage rules is a paint chip, not a guideline.
3. **Capture type as decisions.** Families, the weights actually used, the headline pattern (sentence case? title case? length?), body sizing feel. Note the *don'ts* observed: no italics anywhere? never centered body text?
4. **Extract voice as mechanics** (same discipline as style-fingerprint): sentence length feel, person ("we" vs product-name-as-subject), jargon stance, the phrases that recur, the phrases that would never appear. Write 3 do/don't pairs from real copy.
5. **Logo hygiene minimum**: clearspace, minimum size, what backgrounds it sits on, the misuses to ban (stretching, recoloring, effects).

## Apply Method

1. **Token-map the artifact first** — inventory its current colors/fonts/spacings, then map each to the kit's equivalent. Wholesale mapping beats spot-fixing (spot-fixing produces the half-branded artifact, which reads worse than unbranded).
2. **Apply voice, not just paint** — retitle headings in the brand's headline pattern, sweep for banned phrases, adjust register. A perfectly-colored deck in the wrong voice still feels off-brand.
3. **Respect the hierarchy of the artifact** — branding never overrides legibility: contrast checks still bind (measure them — `npx notugly fix` returns the nearest passing colour in the same hue rather than making you abandon the brand colour), dense tables stay functional; the brand's job is recognition, not decoration.
4. **Note conformance honestly** — what was applied, what couldn't be (font unavailable → declared substitute), what needs a human/designer call.

## Output Format

**The kit** (extract mode):
### Brand kit: [company] — extracted from [evidence] on [date]
**Color roles:** [role → hex → the usage rule] · **Type:** [families/weights/patterns + observed don'ts]
**Spacing & shape feel:** [airy/dense · radius/shadow character]
**Logo rules:** [clearspace/min size/backgrounds/banned misuses]
**Voice:** [mechanics + 3 do/don't pairs from real copy]
**Confidence notes:** [what was inferred vs evidenced]

**The application** (apply mode): the restyled artifact + a conformance note (mapped / substituted / needs-designer).

## Quality Checks

- [ ] Every color carries a hex AND a usage rule — no paint-chip palettes
- [ ] Voice rules are mechanics with real-copy examples, not adjectives
- [ ] Extracted values trace to actual artifacts (site CSS, real decks) — nothing from memory of the brand
- [ ] Applications map tokens wholesale, and include the voice pass
- [ ] Contrast/legibility survived the branding — checked, not assumed

## Anti-Patterns

- [ ] Do not extract a brand from its mission statement — mine what they ship, not what they say
- [ ] Do not guess hex values from memory of a famous brand — screenshot/CSS or it's fiction
- [ ] Do not spot-fix ("make the title teal") — half-branded reads worse than unbranded; map wholesale
- [ ] Do not brand at the cost of legibility — a low-contrast on-brand slide fails both jobs
- [ ] Do not ship a kit without usage rules — a palette and a font list is where inconsistency comes FROM