Brand Identity System Build

Most identity projects end with a beautiful presentation and a long gap. The direction is approved, the team celebrates, and then weeks pass while someone translates the deck into tokens, someone else drafts guidelines, and a third person discovers — usually on a real surface, usually late — that the chosen accent color fails contrast on dark backgrounds or the display face collapses at caption sizes.

The gap exists because the translation work is real work: systematic, detail-heavy, and spread across formats nobody enjoys hand-building. Tokens, guideline prose, starter templates, and conformance checks are exactly the kind of structured, repeatable output agents produce well — once a human has made the creative decision they cannot make.

That boundary frames this whole workflow. Agents do not pick the brand. The creative direction — the logo, the palette intent, the typographic voice, the personality — is chosen by humans before this workflow starts. What agents do is turn that approved direction into a system other people can actually use, and stress-test it against real surfaces before launch instead of after.

Use this workflow when an identity direction has been approved and the next deliverables are tokens, guidelines, and launch-ready applications. It fits agency identity engagements, in-house rebrands, sub-brand and product-brand extensions, and any project where the identity has to survive contact with web pages, decks, email clients, and social crops on day one.

Skip it while the direction is still being explored — the multi-direction concept exploration workflow covers that stage — and skip it for one-off campaign visuals that will never need a system behind them.

• An approved rebrand that needs tokens, guidelines, and starter templates before launch.
• An agency that wants identity delivery to ship as a working system, not a PDF.
• A sub-brand that must demonstrably inherit from a master brand's tokens.
• A brand refresh where accessibility and contrast compliance are contractual, not optional.

This runs as a Claude Code dynamic workflow. Including the word workflow in the prompt makes Claude write a JavaScript orchestration script that runs subagents in the background; intermediate outputs — token candidates, guideline drafts, generated HTML applications, violation lists — live in script variables and on disk rather than in Claude's context window. The script can run up to 16 agents concurrently and up to 1,000 in a run, and it is resumable, which matters for a pipeline that pauses for a creative director's review between stages.

The stages run in sequence because each consumes the previous one's approved output: the token agent works from the direction brief, the guideline agent works from the direction plus the approved tokens, the application agents work from tokens plus draft guidelines, and the consistency agent checks the applications against the guidelines. Within a stage there is plenty of parallelism — five application surfaces can be generated by five concurrent agents — but the gates between stages are sequential and human.

Save the working script to .claude/workflows/ in the project (or ~/.claude/workflows/ for personal use) and the pipeline becomes a reusable slash command for the next identity project. Subagent definitions live in .claude/agents/*.md, and /effort ultracode is the explicit way to ask for this orchestration depth when the prompt alone does not trigger it. If the direction brief needs market or competitor context first, /deep-research — the bundled research workflow, which requires WebSearch — can run before this pipeline rather than inside it.

The token agent reads the approved direction — the palette, the typefaces, the spatial feel described in the creative director's notes — and proposes a structured token set: color with explicitly contrast-checked pairings, a type scale, spacing steps, radius values, and motion durations and easings. Every color pairing carries a computed contrast ratio against WCAG 2.2 AA thresholds, so failures surface as data in the token file rather than as surprises in QA.

Tokens are proposals, not decisions. The agent's job is to make the direction precise and to flag where precision exposes a problem: an accent that cannot pass 4.5:1 on dark surfaces, a display size that has no workable line height at mobile widths, a spacing scale that does not divide cleanly into the grid the web team uses. The creative director resolves those flags at the first gate.

{
  "color": {
    "brand": {
      "primary": { "$value": "#1B3A6B", "$type": "color" },
      "accent": { "$value": "#FF6A3D", "$type": "color" },
      "accent-deep": {
        "$value": "#C2421A",
        "$type": "color",
        "$description": "Companion to accent for use on dark surfaces; accent fails 4.5:1 on surface.dark"
      }
    },
    "pairings": [
      { "fg": "color.brand.primary", "bg": "color.surface.light", "contrast": 9.8, "passes": "AA" },
      { "fg": "color.brand.accent", "bg": "color.surface.dark", "contrast": 3.1, "passes": "FAIL" },
      { "fg": "color.brand.accent-deep", "bg": "color.surface.dark", "contrast": 5.6, "passes": "AA" }
    ]
  },
  "type": {
    "scale": { "display": "clamp(2.5rem, 6vw, 4.5rem)", "h1": "2.25rem", "body": "1rem", "caption": "0.875rem" }
  },
  "space": { "unit": "4px", "steps": [4, 8, 12, 16, 24, 32, 48, 64] },
  "radius": { "control": "6px", "card": "12px" },
  "motion": { "fast": "120ms", "base": "200ms", "easing": "cubic-bezier(0.2, 0, 0, 1)" }
}

The guideline agent drafts the brand guidelines from two inputs: the approved direction and the creative director's notes, which usually exist as a loosely structured document of intent, references, and don'ts. The output is a living document in markdown — logo usage and clear space, color rules with the contrast-checked pairings from stage 1, type hierarchy, spacing principles, and voice and tone — written so it can sit in a repository and be updated alongside the tokens it references.

The draft is deliberately conservative about voice. It quotes the creative director's own language for personality and tone rather than inventing brand poetry, and it marks every rule it inferred rather than received with a note for the gate review. A guideline document the creative director did not actually say is worse than a shorter one they did.

# Brand guidelines — <brand name>

## 1. Identity overview
- The idea in one paragraph (from the approved direction, quoted not paraphrased)
- What the identity is not (anti-patterns from the CD's notes)

## 2. Logo
- Primary, secondary, and mark-only lockups
- Clear space (defined in multiples of the x-height)
- Minimum sizes per surface (print, web, favicon, social avatar)
- Misuse: stretching, recoloring, effects, busy backgrounds

## 3. Color
- Core palette with token names
- Approved pairings table (from brand-tokens pairings, with contrast ratios)
- Surfaces: light, dark, photography overlays
- Accessibility floor: WCAG 2.2 AA for text, 3:1 for UI elements

## 4. Typography
- Typefaces and licensing notes
- Hierarchy: display, headings, body, captions, with token references
- Line length and line height rules per size

## 5. Spacing, layout, and radius
## 6. Motion
## 7. Voice and tone
- Personality traits (CD's words), do/don't sentence pairs, channel notes

## 8. Applications
- Links to the proof-of-concept surfaces and starter templates

## Changelog

The application agents generate proof-of-concept applications as code: a web landing page, social post templates at the standard crops, an email header that survives email-client constraints, a slide template, and a business card layout as print-ready HTML. Each surface is built only from the token file and the draft guidelines — no improvised colors, no off-scale sizes — which is exactly what makes them a stress test rather than a mood board.

Building applications as code has a second benefit: they are testable. Playwright can screenshot the web and social surfaces at fixed sizes, axe-core can check the rendered contrast, and the consistency agent in the next stage can read the markup and styles directly instead of guessing from images. The surfaces also become the starter templates the client receives, so the stress test is not throwaway work.

This is the stage where weak systems reveal themselves. A palette that only ever appeared on white in the deck meets a dark hero section. A display face that looked confident at 96 points meets an email subject line. The point of doing this before launch is that the fixes flow back into the tokens and guidelines while they are still cheap to change.

The consistency agent reads every generated application and checks it against the draft guidelines: token usage only, approved pairings only, clear space respected, hierarchy levels used as defined, voice rules followed in any copy. It reports violations with the file, the rule, and the offending value — the same fix-ready format a visual QA report uses.

Violations split into two kinds, and the report keeps them separate. Application errors mean the surface drifted from the system and the surface gets fixed. System gaps mean the surface needed something the system does not provide — a third surface color, a chart palette, a condensed type style — and the gap goes back to the creative director as a decision, not silently patched by the agent.

---
name: brand-consistency-checker
description: Checks generated brand applications against the draft guidelines and token file. Reports violations and system gaps; never edits the applications or the guidelines.
tools: Read, Glob, Grep
---

You check brand applications for consistency with the system.

Rules:
- Read brand/tokens.json and brand/guidelines.md first; they are the only source of truth.
- For each file under brand/applications/, report:
  - Token violations: any color, size, spacing, or radius value not present in tokens.json.
  - Pairing violations: any foreground/background combination not in the approved pairings list.
  - Logo violations: clear space or minimum size breaches, judged from the markup and CSS.
  - Voice violations: copy that breaks a do/don't rule in the voice section.
- Classify every finding as APPLICATION ERROR (the surface should change) or SYSTEM GAP
  (the guidelines or tokens are missing something the surface legitimately needs).
- Cite the file, the rule section, and the offending value for every finding.
- Do not fix anything. Output a markdown report only.

The prompt below is what you paste into Claude Code at the project root, after placing the approved direction and the creative director's notes in a brand/direction/ folder. The word workflow triggers the dynamic-workflow behavior; the explicit gates tell the script where to pause and wait for review.

Run this as a workflow.

Inputs: brand/direction/approved-direction.md and brand/direction/cd-notes.md.
Do not change the creative direction; it is approved and human-owned.

Stage 1 — tokens: a token agent translates the direction into brand/tokens.json
(color with contrast-checked pairings against WCAG 2.2 AA, type scale, spacing,
radius, motion). Flag any pairing that fails AA instead of silently fixing it.
Pause for my review before stage 2.

Stage 2 — guidelines: a guideline agent drafts brand/guidelines.md from the
direction, the CD notes, and the approved tokens, following
guidelines-outline.md. Mark every inferred rule. Pause for my review.

Stage 3 — applications: in parallel, application agents generate
brand/applications/ as code: landing-page.html, social-1x1.html,
social-9x16.html, email-header.html, slide-template.html, business-card.html.
Use only token values and approved pairings.

Stage 4 — consistency: run the brand-consistency-checker agent over every
application and write brand/consistency-report.md, separating application
errors from system gaps.

Finish by listing the open decisions that need the creative director.

Claude writes the actual script when the workflow runs; the sketch below shows the shape so you can recognize a healthy run. The agent(prompt, options) call is the pseudo-API for running a subagent and getting its final answer back; everything between gates stays in variables and files, not in the main conversation.

// Sketch of the orchestration script Claude Code generates for this workflow.
import { readFile, writeFile } from "node:fs/promises"

const direction = await readFile("brand/direction/approved-direction.md", "utf8")
const cdNotes = await readFile("brand/direction/cd-notes.md", "utf8")

// Stage 1: tokens (single agent, then a human gate)
const tokens = await agent(
  "Translate this approved identity direction into a token JSON file with\n" +
    "contrast-checked color pairings (WCAG 2.2 AA), type scale, spacing, radius,\n" +
    "and motion. Flag failing pairings; do not invent new brand colors.\n\n" + direction + "\n\n" + cdNotes,
  { model: "opus" }
)
await writeFile("brand/tokens.json", tokens)
await gate("Creative director reviews brand/tokens.json")

// Stage 2: guidelines draft, then a gate
const guidelines = await agent(
  "Draft brand/guidelines.md per guidelines-outline.md using the approved direction,\n" +
    "the CD notes, and brand/tokens.json. Quote the CD's language for voice; mark inferred rules.",
  { model: "opus" }
)
await writeFile("brand/guidelines.md", guidelines)
await gate("Creative director reviews brand/guidelines.md")

// Stage 3: applications in parallel
const surfaces = ["landing-page", "social-1x1", "social-9x16", "email-header", "slide-template", "business-card"]
await Promise.all(
  surfaces.map((surface) =>
    agent(
      "Build brand/applications/" + surface + ".html using only values from brand/tokens.json\n" +
        "and rules from brand/guidelines.md. No improvised colors or sizes.",
      { model: "sonnet" }
    )
  )
)

// Stage 4: consistency check
const report = await agent(
  "Use the brand-consistency-checker agent rules. Check every file in brand/applications/\n" +
    "against brand/guidelines.md and brand/tokens.json. Separate application errors from system gaps.",
  { model: "sonnet" }
)
await writeFile("brand/consistency-report.md", report)

You need Claude Code installed, a project folder, and the approved direction in writing. Figma MCP helps when the direction lives in Figma frames the agents should read, and Playwright plus axe-core make the application stage verifiable, but the core run needs nothing beyond the files and the prompt.

• Create brand/direction/ and place approved-direction.md and cd-notes.md in it; if the direction lives in Figma, export or connect it via Figma MCP first.
• Copy the agent definitions from the code repository into .claude/agents/ and the outline files into the project root.
• Paste the workflow prompt into Claude Code; the word workflow triggers the background orchestration script.
• Review the token set at the first gate — especially every pairing flagged as failing contrast — before letting stage 2 run.
• Review the guidelines draft, paying attention to rules marked as inferred; rewrite or strike them rather than letting them harden into policy.
• Open the generated applications in a browser, screenshot them at fixed sizes with Playwright, and run axe-core over the web surfaces.
• Read the consistency report; fix application errors, and take system gaps back to the creative director as decisions.
• Save the working script to .claude/workflows/ so the next identity project starts from a command instead of a prompt.

A 40-person startup approved a rebrand built around a warm orange accent that looked excellent in the agency's deck — almost entirely on white. Stage 1 computed the pairings and flagged the accent at 3.1:1 on the new dark surface color, well below the 4.5:1 AA floor for text, and stage 3 made the failure visible: the dark hero section of the proof landing page rendered the accent CTA text as the least readable element on the surface.

The fix was a system decision, not a patch. The creative director approved a darker companion token, accent-deep, defined as the accent's only legal form on dark surfaces, and the guidelines gained a one-line rule with the pairing table to back it. The change cost an hour during the build; discovered after launch across a marketing site, an app, and two campaign templates, the same change had been estimated at roughly two weeks of coordinated updates.

A brand agency that historically shipped guidelines as a PDF four to six weeks after direction approval ran this workflow on three consecutive identity projects. The deliverable changed shape: tokens, a markdown guidelines repository, six starter templates as code, and the consistency report shipped together, two days after direction sign-off instead of three weeks for the first usable artifact.

The agency kept the pipeline as a saved workflow command and the agent definitions in a shared repository. The measurable difference was not only speed: client-side developers started consuming the token file directly in week one, and the agency's revision rounds on guidelines dropped from an average of four to two, because the proof applications had already surfaced the questions clients usually discover months later.

A consumer company launching a sub-brand needed it to feel distinct while demonstrably inheriting from the master brand. The token agent was instructed to express every sub-brand token either as a reference to a master token or as an explicit, named exception with a rationale — and the consistency agent treated any unexplained divergence as a violation.

The first run produced 14 exceptions; the review gate cut them to 5 the creative director could defend to the brand council, including a shifted accent hue and a rounder radius scale. The exception list itself became part of the deliverable: when the brand council asked what exactly the sub-brand changed, the answer was a one-page table generated from the token file rather than a meeting.

The test of the output is whether someone outside the identity team — a developer, a social manager, a deck builder — can use the system without asking the creative director a question the documents should have answered.

Agents in this workflow translate, apply, and check. They do not choose the brand, and they cannot tell you whether the identity is right for the market, distinctive against competitors, or something the founders will still love in a year. Those are creative and strategic judgments that stay with the humans who own them.

The checks have boundaries too. Computed contrast ratios are evidence, not a substitute for looking at the surfaces; voice rules can be checked for pattern violations but not for whether a sentence actually sounds like the brand; and print color is only approximated until a real proof comes back from a printer. Treat the consistency report the way you treat any QA report — as a floor the humans build on, not a ceiling.

• It cannot pick or improve the creative direction; it makes an approved direction usable.
• It cannot judge taste, distinctiveness, or market fit.
• It cannot approve legal use of typefaces, photography, or trademarks.
• Automated contrast and consistency checks are necessary but not sufficient; the creative director's eye remains the final gate.

Save the script to .claude/workflows/ and the agents to .claude/agents/, and identity delivery becomes a repeatable pipeline the studio runs on every project — with the creative decisions exactly where they belong.

1. Humans choose the direction; write it down with the creative director's notes.
2. Token agent translates the direction into tokens with contrast-checked pairings.
3. Gate: the creative director reviews the token set and resolves flagged failures.
4. Guideline agent drafts the living guidelines document, marking inferred rules.
5. Gate: the creative director reviews and edits the guidelines draft.
6. Application agents build proof-of-concept surfaces as code from tokens only.
7. Consistency agent checks every surface and separates application errors from system gaps.
8. Final gate: fix the errors, decide the gaps, and ship tokens, guidelines, and templates together.