brand-guidelines

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:

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