codexskills.dev

Brand Guidelines skill for Codex

A brand book anyone can follow without asking. Codex writes brand guidelines where every rule has a value and an example: logo clear space and minimum sizes, color specs with measured accessible pairings, licensed typography with fallbacks, and real application samples. In apply mode it scans the codebase for hard-coded colors, stray fonts and outdated logo files, shows a mapping table, and moves everything onto brand tokens.

  • Design & UX
  • $brand-guidelines
  • 168 lines
  • 2 files
  • ~1,800 tokens
  • MIT
  • Updated

Install

curl -fsSL codexskills.dev/install.sh \  | sh -s -- brand-guidelines

Installs to ~/.agents/skills/brand-guidelines/ for every project on this machine.

Download brand-guidelines.zip

104-line POSIX script. No sudo, no telemetry. Read install.sh

Use it in Codex

Start a prompt with $brand-guidelines, or pick it from /skills. You can also just describe the task: Codex reads the description below and loads the playbook when your request matches.

What Codex reads before loading it

Writes brand guideline documents and applies them to code - logo usage with clear space, minimum sizes and misuse examples, color specs in HEX, RGB, OKLCH and print values, typography with licensing, imagery and iconography rules, voice summary, and application examples - delivered as Markdown or a self-contained HTML brand page. Also audits a codebase or site for off-brand colors, fonts and logo files and maps them to tokens. Use when creating a brand book or style guide, or enforcing an existing brand.

Use it when

  • A company or product needs its first brand book or style guide
  • Brand assets exist but rules for using them are vague or scattered
  • A codebase has drifted from the brand colors, fonts or logo
  • Partners or contractors need a self-serve brand reference

Use something else when

How to check the result

Someone can rebuild a social card or slide using only the guide without a question, and a re-run of the codebase audit finds no hard-coded brand values outside the token file.

The mistake it prevents

Publishing computed CMYK or Pantone conversions as official print values, which then fail to match on press.

~/.agents/skills/brand-guidelines/SKILL.md

--- name: brand-guidelines description: Writes brand guideline documents and applies them to code - logo usage with clear space, minimum sizes and misuse examples, color specs in HEX, RGB,… license: MIT ---

A brand guide is good when someone outside the team can produce an on-brand slide, web page or social image from it alone, and when every rule says what to do, shows it, and gives exact values. Vague adjectives (“bold yet approachable”) are a summary, not a rule.

Two modes

RequestMode
“Write our brand guidelines”, “make a brand book”Author: build the document from existing assets and decisions
“Make the app match the brand”, “find off-brand stuff”Apply: audit the codebase or site and map everything to brand tokens

Author mode

Gather

  • Logo files (all variants), construction or grid files if they exist.
  • Color values as decided (ask which values are authoritative; brand teams often have conflicting hex codes in different files).
  • Fonts with licence type (desktop, web, app embedding) and fallback stacks.
  • Existing materials: website, decks, social posts, app screens (for real examples).
  • Positioning: mission, audience, personality (3 traits), what the brand is not.

Search the repo first: rg --files | rg -i "logo|brand|favicon|\.woff2?$|tokens" and read AGENTS.md for where docs belong.

Document structure

# <Brand> brand guidelines   v1.0  <date>  Owner: <team/email>
1. Brand core       - purpose, audience, personality traits with "this, not that"
2. Logo             - variants, clear space, minimum size, backgrounds, misuse
3. Color            - palette, roles and proportions, accessible pairings
4. Typography       - families, hierarchy, licensing, fallbacks
5. Imagery          - photography, illustration, do/don't
6. Iconography      - style, stroke, grid, library
7. Voice and tone   - summary + link to full voice guide
8. Applications     - web, product UI, slides, social, email, merchandise
9. Assets and contacts - downloads, file naming, who approves exceptions

Logo section

State each rule with a measurable value:

RuleExample spec
VariantsHorizontal (default), stacked, symbol only, wordmark only; each in color, black, white
Clear spaceHeight of the symbol’s inner counter (x) on all sides
Minimum sizeSymbol 20px / 6mm; horizontal lockup 96px / 25mm wide
BackgroundsColor logo on white and brand-50; white logo on brand-700 and darker or on photos with a 40% scrim
MisuseDo not stretch, recolor, outline, add effects, rotate, rearrange lockup, place on busy images, recreate in another font

Show misuse visually: render the real SVG with CSS transforms (scaleX(1.4), filter: drop-shadow) inside a red-bordered “Don’t” frame, so the examples stay true to the current logo file.

Color section

| Name | Role | HEX | RGB | OKLCH | CMYK* | Pantone* |
|---|---|---|---|---|---|---|
| Harbor Blue | Primary, actions, links | #1F4FD8 | 31 79 216 | oklch(0.49 0.22 265) | 86 63 0 15 (unverified) | from print vendor |
| Ink | Text | #14161A | 20 22 26 | ... | ... | ... |
Proportions: neutrals ~70%, primary ~20%, accent ~10%.
Accessible pairings: Harbor Blue on white 6.6:1 (text OK); white on Harbor Blue 6.6:1.

*Print values: screen-to-CMYK and Pantone matches depend on paper and press. Mark them as “to be confirmed by the print vendor or designer with a physical swatch book”; never present a computed conversion as the official print value. Compute contrast for every recommended text pairing ($color-contrast-accessibility) and list only pairings that pass.

Typography section

| Use | Family | Weight | Size / line-height (web) | Fallback |
|---|---|---|---|---|
| Display | Fraunces | 600 | 48/56 | Georgia, serif |
| Body | Inter | 400, 600 | 16/24 | system-ui, sans-serif |
Licence: Inter and Fraunces are SIL OFL (free for web, apps, print). Office fallback for decks: Georgia / Arial.

Check font licences explicitly. Commercial fonts often license desktop, web and app use separately; flag uncertainty for the brand owner or a lawyer rather than assuming.

Imagery and iconography

Describe with concrete criteria: subject matter, lighting (natural, high-key), color treatment, crop (people looking into the layout), forbidden content (staged handshakes, clip art). Icons: library name, grid (24px), stroke (1.5px), corners, fill rules.

Output formats

  • docs/brand/README.md (Markdown, versioned in the repo).
  • Optional brand.html: single file, inline SVG logos, CSS swatches showing values, copy-to-clipboard buttons, print stylesheet. No external dependencies, so it works offline and can be attached to email.
  • Tokens: brand.tokens.json (DTCG format, $value/$type) so code and docs share one source. Hand to $design-tokens for build tooling.

Apply mode

Audit

# colors in use, most frequent first
rg -o --no-filename '#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b' --glob '*.{css,scss,tsx,jsx,ts,vue,svelte,html}' \
  --glob '!**/node_modules/**' | tr 'A-F' 'a-f' | sort | uniq -c | sort -rn | head -40
# fonts declared
rg -n "font-family|fontFamily|@font-face|next/font" --glob '!**/node_modules/**' | head -30
# logo files and inline copies
rg --files | rg -i "logo.*\.(svg|png|jpe?g|webp)$"

Classify each finding:

FindingAction
Exact brand value hard-codedReplace with token
Near-miss (#1f50d9 vs #1f4fd8)Replace with token; note as drift
Off-brand color with a clear role (error red)Keep as a semantic token if the guide allows status colors; else ask
Unknown font or fallback-only stackReplace with brand stack
Outdated or rasterised logoReplace with current SVG from the brand assets

Change values only through tokens; do not mass-replace hex codes across files without showing the user the mapping table first.

Gotchas

  • Brand blue often fails contrast as text. The guide must name an accessible text variant rather than leaving teams to break either the brand or WCAG.
  • Logo files multiply (logo-final-v3.png). The guide names the canonical files and their paths; delete nothing without the owner’s confirmation.
  • Trademark registration, usage notices (TM, (R)) and co-branding with partners are legal questions; say a lawyer should review those sections.
  • Guidelines without real application examples get ignored. Include at least web, slide and social examples using actual brand assets.

Verification

  1. Every color and type rule has an exact value; every text pairing has a measured ratio.
  2. Rebuild one real asset (a social card or slide) using only the guide; note any question the guide could not answer and add the answer.
  3. In apply mode, re-run the audit: no remaining hard-coded brand values outside the token file, and the drift list is empty or explained.

Audit report template

## Brand audit: <repo/site> (<date>)
| Category | Found | On-brand | Drift | Off-brand | Fixed |
|---|---|---|---|---|---|
| Colors | 42 values | 9 | 11 | 22 | 31 via tokens |
| Fonts | 4 families | 2 | - | 2 | 2 |
| Logos | 7 files | 2 | - | 5 outdated | replaced 3, 2 need owner decision |
Open decisions: <list>

Related: create the logo itself with $svg-logo-design; write the full voice guide with $brand-voice.

What the zip contains

SKILL.md plus the interface file below. Nothing runs on install.

agents/openai.yamlgenerated from this page

Gives the Codex app a display name, a one-line description and a starter prompt for this skill.

interface:
  display_name: "Brand Guidelines"
  short_description: "A brand book anyone can follow without asking"
  default_prompt: "$brand-guidelines Write brand guidelines for our startup from the logo and colors in this repo"

About this skill

Written and maintained by the Codex Skills editors to the same editorial standard as every skill here: a selective description, a real workflow, known pitfalls and a way to verify the work. First published , last updated . MIT licensed. Something wrong or out of date? Tell us.

Related skills

All 30 Design & UX skills
esc