Build a Brand

Tools below are Pika MCP tools, named bare — call each under whatever prefix your session exposes for the Pika MCP.

Take any input — an idea, a website, a list of reference brands, product photos, or an existing brand to refresh — and produce a usable brand identity.

This is a standalone brand-building workflow focused on strategy, identity, design, and copy. The default output is a quick brand deliverable that can be finished in minutes. The full 14-16-page brand guidelines PDF is still available, but only when the user explicitly asks for full depth or chooses to go deeper after the quick pass.

Reference files

Load these only when the relevant phase starts:

• references/brand-directions.md — strategy angle structure and differentiated positioning boards.
• references/brand-identity.md — logo pipeline, symbol rules, concept lanes, and board-copy budgets.
• references/brand-guidelines.md — full guidelines layout, render contract, page structure, and QA rules.
• references/brand-md-template.md — required machine-readable brand.md structure.

Execution Model — Local First, Cloud Only Where Needed

This skill is local-first. Keep deterministic production work on the user's machine:

• Local: workspace setup, downloaded fonts, generated image files after download, image compression, transparent-background cleanup, 16x16 favicon tests, HTML/CSS page builds, PDF rendering, PNG/JPG QA screenshots, logo asset assembly, token/prompt files, and final zip packaging.
• Cloud: paid generation only (gpt-image-2 for symbols, mood images, photography, illustration, and ambient textures) and URL/source research when the brief requires it.

Do not use a cloud PDF renderer or upload PDFs by default. Save quick PDFs, board PDFs, guidelines PDFs, and brand-kit zips to ~/Desktop on Mac, or the project working directory when Desktop is unavailable. Only upload/share via CDN if the user explicitly asks for a hosted file.

PDF asset hygiene: never embed full-size gpt-image-2 PNGs directly in board or guidelines PDFs. This previously produced huge PDFs and ASSET_FETCH_TIMEOUT failures when renderers tried to fetch multi-MB CDN images. Download every generated image, down-raster/downsample it to the slot size, and save a local JPEG target of about 85-180KB before using it in render HTML. Keep transparent PNG only for logo/symbol source assets and favicon/logo export, not for photographic page imagery. Never put a CSS filter:/backdrop-filter: (warm grade, sepia, saturate, brightness, blur) on a photo or background-image in the render HTML — it forces Chromium to rasterize that element to a full-resolution lossless bitmap in the PDF, which cancels out the JPEG step above and re-bloats the file (a warm-graded mood-board page alone took a deck to 70 MB). Bake any color grade into the JPEG itself (in the gpt-image-2 prompt or when you img.save(..., 'JPEG', ...)); drop-shadow() on a transparent logo PNG is the only filter that's safe.

Cost transparency gate

Before any paid MCP call, call identity_balance({verbose: true}) once. Surface the current balance, recent burn rate, and remaining runway, then gate the selected depth with this exact message:

Estimated cost: about 100-300 credits ($1-$3) for quick brand, or about 900-1,500 credits ($9-$15) for full brand book. These ranges cover gpt-image-2 symbol / mood / touchpoint generation plus one targeted regeneration for failed image QA. Quick brand is usually below $5; full brand book exceeds $5, so Reply proceed to continue or cancel to stop.

Do not call any paid MCP tool until the user replies proceed. If the user replies cancel, stop without generating. For non-interactive --quick, --full, or --config callers, require cost_ack=proceed in the config or invocation metadata; if it is absent, stop with the estimate instead of spending credits.

Depth Modes

Choose the depth before any long-running generation or render work:

1. Quick brand (default) — use for first-time founder-kit runs, --quick, creator tutorial flows, batch/subagent calls, or any user who asks for a brand without explicitly asking for a full brand book. Target: 8-12 minutes after usable input, excluding user reply time; no more than 4 generated images unless QA fails; one quick PDF render plus one QA rerender when needed.
2. Full brand book (opt-in) — use only when the user asks for "full", "brand book", "brand guidelines", "14-16-page", "15-page", --full, or when they approve the quick path's "go deeper" upgrade. Target: 25-45 minutes after choices are locked, excluding user reply time.

The quick brand is not a partial or failed full guidelines deck. It is a deliberately smaller deliverable with its own completion criteria. If the selected mode is full, all full-guidelines completion gates still apply.

Mode Selection

Stage 0 — Intake (empty-args menu)

If invoked with no input (no idea, no URL, no photos, no reference brands, and no relevant prior context in the conversation), print this menu verbatim as your full response and stop. Do not call any tool. Wait for the user's next message.

What are we branding? Paste any of:

• An idea / description — e.g. "a streetwear label for cat people"
• A website URL — e.g. "rebrand my existing site at example.com"
• Product photos — drop them in the chat
• Reference brands — e.g. "I want something that feels like Aesop + Patagonia"
• An existing brand to refresh — name + what's working / what isn't

I'll start with a quick brand by default. Say full brand book if you want the deeper 14-16-page guidelines path.

If the user already dropped one of the above, skip the menu and proceed to the selected mode: Quick Step 1 for the default quick brand path, or Step 1 below when full brand book mode is selected.

Stage 0.5 — Quick brand and non-interactive fast lane

Use quick brand mode when the caller passes --quick, omits an explicit full-depth request, or states they are running from CI, a subagent, a batch job, a tutorial recording, or any other non-interactive harness.

Use full brand book mode only when the caller passes --full, sets mode: "full" in config, explicitly asks for full guidelines / brand book depth, or approves the post-quick "go deeper" upgrade.

This section has precedence over the interactive ask/wait instructions below. When quick mode applies, use the quick brand workflow below and do not fall through to the multi-turn full-workflow intake unless a required input is truly missing.

• --config <path> points to a JSON file that pre-bakes intake answers: input, photos, reference_brands, audience, positioning, assets_to_keep, references, mode, chosen_direction, chosen_identity, and export_kit.
• --quick means quick brand mode. Use model judgment for all confirmation gates. Ask only if the original input is missing entirely; otherwise infer reasonable defaults, choose the strongest strategy direction and identity option, and continue.
• --full means full brand book mode. Still use model judgment for confirmation gates in non-interactive runs, but do not cut the required 14-16-page guidelines.
• For --quick or --config, do not stop for confirmation at the deliverable preview, strategy-direction choice, identity-option choice, or brand-kit export gate. Record the assumption inline, then proceed.
• If a required asset is unavailable and cannot be inferred from the input, stop once with a single compact missing-fields list instead of starting a multi-turn Q&A loop.
• In quick mode, deliver the quick brand package defined below; do not describe it as a condensed full guidelines deck.
• In full mode, do not deliver a condensed or partial brand output just because the caller is non-interactive or the run is short on wall-clock time. A condensed 6-page deck is not an acceptable substitute for the required 14-16-page guidelines. If the run is out of wall-clock budget, save a resumable checkpoint with the pages/assets already completed and stop; do not mark the workflow complete.

Autonomous full mode: use this only when an explicit full-depth request is present (--full, mode: "full", or the user asks for a full brand book / full guidelines) and the run already has cost_ack=proceed. In that case, the brief is the spec. Do not wait for the user to pick a board and do not wait for explicit user approval before kit export. Produce all three full deliverables in one run:

1. brand-boards.pdf — generate all three boards and use model judgment to choose the strongest board or hybrid.
2. brand-guidelines.pdf — build the full 14-16-page guidelines from that chosen direction.
3. brand-kit.zip — export the complete kit after the guidelines pass QA.

Record the assumptions and selected direction in brand.md and the final response. If the brief is ambiguous enough that the board choice would be arbitrary, stop once with the missing decision instead of pretending the run is autonomous. Non-interactive clear briefs without explicit full depth stay quick; never promote a batch/tutorial/founder-kit run to full solely because the brief is clear.

Quick Brand Workflow (Default)

Use this workflow for quick brand mode. It is the founder-kit fast lane: fewer choices, fewer generated assets, and a complete starter brand that can feed downstream skills without burning a full first-run quota.

Quick Step 1 — One-pass intake

If there is usable input, do not start a long questionnaire. State the assumptions you are using and ask at most 3 compact questions only when the answer would materially change the brand:

• What does this sell or do?
• Who is it for?
• Should I preserve any existing name, logo, colors, fonts, photos, or references?

For --quick, --config, CI, subagent, batch, or tutorial-recording flows, do not wait for these answers unless the original input is missing entirely. Infer reasonable defaults and record them in the output.

Quick Step 2 — Choose one strongest direction

Do not present 2-3 directions or 3 identity options in quick mode. Pick one strongest strategy and identity with model judgment. The quick strategy must still include:

• Brand name or kept name
• Tagline (8 words max)
• Audience segments: primary segment, secondary segment(s), and one anchor persona
• Positioning statement
• Assets being kept
• Reference brands / inspirations, if provided

Quick Step 3 — Build the starter identity

Create one coherent identity system:

• Logo concept: wordmark + standalone symbol/mark + lockup plan. For a new symbol, use generate_image with provider="gpt-image-2" and ship the approved symbol as transparent PNG sizes, not SVG. Wordmark and lockup assets may be SVG because the wordmark is converted from real font text to outlined paths.
• Palette: 4 core colors with roles and hex values.
• Typography: one characterful display font plus one practical body font, with Google Fonts URLs when available.
• Voice: 3 tone principles, 3 sample lines, and 5 forbidden words/phrases.
• Imagery direction: one short photo/illustration rule set plus no-text image prompt guardrails.
• Starter applications: social avatar/app icon, simple web hero direction, and one practical touchpoint appropriate to the brand type.

Keep image generation capped: one symbol/mark image plus up to 3 mood or touchpoint images. Retry budget: each generated brand image asset gets at most 2 total generation attempts (initial attempt + one targeted regeneration). If QA fails, regenerate only the failed asset. After either cap is exhausted, stop and ask the user which failed asset or layout issue they want to relax instead of continuing to spend credits.

Quick Step 4 — Deliver the quick brand package

The quick deliverable must be complete enough for a creator to use immediately:

[brand-name]-quick-brand/
├── quick-brand.pdf              # 3 pages: cover/strategy, identity system, starter applications
├── brand.md                     # compact machine-readable brand spec
├── README.md                    # how to use the quick brand and when to upgrade
├── logo/                        # symbol, wordmark, and lockup assets that were produced
├── tokens/
│   ├── tokens.css
│   ├── tokens.json
│   └── tailwind.config.snippet.js
└── prompts/
    ├── system-prompt.md
    └── imagery.md

The 3-page quick-brand.pdf page structure:

1. Cover + Strategy — brand name, tagline, positioning, audience segments, anchor persona, references, and hero visual.
2. Identity System — logo system, palette, typography, voice rules, and imagery rules.
3. Starter Applications — social avatar/app icon, web hero/social card direction, one real touchpoint or product-context image, plus 3 brand-specific dos and 3 don'ts.

Render quick-brand.pdf locally with Chrome headless (or WeasyPrint when the HTML is written for it) and inspect PNG/JPG previews before delivery. Quick visual QA must catch clipped text, missing logo/symbol, unreadable type, baked-in text inside generated images, empty placeholders, and obvious layout collisions. If the quick package or zip cannot be produced, stop with a resumable checkpoint listing completed files, missing files, asset paths/URLs, and the exact blocker.

After delivering quick brand, offer the full 14-16-page guidelines as a "go deeper" upgrade. Do not start the full workflow unless the user explicitly asks.

Full Brand Book Workflow (Opt-in)

Use this workflow only for full brand book mode.

Step 1 — Read the Input

Full brand book mode only.

Inputs vary. Before asking any questions, open with a brief agenda so the user knows what's coming:

here's how this works — 4 steps:
1. **Read the input** — i ask a few questions, you answer, i play back what i'm hearing
2. **3 visual brand boards** — i build a 3-page PDF with three complete brand directions, each with its own colors, fonts, photography, voice samples, and logo concept. you pick one or mix elements.
3. **Build the guidelines** — full 14-16-page brand book PDF for the chosen board
4. **Export the brand kit** — once you're happy with the guidelines, i'll bundle a `brand.md` spec + logo assets (symbol PNG sizes, wordmark SVG/PNG, lockup SVG/PNG) + fonts + tokens + AI prompts as a zip you can use anywhere

let's start. [questions follow]

Then ask 3-5 targeted questions in a single message. Adapt to the input type:

If they dropped an idea / description:

• What does this brand sell or do? (product / service / app / community / something else)
• Who is this for — describe the 2-3 audience segments this brand should serve, plus one vivid anchor persona inside the primary segment
• Why does this exist? what's broken about the alternatives, or what feeling are you trying to deliver?
• Do you have a name in mind, or is naming part of what you want help with?

If they dropped a website / existing brand URL:

• Are we refreshing this brand or rebuilding it from scratch?
• What's working about it today, and what isn't?
• Who's the current customer vs. who you wish were the customer?

If they dropped product photos:

• Ask how the product is made, who has bought or used it, price point, current sales/channel context, and any direction they already have in mind.
• Keep the output scoped to guidelines and a brand kit, not a commerce launch.

If they dropped reference brands only ("I want a brand that feels like Aesop + Patagonia"):

• What's the product, service, or thing this brand will be attached to?
• What about each reference brand specifically do you love? (the photography? the tone? the restraint?)
• Who buys this — describe the 2-3 audience segments this brand should serve, plus one vivid anchor persona inside the primary segment.
• Any constraints? (industry, regulation, location, price tier?)

Always also ask (regardless of input type):

• Do you have any existing brand assets you want to keep or incorporate? (Logo, wordmark, symbol, name, colors, fonts, photography, packaging — anything you don't want to lose.)
• Any specific references, inspirations, or moodboards you'd want this to draw from?
• Is this a digital product (app, website, SaaS, web tool)? This determines whether the Icons page belongs in the full guidelines — for non-digital brands (products, services, restaurants, fashion, etc.) the Icons page is skipped.

These two are essential — they prevent you from generating things the user already has, and they anchor the work in references the user actually likes. Always include them.

Keep it to a single message. Aim for 5-7 questions total (input-specific + the 2 universal), conversational not clinical. Wait for answers before proceeding.

After answers, analyze the input + answers together and read back:

• Aesthetic territory: what visual world does this live in?
• Audience segments: primary segment, secondary segment(s), and one vivid anchor persona inside the primary segment. Do not collapse the audience into one over-specific individual.
• Positioning: what's the wedge — what does this stand for that competitors don't?
• Price tier / category fit: where on the market shelf does this sit?
• Story hook: what's the emotional reason someone cares?
• Assets being kept: explicitly list what the user said they want to preserve (existing wordmark, name, colors, etc.)
• References anchoring the work: list the user-named inspirations.

Then preview the deliverable and invite specific guidance — before moving to brand directions, show the user what'll be in the final guidelines so they can flag anything to add, change, or call out:

here's what i'll build into the brand guidelines (14-16 pages depending on your brand):

1. Cover (brand name, tagline, hero mood)
2. Strategy & positioning (primary/secondary audience segments + anchor persona)
3. Brand foundation (mission, values, story)
4. Logo (wordmark + symbol + variants)
5. Logo don'ts
6. Color palette
7. Typography
8. Icons — UI icon system + library guidance, ONLY IF this is a digital product (app / web / SaaS). Skipped for non-digital brands.
9. Voice & tone
10. Imagery rules (photography and/or illustration, adapted to brand medium; splits to 2 pages if hybrid)
11. Visual world / lifestyle imagery
12. Touchpoints (real photos showing the brand in use)
13. Brand applications (mockups: business card, app icon, favicon, etc.)
14. Digital + social
15. Do & don't

plus a brand kit zip at the end with: `brand.md` spec, logo assets (symbol PNG sizes, wordmark SVG/PNG, lockup SVG/PNG), brand fonts, design tokens (CSS / JSON / Tailwind), AI prompts (system prompt + task-specific starters), and the icon SVGs if applicable.

anything you want to add, change, call out specifically, or want me to handle differently? if not, i'll move on to the 3 brand boards.

Wait for response. Incorporate any specific user guidance (add a page, swap something, special focus on a particular section, exclude something) before moving to Step 2. This catches scope mismatches early — much cheaper than discovering them after the PDF is built.

Step 2 — Generate 3 Visual Brand Boards (PDF)

This step is the user's first visual touchpoint with the brand. No text-only "directions" precede it. The boards ARE the directions, made visible. Each board contains a complete visual identity at-a-glance so the user can see the difference, not just read it.

Build a single 3-page PDF (one page per board, 1200×850 each) and save it to ~/Desktop/[brand-slug]-brand-boards.pdf. Each board is a genuinely different brand direction — not template recolors. Differentiate on WHO the brand is for and WHY it exists, while making the visual system, layout, fonts, color logic, photography style, and voice feel distinct.

Each option must include:

• Wordmark in the brand's display font — use the user's existing wordmark if they have one they like; propose a new one if they need a logo or don't like their current one. A new wordmark must have custom letter treatment: adjusted spacing, ligature, cut, terminal, case, underline, or other ownable detail. It is not just a Google Font typed in a color.
• Symbol/mark — a standalone graphic that lives without the wordmark. Use the user's existing symbol if they have one they like; propose a new one otherwise. Even if the user keeps their wordmark, propose a symbol if they don't have one — favicons and app icons need a non-typographic mark. For new symbols, generate a transparent PNG via generate_image with provider="gpt-image-2". Ask for a clean isolated mark on transparent background, no baked-in letters, no watermark, no mockup, centered in a square. Do not trace the generated symbol to SVG; export PNG sizes from the approved master. Must work at 16×16 AND 512×512.
• Seal / badge — if the option uses a seal, stamp, badge, or monogram, it must be readable and ownable at small and medium sizes. It cannot be a generic circular font lockup, clip-art crest, or low-contrast decorative filler.
• Tagline (8 words max)
• Voice sample with visible "VOICE" label (one quoted sentence, 14 words max)
• Compact board story (~35 words max, min 2 sentences)
• Lifestyle world description with visible "WORLD" label (~22 words max, min 1 full sentence)
• Lifestyle mood image (generated via gpt-image-2)
• 4-color palette with hex + role labels
• Display + body type specimens with named fonts

Brand board pages should look different enough that the user can tell which identity they are seeing before reading the labels. Don't use the same template recolored 3 times; each board's layout should embody the option's design philosophy. A magazine-cover option should look like a magazine cover (full-bleed photo, masthead-style); a soft consumer option should look like a homepage hero (rounded shapes, soft circles for swatches); an editorial option should look like a literary spread (huge italic centered, inset photo). See references/brand-guidelines.md "Brand Board Layout — Differentiate per Option" for examples.

If you can't physically tell which brand you're looking at without reading the labels — regenerate within the visual-QA retry budget below.

Page size: 1200×850px. Renderer: local Chrome headless preferred; WeasyPrint is allowed only when the HTML is written for it. Render board PDFs and QA previews locally, then copy the final board PDF to ~/Desktop.

Board quality gate: the 3-page preview must pass visual QA, not just render QA.

Retry budget: each brand-board or guidelines PDF visual-QA loop gets at most 2 total render/repair attempts for the same option/deck (initial render + one repair rerender). After either cap is exhausted, stop and ask the user which failed asset or layout issue they want to relax; include the failing page/asset name, the QA reason, and the best preview URL so far.

1. Inspect each PNG preview before sending the PDF. Fail ugly density, weak hierarchy, muddy one-note palette, unreadable small text, empty mockup/image slots, clipped text, and body copy or non-masthead text intersecting icons, swatches, seals, photos, phone mockups, or decorative rules. Also inspect the symbol at 16×16 and 512×512; if the small-size read is illegible, muddy, too generic, or collapses into noise, regenerate or simplify before delivery. Website/social/app mockups are optional on brand boards; do not add them unless they contain real content. If included, flat color rectangles count as empty placeholders unless the section is explicitly a palette specimen.
2. Read each board preview at full size. Fail low-contrast type, unreadable small text, text/photo collisions, missing content, weak hierarchy, and muddy one-note palettes. Masthead wordmark/tagline/issue metadata overlays on photos are allowed only when they use deliberate negative space or a contrast scrim and pass contrast QA as defined in references/brand-guidelines.md Rule 5. Body copy on images is still forbidden.
3. Fix every captured FAIL before delivery. If the board is technically valid but ugly, treat it as failed and simplify hierarchy, copy density, or decorative elements before rerendering.

Font rule: fresh fonts per brand AND fonts must have character. Never default to Inter / Karla / Outfit / DM Sans / Lato — they have no point of view as a display face. Explore the full Google Fonts library. See references/brand-guidelines.md "Must Have Character — Don't Default to Safe Fonts" for high-character options by vibe. Download the chosen font files locally and use absolute file:// @font-face declarations in rendered HTML.

Font fallback for non-Latin brand names: every font-family chain in brand boards, quick PDFs, and full guidelines must include broad-script fallbacks. Use Chromium's per-glyph fallback so Latin stays in the chosen brand face while CJK, Arabic, Cyrillic, and other scripts resolve to Noto families instead of tofu boxes. Minimum chains: display/serif BrandDisplay, "Noto Serif SC", "Noto Serif TC", "Noto Serif JP", "Noto Serif KR", "Noto Sans Arabic", serif; body/sans BrandBody, "Noto Sans SC", "Noto Sans TC", "Noto Sans JP", "Noto Sans KR", "Noto Sans Arabic", system-ui, sans-serif.

Do not build the full 14-16-page guidelines PDF until the user picks an option — that wastes time on rejected identities. Exception: in autonomous full mode, use model judgment to pick the strongest board or hybrid and continue without waiting.

Present all 3 clearly. Ask the user to pick one, or mix elements from different options.

Step 3 — Build the Full Brand Guidelines PDF

Once user confirms a board, build the 14-16-page brand guidelines PDF. In autonomous full mode, build from the model-selected board or hybrid recorded in the assumptions log.

Page count is conditional:

• 14 pages — non-digital brands (product, restaurant, fashion, service, etc.) with single-medium imagery. Icons page is skipped.
• 15 pages — digital brands (app / web / SaaS) with single-medium imagery. Includes Icons page.
• 15 pages — non-digital brands with hybrid imagery (photo + illustration). Imagery splits to 2 pages; Icons skipped.
• 16 pages — digital brands with hybrid imagery. Both Icons and split-Imagery present.

Renumber pages contiguously based on what's included. Do not leave page-number gaps.

Page structure (full list — apply conditionally per above):

1. Cover — Brand name, tagline, hero mood image. Full-bleed.
2. Strategy & Positioning — Direction name. Positioning statement (one punchy sentence). Target audience system: primary segment, secondary segment(s), and one vivid anchor persona inside the primary segment. Do not describe only one over-specific customer. 3-4 reference brands with "borrow this" notes.
3. Brand Foundation — Mission. Brand values (3-5). The "why this exists" story (2-3 paragraphs of real copy in brand voice — not a template).
4. Logo — Primary mark + all variants (horizontal, icon-only, reversed), usage rules (on dark / on light / on color), logo mark explanation, clear space rule.
5. Logo Don'ts — Explicit misuse rendered in CSS: never stretch, never rotate, never wrong background, never recolor, never use drop shadow. Show each violation visually with a ✗ label.
6. Color — All swatches with hex + RGB + CMYK, primary pairings, accessibility/contrast note, never-do combinations. Full-bleed color columns, not swatches floating on white.
7. Typography — Full hierarchy (H1 through caption with exact px sizes), display/accent/body fonts, usage rules per context, type on color backgrounds, minimum sizes.
8. Icons (digital brands only — skip for product, fashion, restaurant, service brands) — UI icon system: 8-12 essential icons (arrow-right, check, close, plus, settings, search, user, bell, menu, info, etc.) rendered in the brand's geometric style + stroke/corner/grid rules + library recommendation for icons beyond the set. See references/brand-guidelines.md "Icons Page — Structure & Rules" section.
9. Voice & Tone — Tone adjectives, copy examples by context (headline, body, button, error state, social caption), forbidden words/phrases. Show actual brand copy, not generic example copy.
10. Imagery Rules — adapts to the brand's medium. Photography-led → photography rules (subject/light/color/cast/texture/forbidden + 1 example photo). Illustration-led → illustration rules (style/color/line/character/composition/forbidden + 1 example illustration). Hybrid (both equally) → split into two pages, guidelines becomes 16 pages. See references/brand-guidelines.md "Imagery Rules Page — Adapts per Brand."
11. Visual World — Full-bleed 4-column grid of 4 images matching the brand's medium mix (all photos, all illustrations, or mixed). Cast must be racially diverse for any people-featuring images.
12. Touchpoints — Real Photos — A 2×2 grid of 4 REAL GENERATED PHOTOGRAPHS showing the brand in physical context. Adapt to the brand type:
    • Physical product brand: hang tag on garment, woven label macro, kraft mailer with tissue, flat lay of product + packaging
    • Digital / app brand: phone in hand showing the app, laptop on desk showing the site, sticker on water bottle, tote bag in a real scene
    • Service brand: business card in hand, branded notebook on desk, signage on a building, swag in context No CSS vector mockups on this page — without real generated photos the touchpoints look like a Figma exercise, not a brand. Real images prove the brand can survive contact with the physical world.
13. Brand Applications — CSS Mockups — CSS-rendered mockups of secondary applications, each labeled with specs: business card (with dimensions), social avatar (circle crop), sticker/app icon (rounded square), email signature, presentation cover slide. For product brands also include: hang tag spec, woven label spec, shopping bag spec.
14. Digital / Social — Website hero aesthetic (colors, fonts, layout feel), Instagram grid style (3×3 mockup with color palette + caption tone), story template (brand colors + logo placement), link-in-bio layout.
15. Do & Don't — 5 dos and 5 don'ts, brand-specific and actionable. Not generic ("do use the logo correctly") — brand-specific ("do leave a full em-dash of space around the wordmark in social posts; never crop our tagline mid-word").

Keep Page 2 (strategy) before Page 3 (foundation), and keep both before logo/color/type. Strategy frames every visual decision that follows.

Include every page in the structure. If the brand has no packaging, adapt the touchpoints page to the brand type instead of skipping it; the guidelines should still show how the identity survives in real contexts.

Completion gate: do not deliver a condensed or partial guidelines PDF. A condensed 6-page deck, missing Visual World page, missing Touchpoints page, or missing Brand Applications page is a failed checkpoint, not a final deliverable. If time runs out, stop with a resumable checkpoint that lists completed pages, missing pages, generated asset URLs, and the next render step. Do not present the deck as done until all mandatory pages have rendered and passed QA.

All build rules in references/brand-guidelines.md apply: local rendering rules, explicit 1200×850 page dimensions, absolute local asset/font paths, no load-bearing text on generated images, no duplicate generated images across deck, text contrast thresholds on dark backgrounds, and mandatory pre-send QA previews for every page.

Deliver as PDF. Save to ~/Desktop/[brand-name]-brand-guidelines.pdf and tell the user the local path. Do not upload or host the PDF unless the user explicitly asks for a hosted copy. If the user is not on a Mac, save to the project working directory and mention the path in your reply.

Step 4 — Export the Brand Kit (HARD GATE — only after user explicitly approves the guidelines)

After delivering the 14-16-page guidelines PDF, wait for explicit user approval before exporting the brand kit. Don't auto-export — the kit codifies the final brand, so only build it once the brand is locked. Exception: in autonomous full mode, the single clear brief already authorizes the full deliverable set, so export brand-kit.zip after the guidelines pass QA.

Then build a comprehensive brand kit zip that lets the user produce on-brand work anywhere — in Claude, GPT, Figma, with a designer, with a developer.

Kit structure:

[brand-name]-brand-kit.zip
├── brand.md                       # comprehensive machine-readable spec
├── brand-guidelines.pdf           # full 14-16-page guidelines PDF (the visual deliverable)
├── README.md                      # 1-page how-to-use guide
├── logo/
│   ├── symbol/                    # standalone mark — RASTER ONLY, no SVG (symbol is generated PNG, not traced)
│   │   ├── symbol-[color]-16.png
│   │   ├── symbol-[color]-32.png
│   │   ├── symbol-[color]-64.png
│   │   ├── symbol-[color]-128.png
│   │   ├── symbol-[color]-256.png
│   │   ├── symbol-[color]-512.png
│   │   ├── symbol-[color]-1024.png
│   │   └── symbol-[color]-2048.png
│   ├── wordmark/                  # the brand name — vectorized via text-as-paths
│   │   ├── wordmark-[color].svg
│   │   └── wordmark-[color].png
│   └── lockup/                    # symbol + wordmark together at locked measurements
│       ├── horizontal/
│       │   ├── lockup-h-[color].svg
│       │   └── lockup-h-[color].png
│       └── stacked/
│           ├── lockup-s-[color].svg
│           └── lockup-s-[color].png
├── icons/                         # digital brands only — UI icons from the Icons page as SVGs
│   ├── arrow-right.svg
│   ├── check.svg
│   ├── close.svg
│   ├── plus.svg
│   ├── search.svg
│   ├── user.svg
│   ├── settings.svg
│   ├── bell.svg
│   ├── menu.svg
│   ├── info.svg
│   └── [+ any brand-specific icons]
├── fonts/                         # actual TTF font files (OFL-licensed Google Fonts)
│   ├── [display-font]-Variable.ttf
│   ├── [body-font]-Variable.ttf
│   └── README.md                  # license + install instructions
├── tokens/                        # design tokens for devs
│   ├── tokens.css                 # CSS custom properties — paste into :root
│   ├── tokens.json                # same content in JSON — for AI tools / CI
│   └── tailwind.config.snippet.js # paste into tailwind.config.js extend block
└── prompts/                       # AI prompts for downstream brand use
    ├── system-prompt.md           # paste at the top of a Claude/GPT thread for brand voice
    ├── tweet.md                   # task-specific starter: write a tweet
    ├── landing-hero.md            # task-specific starter: landing page hero copy
    ├── email.md                   # task-specific starter: marketing/transactional email
    ├── error-message.md           # task-specific starter: write a friendly error
    ├── photography.md             # task starter: generate brand-style photography (with cliché guardrails + brand-photography rules embedded)
    └── illustration.md            # task starter: generate brand-style illustration (only if the brand uses illustration as a medium)

Color variants to export (per logo): primary-on-light, primary-on-dark, neutral-on-light (ink), neutral-on-dark (cream), and one accent-on-color combination. Usually 4-5 color sets per logo type.

brand.md — see references/brand-md-template.md for the full structure. It must include:

• Quick reference block (name, tagline, primary color, fonts, voice in one scannable section)
• Positioning + audience segments
• Mission, values, story
• Voice & tone (adjectives, copy examples by context, forbidden words)
• Colors (table with hex / RGB / CMYK / Pantone / role)
• Typography (display + body + Google Fonts URLs + full hierarchy)
• Logo (wordmark description + symbol description + lockup specs + file list with paths)
• Photography rules
• Visual world description
• Touchpoint specs
• Do & don't list
• Reference brands with "borrow this" notes
• How-to-use section telling downstream tools/people how to apply the spec

Logo asset pipeline:

1. Symbol assets — the symbol is a generated raster mark, so export PNG only. Start from the approved 2048x2048 transparent master, verify true alpha, then generate 16/32/64/128/256/512/1024/2048 PNGs per needed color/background variant. Do not trace it to SVG and do not claim it is vector.
2. Wordmark assets — render the brand name as real font text, then convert the chosen font text to outlined paths for wordmark-[color].svg; also export a 1024-wide transparent PNG fallback. The wordmark is reproducible because it is typography, not an image-generation artifact.
3. Lockup assets — assemble the approved symbol PNG + outlined wordmark at the locked measurements. Export lockup-[orientation]-[color].svg with the PNG embedded inline and the wordmark as paths, plus a 1024-wide PNG fallback. Keep geometry identical across color variants.
4. Optional print PDF — only add PDFs if the user or printer specifically asks. A PDF may embed the raster symbol plus vector wordmark, but it is not a pure-vector logo file.
5. Icon SVGs — for digital brands only, write the icon set as standalone SVGs with stroke="currentColor", viewBox="0 0 24 24", and the brand's chosen stroke weight + corner style applied consistently. See references/brand-guidelines.md "Icons Page — Structure & Rules" for which icons to include.
6. Design tokens — generate all three files from the brand spec:
   • tokens.css — :root block with --color-*, --font-*, --font-size-*, --line-height-*, --space-*, --radius-*, --shadow-* custom properties
   • tokens.json — same content as JSON object with sections: color, font, fontSize, lineHeight, spacing, radius, shadow
   • tailwind.config.snippet.js — JavaScript snippet to paste inside module.exports.theme.extend covering colors, fontFamily, fontSize, borderRadius, boxShadow
7. AI prompts — generate each prompt file with brand specifics interpolated:
   • system-prompt.md — a system prompt to paste at the top of any Claude/GPT thread. Includes: brand voice adjectives, forbidden words, copy rules, photography direction, color/font specs, sample voice examples. End with "Always apply this brand voice unless explicitly instructed otherwise."
   • tweet.md — task starter: max 280 chars, voice constraints, sample target tweets, then "Task: [USER FILLS IN]"
   • landing-hero.md — task starter: hero copy structure (headline + subheadline + CTA), brand voice rules, examples from the guidelines
   • email.md — task starter: email tone, subject line guidance, body structure, sign-off conventions
   • error-message.md — task starter: how the brand handles error/empty/loading states in voice (warm not robotic, specific not vague)
   • photography.md — task starter for generating brand-style photography (gpt-image-2 etc.). Must include: master prompt template tailored to the brand's photo direction (subject, light, color grade, cast diversity, texture); explicit "what to AVOID in the prompt" list (studio strobes, stock terms, glass coworking spaces, "engineers at laptops," "professional," "premium," etc.); banned cliché concepts list (hourglasses, lightbulbs, handshakes, network nodes, glowing brains, etc.); subject substitutes for "person doing X"; quality requirements (butter accent, diversity, film grain, documentary); explicit no-text guardrail string; note about never naming real publications.
   • illustration.md — only if the brand uses illustration as a medium. Task starter for generating brand-style illustrations. Master prompt template with strict palette + style rules (flat vector / line art / etc), banned elements (gradients, drop shadows, 3D, photographic textures), when to use illustration vs photography. Skip this file entirely if the brand has no illustration in its visual world.
8. Brand fonts — local export step. Download the actual font files from Google Fonts (or wherever the brand fonts live) and include in fonts/:
   • Variable font files when available: [FontName]-Variable.ttf (single file, supports all weights)
   • Or static weights at the levels the brand uses
   • Use local TTFs in local render HTML via absolute file:// paths
   • Add a fonts/README.md noting the license (OFL is common, allows redistribution) + Google Fonts URL for online installation
9. Brand guidelines PDF — copy the 14-16-page guidelines PDF produced in Step 3 into the kit as brand-guidelines.pdf. The kit is incomplete without it.
10. README.md — 1-page guide telling the user: what's in the kit, how to use brand.md with AI tools, which logo file for which context, where to install fonts (local TTFs or Google Fonts URLs), how to use the photography/illustration prompts.
11. Zip everything: zip -r [brand]-brand-kit.zip brand.md brand-guidelines.pdf README.md logo/ icons/ fonts/ tokens/ prompts/

Brand-kit completion gate: when the user confirms export, or when export_kit is set in --config, the brand kit zip is a required deliverable. Do not mark the brand kit complete until the zip exists and contains brand.md, brand-guidelines.pdf, README, logo assets, icons, fonts, tokens, and prompts. If any required file cannot be produced, stop with a resumable checkpoint and list the missing files instead of shipping a partial zip.

README.md — 1-page guide telling the user:

• What's in the kit
• How to use brand.md with AI tools (paste into Claude/GPT to generate on-brand work)
• Which logo file to use for which context (web favicon → symbol PNG; print collateral → PDF; web header → wordmark SVG; etc.)
• Font installation links (Google Fonts URLs plus local TTF filenames)

Delivery:

• Save zip to ~/Desktop/[brand-name]-brand-kit.zip for local Mac users.
• If the environment cannot download fonts or write a local zip, do not ship a partial kit. Stop with a resumable blocked checkpoint that lists the completed artifacts (local PDF path, brand.md, tokens, logo assets), the missing files, and the exact filesystem/network blocker.
• Host the completed zip only if the user explicitly asks.
• Tell the user what's in the completed zip and link to the brand.md so they can preview without unzipping.

Post-flight quality gate

Before declaring success on either deliverable, render local preview images and perform a structured visual QA pass with a structured verdict:

• Quick mode: inspect the PNG/JPG previews or contact sheet for quick-brand.pdf before delivering the quick brand package.
• Full mode: inspect the final page PNG/JPG previews or contact sheet used to approve the guidelines PDF before delivering the local PDF path. Do not run analyze_media on the final PDF as the primary QA path; page previews are the QA artifact because they expose page-level layout and avoid large-PDF rasterization failures.

Return JSON only: {
  "verdict": "clean" | "degraded" | "catastrophic",
  "observations": string[],
  "quality_warning": string | null,
  "re_roll_suggestion": string | null
}
Check that the brand name is spelled consistently, the `quick-brand.pdf` or guidelines PDF preview shows the required pages, low-contrast text is not present, the wordmark/symbol are not garbled, and there are no blank or duplicate-looking pages.

• If verdict is clean, return the quick brand package or local PDF path normally.
• If verdict is degraded, return the quick brand package or local PDF path plus the quality_warning so the user can review before publishing.
• If verdict is catastrophic, do not call the deck complete; surface the verdict and re_roll_suggestion instead of declaring success.

Key Principles

• The input is the brief. Don't ask for lengthy intake forms. Read what's in front of you and ask 3-5 precise questions.
• Be specific about customers without narrowing the brand to one person. Vague audiences = weak brands, but one hyper-specific individual can make the output unusably narrow. Define audience segments first: a primary segment, 1-2 secondary segments, and one anchor persona that makes the primary segment feel concrete.
• 3 boards at the main full-mode choice point. Step 2 always gives three visual brand boards, not text-only directions or template recolors.
• Opinionated but collaborative. Present your read confidently. They can push back.
• Generate actual copy — don't give templates with [BRACKETS]. Write real words in the brand voice.
• All images must look real and crafted. Generated lifestyle/touchpoint images need film grain, natural light, slight imperfections, editorial composition. Banned: perfect symmetry, gradient backgrounds, studio strobes, stock-photo energy, AI-smooth surfaces, floating objects on white. If it looks fake, use the image retry budget above; do not keep regenerating after the capped retry.
• One deliverable set per selected depth. Quick mode delivers a quick brand package. Interactive full mode delivers one brand guidelines PDF, with the optional brand kit only after the user confirms the guidelines. Autonomous full mode ships all three full artifacts: brand boards, guidelines, and brand kit.

---

Brand Quality Standards

Every brand produced by this skill should meet the following standards. Generic output is a failure state because the deliverable is meant to guide real design decisions, not decorate a template.

The Anti-Generic Test

Before delivering anything, ask: Could this be a brand for literally anything else? If yes — it's not done.

Strong brand = specific product/service + clear audience model + specific point of view. Weak brand = vibes + aesthetic mood board + empty tagline. Never deliver the second.

Copy Standards

What good brand copy sounds like:

• It makes a specific claim: "Heavy wool. Made to last a decade." / "Built for one quiet hour a day."
• It has a point of view: "Not trend-led. Not mass-made."
• It can speak concretely to a reader inside a segment: "The app you reach for before checking your phone." This is copy style, not audience strategy; do not collapse the brand's audience model to only that reader.
• It creates tension or contrast: "Handmade. Overused. On purpose."
• It trusts the reader: no over-explaining, no "perfect for any occasion", no "cozy vibes"

What bad brand copy sounds like:

• "Crafted with love" / "Made with care" / "Designed with passion"
• "Perfect for any occasion" / "A timeless addition"
• "Quality you can feel" / "Designed to inspire"
• Generic taglines: "Where quality meets style" / "Wear your story"
• Hollow superlatives: "premium", "luxury", "elevated", "curated", "artisanal"
• Anything that could describe 500 other brands without changing a word

Tagline test: A great tagline could only belong to this brand. "Handmade. Overused. On purpose." is WORN's. "Just do it." is Nike's. If your tagline could appear on any random Etsy shop or Squarespace site without anyone noticing — rewrite it.

Design Standards

What editorial brand design looks like:

• Strong typographic hierarchy — one thing is clearly the most important
• Color used with conviction — large fields, not accent dots
• Photography bleeds to edges — no floating images with shadow drops
• Scale contrast — one element dominates, others recede
• Pages feel designed, not assembled
• Whitespace is intentional, not default padding

What generic brand design looks like:

• Equal-sized boxes arranged in a grid
• Body copy the same size as everything else
• Centered everything
• White background with a few colored boxes
• Photos floating in white space with rounded corners
• Font specimens that say "Font Name Here" or "Sample Text"
• Color swatches that look like a paint store brochure

Layout rule: If a page could have been made in Canva or PowerPoint in 10 minutes — it's not good enough. Every page should require design decisions only someone with taste would make.

Photography & Diversity Standards

Generated image sets featuring people should show racial diversity. This avoids defaulting every brand world to the same narrow cast.

• Default to a mixed cast across all 4+ lifestyle images: include Black, Asian, Latina, South Asian, Middle Eastern, or mixed-race subjects
• Vary body types, not just skin tone
• If only one person is shown, make a deliberate choice about who that person is — don't default to white/light-skinned
• Diversity is not a checkbox. It's a design choice that makes the brand more resonant and more honest

Photography must feel found, not staged:

• Real rooms with real lives in them (papers, plants, worn furniture)
• Imperfect light (window light, overcast, early morning)
• Film grain always — even a little
• Subjects not looking at camera unless it's a strong choice

Deck / Guidelines Design Standards

• Typography must load. Download the actual font files and use absolute file:// paths in local render HTML. Always verify loaded fonts before signing off on a render. If fonts fall back to system defaults — the deck is broken, not deliverable.
• See references/brand-guidelines.md for the full local render contract and QA rules.
• Every page must have a clear visual hierarchy — one thing to look at first.
• Full-bleed photography pages should feel like magazine spreads, not slideshow slides.
• Color palette pages: full-bleed color columns, not swatches floating on white.
• Logo page: logo dramatically large, with clear variants, not timid or small.
• Voice page: show actual brand copy, not generic example copy.
• Touchpoints page: must include generated photographs of actual touchpoints — never CSS boxes.

Deliver the guidelines as one local PDF, not as individual page images. Save the PDF path and copy it into the brand-kit zip when exporting the kit.

The Taste Check

Before delivering any brand output, ask yourself:

1. Would a 25-year-old with good taste want to buy from / use / work for this brand?
2. Does the copy sound like a real person wrote it?
3. Does the design look like a real designer made it?
4. Are the photos diverse and real-looking?
5. Is there a specific point of view — something this brand stands for that another brand doesn't?

If any answer is "not sure" — improve it before delivering. Strong and specific beats safe and generic every time.

---

Load-bearing phrases

These are the anchors that keep this skill from drifting into generic brand-book output:

---

Engine choice: gpt-image-2 (with caveats)

Default to gpt-image-2 at quality: "medium" for all brand imagery. Why:

• Best instruction-following for cast-diversity prompts (nano-banana-pro tends to drift toward a white default unless heavily prompted).
• Strongest no-text guardrail adherence — critical for touchpoint shots (hang tag / woven label / sticker) where any baked-in text would ruin the mockup.
• Native 3:4 / 4:3 / 9:16 ratios crop cleanly on sharp subjects without weird stretching.

Avoid nano-banana-pro for this skill — it bakes magazine-cover-style text into product shots when prompts mention "editorial." 1K from gpt-image-2 is plenty for a 1200×850 PDF page; bump to gpt-image-2's 2K tier (or escalate to seedream for higher) only if a specific touchpoint genuinely needs print-tier resolution. (4K on gpt-image-2 is 16:9 / 9:16 only — this skill's 3:4 / 4:3 ratios route to seedream if 4K is required.)

Runtime expectations

Tell the user the rough total up front — long stages without status updates feel broken. Always report times in PST when giving timestamps.

Quick brand target

Total quick target: 8-12 min after usable input, excluding user response time.

Full brand book timing manifest

For every full run, maintain a timing manifest in working notes and include it in the final delivery or resumable checkpoint. Capture PST timestamps for:

• Input received / mode selected
• Intake complete
• Visual boards drafted
• Brand board render started / completed
• User identity choice locked
• Image generation batch 1 started / completed
• Image generation batch 2 started / completed
• Full guidelines render started / completed
• Full-deck QA started / completed
• Brand kit export started / completed, if requested

If a run takes around 2 hours again, do not guess where the time went. Use this manifest to name the actual slowest stage and carry that evidence into the next cut.

Full brand book target

Total full target: ~25–45 min wall-clock excluding user response time. Recent field feedback saw ~2 hours end to end for a paid creator tutorial recording; treat that as the baseline symptom to beat, not as an acceptable target.

---

Failure modes

Recovering from upstream 5xx on generate_image

If any paid generation or render MCP call returns:

• code: "provider_5xx" AND retry_class: "retry_after_backoff"
• Or HTTP 502 / 503 / 504 from an upstream image provider

Do this:

1. Wait 5 seconds.
2. Re-call the exact same MCP tool with the exact same arguments. Do not rewrite the prompt, swap fonts, change palette, change HTML, change provider, or regenerate inputs.
3. If the retry also fails with 5xx, abort and surface to the user: "Provider returned a transient upstream error twice. Try again in 1-2 minutes; this usually clears on its own."

Do not retry more than once. This is a transient outage, not a brand-direction problem; changing the creative brief wastes credits and makes the retry harder to compare.

Recovering from upstream 4xx / moderation_blocked

If generate_image with provider="gpt-image-2" returns an upstream 4xx or moderation_blocked:

1. Do NOT retry the same prompt; moderation and most 4xx validation failures are deterministic.
2. If the failed asset is a generated symbol or lifestyle image, try a fallback provider once only when the brief can survive it: seedream for high-resolution brand imagery, or an inline SVG mark for simple geometric symbols.
3. If the fallback provider also fails or would materially change the brand direction, surface to the user: "Image provider declined this brand-image prompt. Try a less recognizable reference, remove real publication/celebrity cues, or approve an SVG/simple-mark alternative."

Recovering from upstream 429 (rate limit)

If any upstream returns HTTP 429 with a backoff hint:

1. Wait the hinted backoff, or 30 seconds if no hint is provided.
2. Re-call the exact same MCP tool with the exact same arguments.
3. Do not retry more than once. If it still returns 429, abort and surface the rate-limit message instead of spending more calls.

capture_website returning empty / page-not-loaded

This skill normally builds from user answers and provided assets, but URL-sourced references or future intake helpers may call capture_website. If capture_website returns 200 but action_bboxes is empty or recording_viewport is 0x0:

1. Do NOT retry; the page failed to render in the capture environment.
2. Surface: "Could not capture <url>. The page may be blocked / paywalled / require auth. Please provide screenshots, logos, or hosted assets instead."

Long-running task_status exceeding ceiling

Each async MCP call returns either an inline result or {task_id, status} for polling. Use these ceilings before deciding a task is stuck:

• gpt-image-2 high quality: 3 min per call
• Seedream image generation: 3 min per call

Use whichever is earlier: the provider's ceiling x 1.5 or any skill-specific hard polling cap. If task_status returns status: "processing" or status: "queued" past that earlier limit, call task_cancel({task_id}) and surface: "Provider taking unusually long; aborting. Try again."

---

Supporting file: README.md

build-a-brand · Claude Code Skill

A skill that takes any input — an idea, a website URL, a list of reference brands, product photos, or a request to refresh an existing brand — and produces a complete brand identity, ending in a 14–16-page brand guidelines PDF + a portable brand kit.

What this skill does

Walks the user through a 4-step workflow:

1. Read the input — adaptive intake questions per input type + universal asks about existing brand assets, references, and whether the brand is a digital product. Finishes with a deliverable preview to invite specific guidance.
2. Generate 3 visual brand boards (PDF) — three complete brand directions, each with its own colors, fonts, photography style, voice samples, and logo concept. Boards diverge across at least 4 structural dimensions (density, saturation, layout philosophy, type energy, voice register). User picks one or mixes elements before guidelines build. Hard stop until user picks.
3. Build the full brand guidelines PDF — render the 14–16-page guidelines PDF for the chosen board (page count depends on whether the brand is digital and whether imagery is single-medium or hybrid). Includes: cover, strategy, foundation, logo, logo don'ts, color, typography, voice, photography, visual world, icons (conditional), touchpoints, application, digital/social, do & don't. Hard stop until user explicitly approves the guidelines.
4. Export the brand kit — after user confirms the guidelines PDF, bundle a zip with: brand.md (machine-readable spec), brand-guidelines.pdf (the visual deliverable), logo assets (symbol as transparent PNG at 8 sizes; wordmark + lockup as SVG/PNG with text-as-paths), conditional UI icon SVGs for digital brands, brand fonts (TTF), design tokens (CSS/JSON/Tailwind), and AI prompts (system prompt + copy + image starters).

Autonomous full exception: when a non-interactive run supplies an explicit full request (--full, mode: "full", or asks for full guidelines / full brand book) and cost_ack=proceed, the brief is the spec. The skill ships all three artifacts — brand boards, guidelines, and brand kit — without waiting at the board-pick or guidelines-approval gates. If the brief is not clear enough to pick a direction responsibly, it stops once with the missing decision. Non-interactive clear briefs without explicit full depth still use quick mode.

Install

# Extract the zip to your user-level Claude Code skills directory:
unzip build-a-brand-skill.zip -d ~/.claude/skills/

# Confirm the folder lives at:
ls ~/.claude/skills/build-a-brand/
# Should show: README.md  SKILL.md  references/

The skill is now available in any Claude Code session.

Invoke

The user can trigger this skill by saying any of:

• "build me a brand"
• "make me a brand"
• "design a brand identity"
• "brand guidelines for [X]"
• "i want a brand book"
• "create a brand from scratch"
• "brand for [idea]"
• "i want a brand that feels like [X] + [Y]"
• "rebrand my [thing]"
• "visual identity for [thing]"
• /build-a-brand

Folder structure

build-a-brand/
├── README.md                       # this file
├── SKILL.md                        # main skill instructions (4-step workflow)
└── references/
    ├── brand-directions.md         # how to structure positioning angles (WHO + WHY differentiation rule)
    ├── brand-identity.md           # logo pipeline + symbol output rules + concept lanes
    ├── brand-guidelines.md         # 14-16 page build mechanics, font rules, image rules, three-pass QA
    └── brand-md-template.md        # template for the Step 4 brand kit `brand.md` file

Dependencies

• Image generation: Skill defaults to gpt-image-2 for all generate_image calls (logos, mood photos, textures).
• PDF rendering: Built for Chrome headless (--print-to-pdf) or WeasyPrint.
• Python + PIL: for image transparency keying, favicon-test renders, and lockup composition.
• Fonts: Pulled from Google Fonts as TTF for self-hosting.

Local vs Cloud

• Local by default: font downloads, image cleanup/compression, favicon tests, HTML/PDF rendering, QA screenshots/crops, logo asset assembly, tokens/prompts, and final zip packaging.
• Cloud only where needed: gpt-image-2 image generation and URL/source research when required by the brief.
• PDFs and zips are saved locally by default. Hosting/upload is only used when explicitly requested.

What the skill enforces

Embedded in the reference files as non-negotiable rules (all auto-applied during build):

Brand strategy & options

• 3 boards must be genuinely different brands, not template recolors — diverge across at least 4 structural dimensions (density, saturation, layout, type energy, composition, photography mood, voice register, era specificity)
• Adjective audit before delivery — top-3 adjectives per board; if any 2 share 2+ adjectives, push apart
• Divergence ≠ subtraction — every board delivers the brief at 100%, never strip back to differentiate
• Era palettes are specific (Y2K = chrome/gel/holo/candy, NOT muted cottage cream; same for any named era)

Logo

• Symbol generated via gpt-image-2, shipped as high-res transparent PNG (NOT traced to SVG)
• Symbol style is a brand-personality choice — flat, dimensional, painted, photographic, hand-drawn — whatever fits
• Mandatory checks: conceptually linked to brand, unique, recognizable at 16×16 (favicon test via PIL), ≤3 dominant colors, no text in image, true alpha=0 transparency
• 3 symbols across 3 boards must differ in concept lane (mascot / product-feature / abstract / monogram / hybrid / container)
• Wordmark is always Google Font; in the brand kit it's converted to text-as-paths SVG so it renders without the font file
• Lockup measurements perfectly measured and permanently fixed across all color variants

Fonts

• No favorite fonts and no banned fonts — every font in Google Fonts is in the running. Diversity is enforced through process (brainstorm fresh every brand + cross-brand variety check), not gatekeeping
• Display fonts with built-in shadow/3D detail (BungeeShade, Honk, etc.) only at hero scale (40px+) and only on cream/black backgrounds

Photography

• Hero photography shows the product IN USE (for digital products = phone/device with the actual result, or person using it). Never a representational stand-in object (the "keychain test")
• Photography occupies distinct visual territories per direction; vary medium and subject scale across the 3 boards

Texture (for retro/era briefs)

• Textures must be AMBIENT (subtle grain, VHS noise, paper grain, grainy gradient) — not literal patterns (halftone dots, glitter flakes, scanline rows)
• Always generated via gpt-image-2 (never CSS gradients — those read as theme-applied)
• Applied full-board with mix-blend-mode + opacity 0.12–0.30

Product clarity & layout

• Page 1 cover + Page 2 strategy must make the product unambiguous in the brand's voice (clarity through content, not robotic templates)
• Contrast gate — every text/background pair audited; pink-on-pink, lime-on-cream, dark-on-dark photos are auto-fail
• Complex fills (chrome / holographic / multi-stop gradients) only at hero scale (60px+); switch to solid + stroke at small scale
• .content element must have overflow: hidden + explicit max-height as a safety net against footer overlap

QA & approval gates

• Three-pass QA: render every page individually → thumbnail pass → mandatory crop-and-read (PIL crops into 800×800 regions, Read each crop file — glancing at the full PNG is NOT zoom-reading)
• Approval gates are HARD stops:
  • Step 2 → Step 3: user must explicitly pick a board before guidelines build
  • Step 3 → Step 4: user must explicitly approve the guidelines PDF before kit export
  • Creative direction ("make it cuter") is feedback, not approval — explicit "yes / ship it / go" only
• In autonomous full mode, the explicit full request plus cost_ack=proceed is the approval source; the run records its assumptions and continues through all three artifacts instead of stopping at those gates.

User-level Claude Code skill at ~/.claude/skills/build-a-brand/.

---

Supporting file: references/brand-directions.md

Brand Directions — Reference

A brand direction is a strategic positioning angle. Each direction should be genuinely distinct — not just aesthetic variations but different answers to "why would someone buy this and what does it mean to them?"

The Most Important Rule: Differentiate on WHO and WHY, Not WHAT

The most common mistake is presenting directions that are all variations of the same thing — "soft", "quality", "feminine" — just with slightly different words. That's differentiating on what, which leads to directions that blend together.

Real differentiation comes from:

• WHO the brand is built around (the maker's personality vs. the product vs. the community)
• WHY someone buys (to feel something, to be part of something, to get access to something scarce)
• What business mechanic drives it (drops, personal brand, gifting, nostalgia, etc.)

Ask yourself: could a savvy person immediately see these as three genuinely different businesses? If not, push further apart.

Examples of Genuinely Different Directions

The Insider — built around the maker's taste and personality. Customers follow the person, not the product. Could be named after the founder.

The Heirloom — leans into nostalgia and emotional weight. The pieces feel like they have history. Precious, slow, deeply feminine.

The Drop — borrows scarcity mechanics from streetwear. Limited releases, miss it and it's gone. Creates urgency and a following around drop announcements.

The Gifting Brand — positioned entirely around the act of giving. Not "wear this" but "give this to someone you love."

The Community — the brand is a membership in a taste tribe. Customers don't just buy, they belong.

Structure for Presenting Directions

**[Direction Name]** — evocative, 2-4 words
Positioning: [What the brand stands for — one punchy sentence]
What this means: [1-2 sentences on the business model / customer relationship this creates]
Customer: [Specific and vivid — who they are, what they care about, why they buy]
Vibe: [3-4 descriptive words]
Example names: [2-3 name ideas]

Tips

• Lead with the direction that feels most true to the product AND the seller's personality
• Make the 3 options feel like genuinely different businesses, not aesthetic variations
• Name the direction evocatively — "The Heirloom" not "Option B - Nostalgic"
• Be confident and specific. Vague directions lead to weak brands.
• After user picks a direction, note: the identity options in Step 3 should all sit within that direction's world — don't drift back to generic

---

Supporting file: references/brand-guidelines.md

Brand Guidelines — Build Guide

In full brand book mode, the brand guidelines PDF is the primary visual deliverable of this skill. It is 14-16 pages depending on brand type, rendered locally with Chrome headless or WeasyPrint, and delivered as a local PDF path. Quick brand mode has its own 3-page deliverable in SKILL.md; do not treat that quick PDF as a condensed or partial version of these full guidelines.

This guide is the technical playbook: page layouts, image generation, font rules, local render contract, QA checklist. All non-negotiable.

Execution Model — Local First

Keep deterministic production local:

• Local: workspace setup, downloaded fonts, compressed image files, transparent-background cleanup, favicon tests, HTML/CSS builds, PDF rendering, preview screenshots, visual QA, logo asset assembly, and kit packaging.
• Cloud: gpt-image-2 image generation for symbols, photography, illustration, and textures; URL/source research when the brief requires it.

Do not upload PDFs by default. Save PDFs and zips to ~/Desktop on Mac, or the project working directory if Desktop is unavailable. Only create a hosted/CDN copy when the user explicitly asks.

Page Structure (14-16 pages depending on brand)

Page count is conditional:

• 14 pages — non-digital brand (product, restaurant, fashion, service) with single-medium imagery. Icons page skipped.
• 15 pages — digital brand (app/web/SaaS) with single-medium imagery. Icons page included.
• 15 pages — non-digital brand with hybrid imagery. Imagery splits to 2 pages; Icons skipped.
• 16 pages — digital brand with hybrid imagery. Both Icons + split-Imagery present.

Renumber pages contiguously based on what's included. Do not leave gaps.

1. Cover — Full-bleed brand-specific layout. Brand name + tagline + hero mood image.
2. Strategy & Positioning — Direction, positioning statement, audience segments (primary segment, secondary segment(s), and anchor persona), 3-4 reference brands with "borrow this" notes.
3. Brand Foundation — Mission, values (3-5), why this exists (story in brand voice).
4. Logo — Primary mark + variants (horizontal, icon-only, reversed), usage rules, clear space.
5. Logo Don'ts — Misuse rendered in CSS with ✗ labels.
6. Color — Swatches with hex+RGB+CMYK, full-bleed color columns (not floating swatches).
7. Typography — Full hierarchy with px sizes, display/body specimens, usage rules.
8. Icons (digital brands only) — 8-12 essential UI icons in brand's geometric style + stroke/corner/grid rules + library recommendation. Skip this page entirely for non-digital brands and renumber subsequent pages.
9. Voice & Tone — Adjectives + actual brand copy examples by context.
10. Imagery Rules — adapts to the brand's primary medium (see "Imagery Rules Page — Adapts per Brand" section below):
    • Photography-led brand → Photography Rules (subject / light / cast / treatment / forbidden) + 1 example photo
    • Illustration-led brand → Illustration Rules (style / color / line / character / composition / forbidden) + 1 example illustration
    • Hybrid brand (both matter equally) → split into two pages, pushing the total to 16 pages
11. Visual World — Full-bleed 4-column grid of 4 images (photos and/or illustrations matching the brand's medium choice).
12. Touchpoints — Real Photos — 2×2 grid of generated photos showing the brand in physical/digital context. Real images, never CSS boxes.
13. Brand Applications — CSS Mockups — Business card, social avatar, sticker, hang tag, woven label, etc. CSS-rendered. Each labeled with specs.
14. Digital / Social — Web hero, IG grid (3×3), story template, link-in-bio.
15. Do & Don't — 5 dos + 5 don'ts. Brand-specific, actionable.

---

Step 0 — Workspace Setup

Images and fonts live in a persistent workspace path. /tmp is wiped between sessions on many systems, so don't put assets there.

WS="${BUILD_A_BRAND_WS:-$HOME/build-a-brand-workspace}"
mkdir -p "$WS/fonts" "$WS/images"

Use $WS/images/lifestyle1.jpg etc., and file://$WS/images/lifestyle1.jpg in HTML after resolving $WS to an absolute path. Build the final guidelines as a local HTML file or one generated HTML string; local paths are expected because rendering is local.

---

Step 1 — Generate Imagery (in parallel batches of 4)

You need a minimum of 10 generated images:

• 1 hero mood image (for the cover)
• 1 example image (for the photography rules page)
• 4 lifestyle images (for the visual world grid)
• 4 touchpoints images (for the real photos page) — adapt to brand type

That's 10 images. Run in parallel batches of 4 with & + wait. Never more than 4 at once (timeouts).

Before generating or placing those images, write a short crop plan and pre-generation slot plan for the deck. This is required working context, not final user-facing copy:

• Crop plan: for every generated image, name the destination page, slot aspect ratio, final pixel box, intended subject anchor (face/product/hands/object), expected object-position, and rounded frame risk. If rounded frame risk is high, use a softer radius, move the subject anchor lower/center, or regenerate for the actual slot ratio.
• Pre-generation slot plan: list every slot expected to show imagery, including destination page, slot aspect ratio, planned medium, and prompt intent. Do not invent asset URLs before generation.
• Post-generation filled manifest / image slot manifest: after image generation or upload, copy the final asset URLs/IDs into the same slot list and verify every planned slot is filled. The manifest must include the cover hero, imagery-rules example, visual-world grid, touchpoints grid, and the Digital / Social website hero, Instagram grid, and story template. Each required slot needs a real generated image or hosted image asset. Flat color rectangles count as empty unless the section is explicitly a palette specimen.
• The Visual World page must use real generated images that match the brand's medium. CSS color blocks, gradients, caption-only placeholders, and empty rectangles are not image assets.
• The Touchpoints page must use real generated photographs in believable physical or digital context. CSS color blocks, flat vector mockups, and captioned boxes are not substitutes for touchpoint photography.

Download generated image outputs into $WS/images, then compress before using in PDFs:

from PIL import Image
img = Image.open(path)
img.thumbnail((1200, 1200), Image.LANCZOS)
img.save(path, 'JPEG', quality=68, optimize=True)

Target under 150KB per page image where practical. Keep page images reasonably sized, avoid duplicating the same source across pages, and use CSS object-fit / object-position explicitly.

This is load-bearing for reliability: full-size gpt-image-2 PNGs are often 1.5-2.5MB each. Embedding them directly can inflate a guidelines PDF into tens of MB and trigger ASSET_FETCH_TIMEOUT while local/remote renderers fetch page images. For photographic page imagery, down-raster/downsample to the slot size and write JPEG files targeting about 85-180KB. Keep PNG only where transparency is required for logo/symbol assets.

Photography prompt template (lifestyle):

[Brand lifestyle direction — who, where, what they're doing, mood]. [Specific moment or activity]. [Environmental details — what's in the room, on the desk, in the background]. [Color temperature]. Film grain, natural light, slight imperfections, editorial composition. No studio strobes, no gradient backgrounds, no perfect symmetry.

Touchpoint prompt template (physical brand):

[Type of touchpoint — hang tag / woven label / kraft mailer / business card / signage]. [Brand visual cues — logo style, color]. [Real-world context — on a garment, on a desk, in a hand]. [Surface, light, color temp]. Editorial photography, film grain, natural light.

Touchpoint prompt template (digital brand):

[Type of touchpoint — phone screen / laptop / tote / sticker]. [Real-world context — in a hand, on a desk, on a water bottle, on a coffee shop table]. [Brand visual cues showing through]. Editorial photography, film grain, natural light.

Diversity rule: All lifestyle images with people must show a mixed cast across the 4-image grid: Black, Asian, Latina, South Asian, Middle Eastern, or mixed-race subjects. Vary body types. Never default to white/light-skinned subjects.

---

Image Generation — Hard Rules (Read Before Every Prompt)

These are the failure modes that have burned us before. Apply EVERY prompt.

0. Default provider: gpt-image-2

Every generate_image call must pass provider="gpt-image-2" unless the user explicitly names a different model. This is a global preference, not a per-skill rule. Don't default to nano-banana-pro (Gemini) — it has worse instruction-following for our brand work and bakes in text more aggressively. Use gpt-image-2 with quality="medium" for the default balance of speed and fidelity.

1. Never let text bake into the image

Every image model — gpt-image-2 included — WILL render text into generated images when you give them a reason to. Risk is highest when prompts mention "magazine cover," "editorial," "Bloomberg Businessweek," "Vogue," "TIME," "billboard," "poster," "book cover," any real publication name, or any framing that implies typography on the surface.

Every prompt must end with this guardrail (copy verbatim):

ABSOLUTELY NO TEXT of any kind in the image — no magazine titles, no logos, no watermarks, no captions, no typography, no brand names, no headers. Pure photograph only. No graphic design overlays whatsoever.

Never name real publications or brands directly in a prompt ("Bloomberg Businessweek cover," "looks like Vogue," "Anthropic launch film"). The model treats these as instructions to reproduce the publication's design — including its name. Instead, describe the visual qualities the brand evokes: "editorial close-up portrait with dramatic side light and quiet authority" rather than "Bloomberg Businessweek cover portrait."

2. Photo composition must survive the crop you'll use

Before writing the prompt, decide WHERE this photo will appear in the layout and what shape it will be cropped to. Generate a composition that survives that crop:

• Full-bleed landscape from 3:4 portrait source → subject must be in the vertical center 60% of the source. The top and bottom 20% will be cropped off.
• Arched / dome rounded frame (border-radius ≥ ½ of width) → DON'T use this shape unless the subject is in the LOWER center of the source. The dome will eat the entire top including any head. Default to soft 24-60px corner radius instead.
• Small landscape inset from 3:4 portrait source → subject must be in the horizontal center 70%. Sides will crop.
• Centered portrait subject → safest. Most layouts can preserve a centered head-and-shoulders composition.

Specify the subject's position in the prompt explicitly: "subject centered in frame, face occupying middle 50% of the image vertically."

3. Logos: generate a high-res symbol via gpt-image-2, ship as transparent PNG (no tracing)

Hand-coded SVG symbols often look amateur. But also: don't trace a generated symbol to SVG. Keep the symbol as a high-resolution transparent PNG. Only the wordmark gets vectorized in the brand kit.

1. Generate the symbol via generate_image with provider="gpt-image-2", quality="high" when final, 1:1 aspect ratio, 1024x1024 minimum. The symbol can be flat, dimensional, painted, photographic, gradient-rich, chrome, holographic, or hand-drawn when that style fits the brand.
2. Add the no-text guardrail: "absolutely no text, no letters, no typography, no words, no characters anywhere in the image."
3. The generated symbol must be conceptually linked to the brand, unique, recognizable at 16x16, no more than 3 dominant colors, high res for the shipped version, text-free, and true transparent background. If it fails any of these, regenerate.
4. Save as transparent PNG, verified with PIL. If gpt-image-2 paints near-white pixels in the "transparent" area, key them out or regenerate.
5. The wordmark is always real text in a Google Font or commercial font, never baked into a generated image. Convert the wordmark to text-as-paths SVG only when packaging the brand kit.
6. Lockup composition is measured and fixed: symbol size, wordmark size, gap, and alignment do not drift across color variants.

4. Verify by screenshot BEFORE delivering

After rendering ANY PDF or board, screenshot every page and read every screenshot. The QA checklist at the bottom of this doc is mandatory. Never deliver based on assumption that the layout worked. Specifically check:

• Are subjects visible (not cropped to forehead, hand-only, etc.)?
• Did baked-in text from the image generator appear anywhere?
• Are rounded shapes / arches cutting off content they shouldn't?
• Did object-position show the right portion of the image?

If anything looks wrong, fix it before delivering. Never ask the user to spot problems the agent should have caught.

---

Step 2 — Choose Fonts (Based on Brand Vibe)

Fonts are NOT hardcoded. Select fonts that match the identity built in Step 3 of the main skill. If the fonts could work for a competitor, pick different ones.

Before selecting final type, make a font shortlist for the identity:

• Include at least 2 display families and at least 2 body/accent candidates that fit the specific brand vibe.
• Do not reuse the same display/body pair from the last 3 brand briefs unless the user explicitly asks for that exact pairing.
• Pick the pair for this brief from the shortlist and state why it fits the brand's category, audience segments, and visual world.

Must Have Character — Don't Default to Safe Fonts

If the brand's display font could appear on any random SaaS site without anyone noticing, it's wrong. Push for fonts with recognizable personality.

Avoid as display defaults: Inter, DM Sans, Lato, Karla, Manrope, Outfit, Roboto, Open Sans, Source Sans, Helvetica, Arial. These can be fine as utility body fonts but have no point of view as a display face — they make every brand feel the same.

Explore the full Google Fonts library with intentionality. High-character options by vibe:

• Editorial / archival / literary → Fraunces (variable serif, sloped descenders), Instrument Serif (literary italic), Newsreader (newspaper character), Spectral, Cardo, Crimson Pro, Bodoni Moda (high contrast modern), EB Garamond
• Magazine / cover energy / bold display → Bricolage Grotesque (chunky variable), Big Shoulders Display, Familjen Grotesk, Karantina, Anton (when condensed is core), Funnel Display
• Friendly / soft / consumer-feeling → Funnel Display, Funnel Sans, Hanken Grotesk, Schibsted Grotesk, Geist, Hahmlet
• Tech / mono / digital-native → Reddit Mono, Geist Mono, JetBrains Mono, IBM Plex Mono, DM Mono, Space Mono, Fragment Mono
• Playful / loud / personality-forward → Honk (chubby 3D), Tilt Warp, Tilt Neon, Bagel Fat One, Caveat (handwritten)
• Quiet / minimal-with-soul → Public Sans, Hahmlet, Newsreader (light weights), Spectral (light weights)

Pairing rules:

• Display font must have character. Body font can be quieter but should still feel intentional.
• Never pair two characterless fonts (Inter + DM Sans = no point of view).
• Display + body should feel related but distinct.
• Test: if you swapped this brand's display font with another brand's display font from your last 3 projects, would anyone notice? If no — pick a more characterful one.

Decision Framework

Headline font feeling:

• Striking / loud / high-energy → bold condensed (Bebas Neue, Druk, Anton, Oswald, Archivo Black)
• Precious / archival / collected → elegant serif (Cormorant Garamond, Playfair Display, EB Garamond)
• Tech / app / digital-native → geometric sans (Space Grotesk, DM Mono, Syne, Monument Grotesk)
• Handmade / artisan / craft → warm serif (Libre Baskerville, Lora, Bitter)
• Clean / editorial / grown-up minimal → geometric humanist (Jost, Raleway, Josefin Sans)
• Playful / cute / youth → friendly rounded (Nunito, Poppins, Quicksand)

Body font must contrast with headline:

• Serif headline → clean sans body (Lato Light, DM Sans, Inter)
• Bold condensed headline → lightweight sans (DM Sans, Lato Light, Inter)
• Geometric sans headline → same family lighter weight, or Inter

Download fonts to the local workspace

Store font files under the same local workspace as the HTML and images, then reference them with absolute file:// URLs. Prefer direct WOFF2 font-file downloads from fonts.gstatic.com or other direct font-file sources.

WS="${BUILD_A_BRAND_WS:-$HOME/build-a-brand-workspace}"
mkdir -p "$WS/fonts"
curl -sL "https://fonts.gstatic.com/s/playfairdisplay/v40/nuFiD-vYSZviVYUb_rj3ij__anPXDTzYgA.woff2" -o "$WS/fonts/PlayfairDisplay.woff2"
curl -sL "https://fonts.gstatic.com/s/inter/v20/UcC73FwrK3iLTeHuS_nVMrMxCp50SjIa1ZL7.woff2" -o "$WS/fonts/Inter.woff2"

Use @font-face with local file sources:

@font-face {
  font-family: 'BrandDisplay';
  src: url('file:///Users/name/build-a-brand-workspace/fonts/PlayfairDisplay.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}
@font-face {
  font-family: 'BrandBody';
  src: url('file:///Users/name/build-a-brand-workspace/fonts/Inter.woff2') format('woff2');
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

Font loading rules:

• Use absolute file:// URLs in rendered HTML so local Chrome and WeasyPrint resolve the same files.
• Keep one local fonts/ folder per project and copy every chosen font into it before rendering.
• Do not use @import for render-critical type; explicit @font-face rules are easier to QA and reproduce.
• Do not put a Google Fonts CSS URL such as https://fonts.googleapis.com/css2?... inside @font-face src; that URL returns CSS, not a font file.

Render one page locally before the full PDF; if the type falls back to Times/Arial, fix the font source before continuing.

Font fallback for non-Latin brand names

When rendering CSS for a brand board, quick PDF, or full guidelines deck, every font-family chain must include CJK and broad-script fallbacks. Chromium applies per-glyph fallback: Latin characters use the first available brand font, while CJK, Arabic, Cyrillic, and other missing glyphs resolve to the matching Noto family instead of tofu boxes.

/* Body / sans-serif chains */
font-family: 'BrandBody', 'Inter', 'Noto Sans SC', 'Noto Sans TC', 'Noto Sans JP', 'Noto Sans KR', 'Noto Sans Arabic', system-ui, sans-serif;

/* Display / serif chains */
font-family: 'BrandDisplay', 'Bodoni Moda', 'Fraunces', 'Noto Serif SC', 'Noto Serif TC', 'Noto Serif JP', 'Noto Serif KR', 'Noto Sans Arabic', serif;

Load the Noto fallback faces with the same local strategy as brand fonts: download the relevant Noto files into $WS/fonts, then reference them through absolute file:// URLs in @font-face. This fallback belongs in shared CSS for every page, not only the page containing the brand name.

---

Step 3 — Build HTML

Write fresh HTML for the chosen identity. Never copy old deck HTML — always write fresh.

Critical CSS (required in every guidelines doc):

@page { size: 1200px 850px; margin: 0; }
.page { width: 1200px; height: 850px; overflow: hidden; page-break-after: always; display: block; }

Local Render Rules — Read Before Writing a Single Div

Local Chrome headless and WeasyPrint support flexbox, grid, absolute positioning, and CSS transforms well enough for these fixed-format pages. Keep page geometry explicit so QA is deterministic:

Rule 1: Every page is a fixed canvas

• Use @page { size: 1200px 850px; margin: 0; }.
• Every .page must be width:1200px;height:850px;overflow:hidden;page-break-after:always;position:relative;.
• Use explicit pixel dimensions for key regions. Flex/grid are fine, but don't let page height be content-driven.
• Avoid viewport units (vh, vw) inside pages; they couple layout to the browser window rather than the page box.

Rule 2: Use local assets deliberately

• Use absolute file:// URLs for local fonts, generated images, user-provided source images, and assembled logo assets.
• Download generated image outputs into $WS/images before placing them in HTML.
• Small SVGs and font subsets can be inlined as data: URIs when it improves portability.
• Avoid hotlinking external HTTPS assets in final render HTML; download, compress, and reference the local copy.

Rule 3: Use layout systems intentionally

• CSS grid is preferred for swatches, icon sets, mockup grids, type specimens, and contact sheets.
• Flexbox is fine for compact rows and centered stacks.
• Use absolute positioning for full-bleed editorial pages where overlap and crop are intentional.
• Give repeated tiles fixed dimensions so badges, labels, and icons cannot resize the layout.

Rule 4: Text containers must wrap naturally

• Text cards, sidebars, and copy columns must have an explicit readable width. Reserve at least 320px for body copy via min-width:320px, grid minmax(320px, ...), or an equivalent fixed px floor. You may use ch only as a max-width line-length cap, never as the width floor. Never let a right-column card collapse until each line becomes one word.
• In flex/grid layouts, set min-width:0 on text children so copy wraps inside its assigned track, and separately give the track/card a real width floor (width, flex-basis, or grid track minmax).
• Body-copy containers should include box-sizing:border-box; overflow-wrap:break-word; word-break:normal; hyphens:none;.
• Never use word-break:break-all, overflow-wrap:anywhere, or a narrow absolute-positioned card squeezed by an illustration/phone mockup for readable prose.
• If an illustration, phone, seal, swatch, or decorative element sits near a copy card, the card owns a clean rectangle above it in z-order and geometry. Do not depend on the visual QA pass to catch preventable overlap.

Rule 5: Image rules

• Always explicit px dimensions: style="width:300px;height:400px;object-fit:cover;display:block;"
• Avoid percentage heights unless the parent has an explicit pixel height
• Never opacity: on any <img> — images always at full opacity
• Never body text/labels/rules on images — put captions in an adjacent column or block. Masthead brand boards may overlay wordmark/tagline/issue metadata on a full-bleed photo only when the type sits on intentional negative space or a contrast scrim and passes contrast QA.
• Contrast QA for masthead overlays means the masthead text remains readable in the full-page PNG preview. If uncertain, render a local crop or full-page screenshot and judge the masthead wordmark/tagline/issue metadata at actual preview size before continuing.
• Never duplicate an image src across the deck — each file appears at most once
• Use object-position deliberately and verify the crop in PNG previews

Rule 6: Text contrast thresholds on dark backgrounds

On graphite (#2E2E2E) or any dark background:

• Body text minimum: rgba(248,243,236,.7)
• Sub-descriptions minimum: rgba(248,243,236,.55)
• Decorative / ghost text minimum: rgba(248,243,236,.45) — below this, remove the element entirely
• .3 opacity on dark = invisible. Never use for any visible text.

Rule 7: Page overflow prevention

• Every page is 850px tall. All content MUST fit.
• If a page has a headline >60px AND more than 3 body paragraphs, it will overflow. Cut or split.
• Never more than ~220 words of body text on a single page.
• Padding: 64px top/bottom max on content pages. Don't stack multiple padded sections.

Rule 8: Good-looking layout prevention

• Passing render QA is not enough. A page can have no clipped text and still be bad if it looks crowded, muddy, or amateur.
• Body copy, labels, and load-bearing informational text must never collide with swatches, icons, photos, decorative rules, grain, seals, or background imagery. If an element sits on top of body copy, the page fails even when the text technically remains inside its box. Masthead boards may overlay wordmark/tagline/issue metadata on a full-bleed photo only when the type sits on intentional negative space or a contrast scrim and passes contrast QA; body copy still gets its own clean reading area.
• Body copy on brand boards and guidelines must be readable at the full-page screenshot size. Use 18px minimum for body copy, 14px minimum for labels, and 10px minimum only for decorative metadata that is not load-bearing.
• Decorative microtype is optional. If small labels, faux archival notations, issue numbers, or specimen marks make the page noisy, remove them before reducing the real content.
• Keep one primary visual focal point per page while required board content stays secondary and grouped. If the viewer's eye has to choose between a huge wordmark, a dense paragraph block, six swatches, a seal, a photo, and a pull quote at once, simplify hierarchy and grouping; do not drop required content.
• Do not use a one-note dark brown/green/slate page unless the brief specifically demands it. Add contrast through scale, image light, accent color, or negative space; do not let the whole page collapse into one muddy value range.
• Empty placeholders are a hard fail. Website/social/app mockups are optional on brand boards; do not add them unless they contain real content. If a website hero, grid, story template, image slot, or app mockup is included, either render the real content or remove/redesign the slot. Flat color rectangles in a Digital/Social mockup count as empty placeholders unless the section is explicitly a palette specimen.

Rule 9: Vertical centering critical gotcha

When using <table><tr><td style="vertical-align:middle;"> to center, the inner content div must NOT have explicit height. If the inner div has height:782px (same as td), the td has nothing to center → appears top-aligned. Set height only on the outer <td>, never on the inner content div.

Reusable Templates

Two-column content page:

<div style="width:1200px;height:850px;overflow:hidden;page-break-after:always;display:block;background:#F8F3EC;">
  
  <table style="width:1200px;height:68px;border-collapse:collapse;border-bottom:1px solid rgba(0,0,0,.07);">
    <tr>
      <td style="padding:0 52px;vertical-align:middle;"><span style="font-size:9px;letter-spacing:.42em;text-transform:uppercase;color:#C4B49A;">01 — Section Label</span></td>
      <td style="padding:0 52px;vertical-align:middle;text-align:right;"><span style="font-style:italic;color:#C4B49A;">optional quote</span></td>
    </tr>
  </table>
  
  <table style="width:1200px;height:782px;border-collapse:collapse;table-layout:fixed;">
    <tr>
      <td style="width:480px;height:782px;vertical-align:top;padding:0;overflow:hidden;">
        <img src="https://..." style="width:480px;height:782px;object-fit:cover;display:block;">
      </td>
      <td style="width:720px;height:782px;vertical-align:middle;padding:52px;background:#2E2E2E;box-sizing:border-box;min-width:0;overflow-wrap:break-word;word-break:normal;hyphens:none;">
        
        <div style="max-width:560px;min-width:320px;box-sizing:border-box;overflow-wrap:break-word;word-break:normal;hyphens:none;">
          
        </div>
      </td>
    </tr>
  </table>
</div>

Full-bleed lifestyle grid (page 11):

<table style="width:1200px;height:782px;border-collapse:collapse;table-layout:fixed;">
  <tr>
    <td style="width:300px;height:782px;padding:0;overflow:hidden;"><img src="https://..." style="width:300px;height:782px;object-fit:cover;display:block;"></td>
    <td style="width:300px;height:782px;padding:0;overflow:hidden;"><img src="https://..." style="width:300px;height:782px;object-fit:cover;display:block;"></td>
    <td style="width:300px;height:782px;padding:0;overflow:hidden;"><img src="https://..." style="width:300px;height:782px;object-fit:cover;display:block;"></td>
    <td style="width:300px;height:782px;padding:0;overflow:hidden;"><img src="https://..." style="width:300px;height:782px;object-fit:cover;display:block;"></td>
  </tr>
</table>

This grid is image-only. If captions or labels are needed, put them in adjacent Rule-4 text containers; do not overlay body copy on the photos.

Touchpoints 2×2 grid (page 12):

<table style="width:1200px;height:782px;border-collapse:collapse;table-layout:fixed;">
  <tr>
    <td style="width:599px;height:390px;padding:0;overflow:hidden;"><img src="https://..." style="width:599px;height:390px;object-fit:cover;display:block;"></td>
    <td style="width:1px;background:#fff;"></td>
    <td style="width:600px;height:390px;padding:0;overflow:hidden;"><img src="https://..." style="width:600px;height:390px;object-fit:cover;display:block;"></td>
  </tr>
  <tr><td colspan="3" style="height:2px;background:#fff;padding:0;"></td></tr>
  <tr>
    <td style="width:599px;height:390px;padding:0;overflow:hidden;"><img src="https://..." style="width:599px;height:390px;object-fit:cover;display:block;"></td>
    <td style="width:1px;background:#fff;"></td>
    <td style="width:600px;height:390px;padding:0;overflow:hidden;"><img src="https://..." style="width:600px;height:390px;object-fit:cover;display:block;"></td>
  </tr>
</table>

This touchpoints grid is image-only. If a label is required, use a separate caption strip or adjacent Rule-4 text container; do not place readable prose inside the image cells.

Page-Specific Notes

Page 4 — Logo applications: Left half (~420px) = large logo mark centered with generous whitespace. Right half (~780px) = 5 CSS mockups in a 2-row grid (3 top, 2 bottom), gap:32px, each cell min 160×180px. Don't flex-wrap — use proper grid.

Page 5 — Logo Don'ts: 5 violation tiles in a row, each with the wrong-usage logo + a small ✗ label + a one-line caption explaining the violation.

Page 10 — Photography Rules: Left 2/3 (~780px) = 3 example images in a grid with explicit pixel dimensions. Right 1/3 (~420px) = sidebar of 4-5 specific rules (surface, light, propping, editing, mood). Small label caps + body text.

Page 12 — Touchpoints: The page must show real generated photos of the brand in context. Never substitute CSS vector mockups. Generate the 4 images before building HTML. For physical product brands: hang tag, woven label macro, kraft mailer, flat lay. For digital brands: phone in hand showing app, laptop on desk showing site, sticker on water bottle, tote bag in a real scene. For service brands: business card in hand, signage, branded notebook, swag.

Page 13 — Brand Applications (CSS mockups): Each mockup is a small physical-object representation rendered in CSS. Use fixed dimensions and verify the visual center in PNG previews.

Image hard constraints

• No opacity on images. Never opacity: on any <img> — full brightness always.
• No body text on images. Body copy, captions, labels, and rules never overlay images. Captions go in an adjacent column. Masthead brand boards may overlay the wordmark/tagline/issue metadata on a full-bleed photo only when the type sits on intentional negative space or a contrast scrim and passes contrast QA.
• No gradient overlays on ordinary content images. Do not use decorative gradient overlays on photos. Masthead covers may use one controlled linear scrim/gradient mask behind wordmark/tagline/issue metadata text to preserve contrast: strongest stop <= 50% opacity, one edge direction only, max scrim height <= 40% of image height, and no product/detail/focal subject hidden under the scrim.
• No CSS filter: / backdrop-filter: on raster images (color grade, sepia, saturate, brightness, contrast, hue-rotate, blur). A CSS filter on an <img> or on a background-image element forces the renderer's Chromium to rasterize that element to a full-resolution lossless bitmap inside the PDF — which silently defeats the JPEG downsampling above and explodes file size (one warm-graded mood-board page took a deck to 70 MB, past the upload cap). Bake any "warm grade" / tone treatment into the JPEG itself at generation/export time (regenerate with the look described in the prompt, or grade once in PIL when you img.save(..., 'JPEG', ...)), so the page HTML references a pre-graded JPEG with no live filter. The mood-board / visual-world page is already pre-graded imagery — it needs no page-level filter. The only filter still allowed is drop-shadow() on a transparent-PNG logo/symbol, which does not raster a photo.
• No duplicate images. Each image file appears at most once across the deck. If you run out, replace with typographic or color design elements (large CG italic quote, big page number, color field) — never reuse.
• Remove all price stickers / shelf labels / tags from products before use. If source has a Goodwill sticker or similar, regenerate clean.
• Header logo on every page uses the brand's actual logo font/style — never a generic fallback.
• Generated lifestyle images must match the brand's specific aesthetic — not just "editorial." Define surface/light/color-temp/prop-types per brand before generating. A warm cozy apartment is wrong for a gritty brand; harsh concrete is wrong for a quiet-luxury brand. Regenerate if it doesn't match.

---

Step 4 — Render PDF Locally

Preferred: Chrome headless. Chrome handles modern CSS, flexbox, grid, and @font-face file:// font declarations reliably when run locally. Use it when available:

CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
WS="${BUILD_A_BRAND_WS:-$HOME/build-a-brand-workspace}"
"$CHROME" --headless --disable-gpu --no-sandbox --hide-scrollbars \
  --virtual-time-budget=8000 --no-pdf-header-footer \
  --print-to-pdf="$WS/guidelines.pdf" \
  "file://$WS/guidelines.html"

Fallback: WeasyPrint. Use this only when Chrome is unavailable or the HTML was written to the table-safe constraints:

import weasyprint, warnings, os
warnings.filterwarnings('ignore')
WS = os.environ.get('BUILD_A_BRAND_WS') or os.path.expanduser('~/build-a-brand-workspace')
pdf = weasyprint.HTML(filename=f'{WS}/guidelines.html', base_url=f'file://{WS}/').write_pdf()
open(f'{WS}/guidelines.pdf', 'wb').write(pdf)

Pick one engine and stick with it for the whole 14-16-page build.

---

Step 5 — Verify Every Page (Mandatory)

Before delivery, render one full-page preview per page and verify against the QA checklist. JPG previews are fine for layout/contrast QA; PNG is required only for logo/symbol asset export.

For PDF-to-preview QA, use PyMuPDF:

import fitz, os
WS = os.environ.get('BUILD_A_BRAND_WS') or os.path.expanduser('~/build-a-brand-workspace')
doc = fitz.open(f'{WS}/guidelines.pdf')
for i in range(len(doc)):
    doc[i].get_pixmap(matrix=fitz.Matrix(1.8, 1.8)).save(f'{WS}/qa_p{i+1}.png')
print(f'{len(doc)} pages — now read each one')

Pre-Send QA Checklist

Read every screenshot. Verify every item. If any check fails, fix it. No exceptions. Never ask the user to spot problems the agent should have caught.

Cost rule — QA must scale with page count, not element count. Read ONE full-page preview per page (14-16 reads). Do NOT crop-and-read every small element on every page by default. The full-page read is the default; targeted zoom is the exception, not the rule.

Full-deck visual QA: every final guidelines page must receive a local full-page preview read before delivery. Record PASS or FAIL per page, fix every captured fail, and do not deliver the PDF until all included pages are clean or the user explicitly accepts a documented degraded quality warning.

Per-page QA (mandatory — one full-page read per page):

1. Full-page pass — read the full-page PNG for each page and verify it against the checklist below (blank columns, missing content, wrong colors, font fallback, text/image collisions, clipped text, weak hierarchy).
2. Target detail-level QA only where needed — use local crops for flagged defects or the few highest-risk elements. Fix every captured FAIL.

Targeted zoom — only when triggered. Crop and read an 800×800px region ONLY for:

• a specific element the full-page read flagged as suspect, OR
• the few genuinely highest-risk spots, when the page contains them: a single-character pill/badge marker, a favicon-size (≤32px) logo rendering, or a business-card layout.

Do not zoom every element on every page. Zoom the flagged ones. A clean full-page read with no blocking defects is sufficient to clear a page.

Only deliver after all checks pass.

---

Step 6 — Deliver

Save the final PDF to ~/Desktop/[brand-slug]-brand-guidelines.pdf and send the local path in a single message. Do not upload or host the PDF unless the user explicitly asks for a hosted copy.

Reply shape:

**[BRAND NAME] — brand guidelines**
Saved to: ~/Desktop/[brand-slug]-brand-guidelines.pdf ([actual page count] pages · 1200×850)

If the user is not on a Mac, save to the project working directory and emit that path instead. Never attach the PDF as a file in the chat; link by path.

Done.

---

Image Concept Must Connect to the Brand Metaphor (Don't Default to "Person Doing X")

Before generating any image, identify the brand's central metaphor — the verb or noun the brand keeps returning to. For DeltaStream → "stream" (water, motion, flow, time). For a coffee brand → "ritual" (steam, pour, slow). For a sleep app → "rest" (stillness, breath, dark warmth).

Then, for each direction, propose a visual concept that USES that metaphor in a FRESH way. The most common failure mode is defaulting to "person at desk" or "person using product" three times in a row. That looks stocky and unbranded — three engineers at three desks, even with different palettes, reads as three variations of the same image.

Steps to follow every time

1. Name the brand metaphor. Write it down (e.g. "stream = flow / motion / time / water").
2. For each of the 3 directions, brainstorm 3 different image concepts that use the metaphor through a different medium or subject. Pick the most ownable.
3. Vary the medium across the 3 boards. Mix:
   • Photographs (documentary / editorial / macro / long-exposure / portrait / still life)
   • Illustrations (flat vector, line art, gradient, isometric, geometric)
   • Abstract compositions (typographic posters, color fields, motion studies)
   • Architectural / environmental shots
4. Specify the medium AND the concept in the prompt. "Flat vector illustration of..." vs. "Editorial macro photograph of..." vs. "Long-exposure photograph of...".

Examples (for a "stream" brand)

• Cover Story (bold manifesto) → Editorial macro photograph of glowing amber liquid frozen mid-pour, single dramatic light. Stream metaphor = literal liquid stream, captured in a moment.
• First Light (soft consumer) → Flat vector illustration of a stylized sunrise over geometric waves in butter yellow and cream. Stream metaphor = waves of light + flow.
• Slow Burn (quiet editorial) → Long-exposure photograph of city traffic light trails on a wet dark street at night, rust tail lights as the only accent. Stream metaphor = streams of light through time.

Three different MEDIUMS (macro photo / vector illustration / long-exposure photo). Three different SUBJECTS. All rooted in "stream" but used distinctly. None of them are "person doing X."

When illustration beats photography

Default to illustration (over photography) when:

• The brand is consumer-feeling, app-like, or has Bumble/Notion/Pika DNA → flat illustration reads warmer and more ownable than stock-photo people
• The concept is abstract or symbolic (a feeling, a state, a moment) — illustration can render concepts photography cannot
• The brand has a strong color palette and you want it to dominate the image — illustration controls color absolutely
• The aesthetic is playful, soft, or geometric — photography would feel like a mismatch

Default to photography when:

• The brand is editorial, archival, premium, or grown-up
• The concept is tactile (an object, a material, a texture)
• The mood is documentary or quiet (Frank Ocean / Anthropic territory)

What NOT to do

• Three "person at desk" with different palettes
• Three "person using product" with different lighting
• Three "engineer at laptop" — the stock photo zone
• Defaulting to portraits when an object, illustration, or abstract composition would say more
• Generating photography when illustration would serve the brand better

---

Icons Page — Structure & Rules

Page 8 defines the brand's UI icon system. Every digital brand needs one — even non-tech brands benefit from consistent icons for navigation, social, and product surfaces.

Page layout

• Header bar (standard section label + page num + brand symbol)
• Headline (top): a 38-44px brand-styled headline like "Icons" or "A consistent UI language"
• Rules block (left third, ~380px):
  • Stroke weight — e.g. 1.5px / 2px / 3px based on brand character (thinner = editorial / refined; thicker = friendly / consumer)
  • Corner radius — sharp / soft 2px / round 4px / fully rounded
  • Line caps — round / butt / square (round for friendly brands; butt for technical/precise)
  • Style — outline / filled / two-tone / mixed
  • Grid — 24×24 base / 32×32 base (24 is standard; 32 for larger UI)
  • Stroke ends / corners consistency — same treatment across all icons
• Icon grid (right two-thirds): 4×3 grid of 12 icons, each in a ~120×120px tile
• Bottom note: library recommendation for icons beyond the set — e.g. "Use Phosphor Light for any icon not in this set" or "Use Lucide at 1.5px stroke."

The 12 essential UI icons

Every brand's icon set should include at minimum:

These cover 80% of UI needs. Brands with specific product features can add 2-4 product-specific icons (e.g. a streaming brand might add a "live" indicator; a finance brand might add "card" / "wallet").

Stroke style choice by brand vibe

• Bold editorial / display-heavy brand → 2-2.5px stroke, sharp corners, butt line caps. Looks intentional and precise.
• Friendly / consumer / Bumble-Pika DNA brand → 2px stroke, soft 2-3px corner radius, ROUND line caps. Looks warm and approachable.
• Technical / dev-tool brand → 1.5px stroke, sharp corners, butt caps. Looks precise like the rest of the brand.
• Editorial / quiet / Anthropic-Modal brand → 1.5px stroke, sharp corners, butt caps. Reads as refined.
• Playful / heavy display brand → 2.5-3px stroke, round corners, round caps. Echoes the chunky type.

Pick the stroke style at the same time as the brand's identity, and apply it consistently across all 12 icons.

Rendering each icon

Each icon is a 24×24 viewBox SVG with the brand's chosen stroke weight and corner style. Example structure (for arrow-right at 1.5px stroke, sharp corners, butt caps):

<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="butt" stroke-linejoin="miter">
  <path d="M5 12 L19 12"/>
  <path d="M13 6 L19 12 L13 18"/>
</svg>

Use currentColor for the stroke so the icon adopts the surrounding text color (essential for color-flexible UI usage).

What goes in the brand kit

A /icons/ folder containing all 12 (or more) icons as SVG files:

• icons/arrow-right.svg
• icons/check.svg
• icons/close.svg
• icons/plus.svg
• icons/search.svg
• icons/user.svg
• icons/settings.svg
• icons/bell.svg
• icons/menu.svg
• icons/info.svg
• (etc — full set used on page 8)

Each SVG with stroke="currentColor" so it inherits color from the application context.

---

Imagery Rules Page — Adapts per Brand

Page 10 of the guidelines defines the brand's imagery rules. Its title and content adapt to whatever medium the brand actually uses — don't ship a "Photography Rules" page for an illustration-led brand and don't ship "Illustration Rules" for a brand that lives in photos.

How to decide which page(s) to build

Look at the chosen identity option's specs (set in Step 3) and the lifestyle world you've defined:

Photography Rules page structure

If the brand uses photography:

• Subject — who/what is in the frame (real engineers / hands at work / still life / etc.)
• Light — direction, quality, time of day
• Color — grade, palette tones preserved, anything muted
• Cast / diversity — explicit rule that lifestyle images with people show racial diversity across the set
• Texture — film grain, composition style, off-center editorial framing
• Forbidden — stock-photo energy, studio strobes, perfect symmetry, AI-smooth surfaces, gradient backgrounds
• One example image filling 2/3 of the page (real generated photo in the brand's photo style)

Illustration Rules page structure

If the brand uses illustration:

• Style — flat vector / line art / geometric / hand-drawn / 3D render / collage / mixed. Be specific (e.g. "flat vector with no realistic detail" not just "illustrated").
• Color — how brand colors apply to illustrations (large fields vs accent dots; how many colors per illustration; palette restraint)
• Line / stroke — stroke weight rules (uniform 4px / varied / no strokes); corner radius (rounded / sharp); line caps (round / butt / square)
• Character — what the illustrations feel like (friendly / precise / playful / archival / geometric / organic). Match the brand's overall voice.
• Composition — asymmetric / centered, generous negative space / dense, rule-of-thirds / centered subject
• Subject matter — what the illustrations DEPICT (scenes / objects / abstract patterns / characters / metaphors). Tied to the brand metaphor.
• Forbidden — what kills the style (realistic detail in a flat-vector brand, gradients in a flat-color brand, drop shadows, photo textures, generic stock-illustration style, AI-uncanny features)
• One example illustration filling 2/3 of the page (real generated illustration in the brand's style)
• Reference brands' illustration — 2-3 brands whose illustration style is close (e.g. "like Notion's homepage illustrations but a notch more grown-up")

Visual World page (page 11) also adapts

The 4-image lifestyle grid on page 11 should match the brand's medium mix:

• All-photo brand → 4 photos
• All-illustration brand → 4 illustrations (varied scenes, not 4 of the same composition)
• Hybrid → mix of photos and illustrations in the proportions that match the brand world (e.g. 3 photos + 1 illustration if photography dominates)

---

Avoid Concept Clichés — The First Metaphor Is Always Wrong

The strongest image concepts come from the SECOND or THIRD thing you think of, not the first. The first metaphor is what every stock photography library has been selling for 20 years. If a concept makes you go "yeah, that captures the idea" — pause. Did you actually invent it, or are you reaching for a familiar trope?

Banned cliché concepts

Never use any of these. They read as stock and weaken every brand they appear in:

• Hourglass / sand falling for time, urgency, deadlines
• Lightbulb glowing for ideas, innovation
• Chess pieces for strategy, decisions
• Jigsaw puzzle pieces for fit, integration
• Climbers reaching the summit / mountain peak silhouette for ambition, success, leadership
• Runner crossing a finish line for achievement
• Handshake for trust, partnership, deals
• Sunrise / sunset for new beginnings (used to be fresh, now stock — though abstract sunrise illustrations can still work in consumer brands)
• Compass or map alone for direction, navigation
• Rising graph line / arrow going up for growth
• Open road / horizon stretching into distance for vision
• Ocean waves / endless vastness for scale
• Tangled vs. straight cables for organized vs. chaotic
• Glowing network nodes connecting for connection (especially in AI/tech)
• Magnifying glass over numbers/charts for analysis
• Brain made of circuit board / glowing brain for AI / intelligence
• Domino chain falling for cascading effect
• Tree growing from a coin for investment growth

If you find yourself reaching for any of these — STOP. Brainstorm three more concepts. The third one is usually right.

Three tests for whether a concept is cheesy

1. The Wikipedia test — could this concept be the lead image on Wikipedia's article for the abstract noun your brand cares about? "Hourglass" is literally Wikipedia's image for "Time." That's why it's cliché.
2. The Shutterstock test — search Shutterstock for the keyword. If the top 20 results all look like your concept, you've picked the trope, not a fresh image.
3. The 4-other-brands test — could 4 brands in unrelated industries use this exact image and have it mean something to each of them? (Hourglass: works for time-tracking software, project management, dating apps, history museums, fitness apps — that's the giveaway.)

If a concept fails any of these three tests, regenerate.

Substitutes that work

Trade the obvious metaphor for something specific, indirect, or documentary:

Pattern: trade the SYMBOL for the SCENE. Trade the OBJECT for the MOMENT. Trade the METAPHOR for the DOCUMENTARY.

The cringe test (run before delivering)

After generating, ask: "If I saw this image without knowing the brand, would I cringe slightly?" Stock-photo cringe is subtle — it doesn't scream "BAD IMAGE." It quietly says "this brand reached for the obvious symbol." If even slightly cringe — regenerate.

---

Photography Must Occupy Distinct Visual Territories

Each of the 3 mood images on the brand board must show a genuinely different visual territory — not three variations on the same subject. If all 3 images are "engineer at desk with laptop" with slightly different color grading, the photography has failed. The user reads three identical concepts and concludes the directions aren't really different.

Think of each option as a different MOVIE GENRE, each with its own:

• Subject matter — what's actually in the frame (portrait? still life? interior? hands at work? landscape?)
• Setting — where the brand lives (office? home? kitchen? after-hours desk? outdoors? abstract space?)
• Scale — close-up portrait vs. wide environment vs. tight still life vs. mid-shot
• Time of day — morning sun vs. midday vs. golden hour vs. midnight
• Human presence — is a person the subject, an element in the composition, or absent entirely?

Examples of structurally distinct territories

For a brand with 3 directions (magazine-cover / consumer-warmth / editorial-quiet):

• Magazine-cover → close-up editorial PORTRAIT, single subject lit dramatically with one strong directional source, Bloomberg Businessweek cover energy
• Consumer-warmth → domestic STILL LIFE or hands in a real environment, no laptops or screens, golden hour, the LIFE around the work (kitchen, couch, sketchbook, market)
• Editorial-quiet → atmospheric STILL LIFE on a dark surface, single objects in moody pool of warm light, often no person visible, Frank Ocean Blonde sparseness

For a different set of directions, the territories would be entirely different — the rule isn't "always do portrait + kitchen + still life," it's "find three structurally distinct territories that match each direction."

What NOT to do

• Three engineers at three desks with three different color casts
• Three close-ups of hands on three different keyboards
• Three "person at laptop in coffee shop" with different lighting
• Any variation where you swap one word in the prompt and re-run with a different palette

Each prompt should be structurally different: different subject, different setting, different scale, different mood. Color grading is the LAST differentiator, not the first.

---

Brand Board Layout — Differentiate per Option (Step 3 Preview)

Critical rule for the 3-page brand board preview built in Step 3 of the main skill: do NOT use the same template for all 3 boards recolored. Each board's layout must physically embody its option's design philosophy. If you can swap colors and fonts and the layouts feel identical, the board has failed — viewers read the differences as cosmetic, not structural.

Each brand board must answer: what would this brand's actual hero page look like? Build the answer.

Examples of differentiated layouts

Magazine-cover brand — Full-bleed photo as background covering the entire page. Massive wordmark overlaid in display type. Tagline overlaid in small text. Issue/edition tag in corner ("Vol. 01 / Cover Story"). Bottom-margin strip showing color swatches and typography credit, like a magazine masthead. Whole page should look like a Bloomberg Businessweek or NYT Magazine cover.

Soft consumer-brand homepage hero — Asymmetric split with a curved or rounded shape break between colored side and cream side. Big rounded type on one half, photo with rounded corners on the other. Color swatches presented as soft circles, not squares. Lots of breathing room. Should feel like the hero of bumble.com or pika.me.

Editorial / literary essay — Bone or cream full-bleed background. Massive italic display type centered with extreme whitespace. Photo as a small inset rectangle, not full-bleed. Pull-quote on the margin. Color swatches as a tiny ribbon at the bottom. Should feel like the opening page of a Frank Ocean visual essay or an Anthropic announcement.

Tech-doc / dev-tool aesthetic — Monochrome grid. Tight type. Code-like layout with bracket marks or syntax highlighting. Mono font everywhere. Color swatches as inline code blocks with hex strings. Should feel like Stripe's docs or GitHub's changelog.

Required content per board (regardless of layout)

Every brand board page must include ALL of the following. The layout differentiation rule above does NOT mean cutting content — visually distinct layouts must still fit ALL the text. If a layout doesn't have room for the content, redesign the layout, don't drop content.

• Brand wordmark (set in the brand's display font)
• A standalone logo symbol/mark — generated as a transparent PNG via generate_image with provider="gpt-image-2" when new. Do not trace the generated symbol to SVG and do not claim it is vector. NOT just typography. The symbol must work as a favicon, app icon, social avatar, and exported asset on transparent background at 1024×1024+.
• A distinctive wordmark and any seal/badge treatment — custom letter spacing, ligature/cut/terminal detail, stamp geometry, or other ownable touch. Not just a Google Font in a circle, not a generic monogram seal, and not decorative filler.
• Tagline
• Voice sample (one sentence in brand voice, quoted, with a "VOICE" label)
• Brand story (~35 words max, min 2 sentences, one compact paragraph in brand voice)
• Lifestyle world description (~22 words max, min 1 full sentence describing the brand's visual territory — where it visually lives, who's in the frame, time of day, color temperature) — labeled "WORLD" or similar
• Lifestyle mood image (generated via gpt-image-2 — see "Photography Must Occupy Distinct Visual Territories" rule below)
• 4-color palette with hex codes + role labels
• Display + body type specimens with named fonts

Content budgets per board

The board is a visual decision aid, not the final brand book. Keep each board sharp enough to sell the direction at a glance:

• Tagline: 8 words max.
• Voice sample: 14 words max.
• Brand story: 35 words max, min 2 sentences. Use one compact paragraph, not 2-3 full paragraphs.
• World description: 22 words max, min 1 full sentence.
• Palette: 4 colors max on the board. Full extended palettes belong in the final guidelines.
• Type specimen: one display sample and one body sample. Do not add full hierarchy tables to boards.
• Essential body copy: 18px minimum. If it needs to be smaller to fit, rewrite the copy.

If all required content cannot fit within those budgets, the content is too verbose for a board. Rewrite it; do not shrink, stack, or layer it until it becomes technically present but visually bad.

What NOT to do

• Same left-column-color-block-right-column-photo template recolored 3 times
• Same swatch grid in the same position on every page
• Same type specimen "Aa" treatment on every page
• Three different colors and three different fonts laid onto identical layouts
• Wordmark with no separate symbol — the logo isn't complete without a mark
• Dense archival/specimen styling where decorative rules, labels, swatches, and paragraphs intersect. If it looks like a broken certificate rather than a brand board, simplify.
• Body copy crossing through color swatches, icons, seals, or decorative overlays. Text must own a clean reading area.
• Empty mockup boxes or blank social grids. A placeholder reads as missing output, not restraint.
• Full boards that are almost entirely one muddy value range. Use image light, accent color, or negative space to create hierarchy.
• Asymmetric rounded corners on color blocks (e.g. only border-top-left-radius on a big shape) — these read as a clipping bug, not a design choice. If you want softness, use symmetric rounded corners (whole left edge rounded, or all four corners rounded), a clean rectangular split, or a deliberately organic shape via SVG/clip-path. Half-rounding a single corner of a big block looks like a mistake every time.
• Inline pill backgrounds on display text (40px+) — they overlap into adjacent lines because line-height is usually tighter than the rendered character box. A background: var(--color); padding: 0 12px; border-radius: 12px; on big headline text WILL bleed into the line above or below. Two safer options:
  1. Highlighter-underline gradient (recommended): background: linear-gradient(to bottom, transparent 0%, transparent 58%, var(--accent) 58%, var(--accent) 92%, transparent 92%); padding: 0 6px; -webkit-box-decoration-break: clone; box-decoration-break: clone; — creates a marker-highlight band that only occupies the bottom of the line, never extends beyond.
  2. Just change the text color (color: var(--accent)) — simplest, no overlap risk. Never use solid pill backgrounds on display text unless you've also set generous line-height (1.4+) AND tested the actual render.
• Pill/badge containers with text inside (numerals like 01, 02, markers like + or ×, single letters) — never style them with padding + text-align: center and expect the text to look vertically centered. Font glyphs sit on a baseline with empty space above and below, so padding alone leaves the character looking top-shifted with empty space underneath. Always use display: inline-flex; align-items: center; justify-content: center; with EXPLICIT width and height — let the flex container center the text. Skip padding. Skip text-align: center (it only handles horizontal). The text will sit visually centered regardless of font metrics.

If you can't physically tell which brand you're looking at without reading the labels, regenerate.

---

Quality Bar

• Feels like a $5,000 brand studio deliverable — not a template, not a Canva export
• Every page should feel like a deliberate design decision was made
• Typography used boldly: headlines at 80–160px as graphic elements, not just labels
• Color used intentionally: full-bleed color blocks, not just colored text
• Negative space is a design tool — don't crowd every page
• Hierarchy must be obvious: display → subhead → body at dramatically different sizes
• Voice page shows actual brand copy, not generic example text
• Touchpoints page shows real generated photos — never CSS vector boxes
• No placeholder text, no [BRACKETS], no repeated images anywhere

---

Supporting file: references/brand-identity.md

Brand Identity Options — Reference

Each identity option is a complete creative package. When presenting 3 options, make them genuinely different in name personality, color mood, and voice — not just palette swaps.

Structure for Each Option

### Option [1/2/3]: [Brand Name]
**Tagline:** [Short punchy line — 8 words max]

**Colors:**
- [Name]: #[hex] (role: primary/accent/background/text)
- [Name]: #[hex]
- [Name]: #[hex]
- [Name]: #[hex]

**Typography direction:** [e.g. "Serif headline with clean sans-serif body — editorial and grounded"]

**Voice & tone:** [3-4 adjectives] — [One example sentence in the brand's voice]

**Logo concept — wordmark + symbol + lockup:**

A complete brand identity has BOTH a wordmark and a symbol — they're different things doing different jobs:
- **Wordmark** = the brand name in its identifying typeface. Used wherever there's room (web header, business card, packaging).
- **Symbol** = a standalone graphic mark that lives WITHOUT the wordmark. Used for app icon, favicon, social avatar, browser tab — anywhere the wordmark is too long.
- **Lockup** = how the two combine (horizontal, stacked, symbol-only).

### Logo Pipeline — generate a high-res symbol via gpt-image-2, ship it as transparent PNG (no tracing)

Do not write hand-coded SVG paths for a rich brand symbol, and do not trace a generated symbol to SVG. Keep the symbol as a high-resolution transparent PNG. Only the wordmark gets vectorized in the brand kit.

1. Generate the symbol via `generate_image` with `provider="gpt-image-2"`, `quality="high"` for final, 1:1 aspect ratio, 1024x1024 minimum.
2. Style follows the brand: flat, dimensional, glossy, painted, photographic, chrome, hand-drawn, etc. Neither flat nor 3D is the default.
3. The prompt must include: "absolutely no text, no letters, no typography, no words, no characters anywhere in the image."
4. Save the approved symbol as a 2048x2048 transparent PNG with true alpha verified by PIL.
5. Wordmark = real font rendering, never baked into the image. Convert the wordmark to text-as-paths SVG in the kit.
6. Lockup measurements are fixed: symbol size, wordmark size, gap, and alignment do not drift across color variants.

### Symbol output rules

Every generated symbol must satisfy all of:
- Conceptually linked to the brand/product.
- Unique enough that it would fit only this brand.
- Recognizable at 16x16 favicon size. Test by resizing to 16x16 with LANCZOS, then upscaling to 128x128 with NEAREST and reading the result.
- No more than 3 dominant colors.
- High resolution, with 2048x2048+ master when shipped.
- No text inside the image.
- True transparent background.

If the output has text, too many dominant colors, fake transparency, or fails the 16x16 test, regenerate.

**Whether to generate new ones depends on what the user has:**
- If the user has an existing wordmark or symbol they like — USE it. Document the existing asset in the guidelines.
- If the user is asking for a new logo, or has said they don't like their current one — propose a new wordmark and/or symbol as part of the identity option.
- If the user has a wordmark but no symbol — propose just the symbol. Brands need a non-typographic mark for app icons, favicons, etc., so a symbol is worth proposing even when the wordmark is kept.
- Whatever the source, document BOTH in the guidelines. They're both part of complete brand documentation, even when only one is new.

For each identity option, fill in:
- **Wordmark:** [How the brand name is typeset — typeface choice, custom letter treatment, spacing, ligature/cut/terminal detail, and lockup rhythm. Reference existing if kept; describe new if proposed. A wordmark is not just a Google Font typed in a brand color.]
- **Symbol / mark:** [The standalone graphic mark — shape, reference, what it evokes. Generated via gpt-image-2 when new, shipped as transparent PNG, NOT traced to SVG. Must read at 16x16 AND 512x512. Reference existing if kept; describe new if proposed.]
- **Lockup:** [How wordmark + symbol combine — horizontal (symbol left, name right), stacked (symbol above name), symbol-only at small sizes.]

**Brand story:**
[2-3 sentences for the About page. Written in brand voice. Real copy, not a template.]

Board-preview copy is intentionally shorter: when this story appears on the 3-option brand board, rewrite it to the board budget (~35 words max, min 2 sentences, one compact paragraph). The 2-3 sentence version belongs in the text option/About-page snippet, not the preview board. For the full guidelines foundation page, expand the story to 2-3 paragraphs of real copy in brand voice.

**Product / hero subject photography direction:**
[How the main subject of brand photography should look — for product brands: the product itself.
For service / app / community brands: the hero subject of the brand (the person using it, the
moment it serves, the artifact it produces). Be specific: surfaces, lighting, props, mood,
composition. 1-2 concrete reference descriptions (e.g. "like a Sunday farmers market table"
or "like a quiet morning before anyone else is awake").]

**Lifestyle photography direction:**
[The full visual world beyond the hero subject — what does the life around this brand look like?
Include: what environments (homes, outdoor spaces, markets, studios, offices), what kind of
people and how they're styled, what activities and moments feel on-brand, color temperature
and mood of the world, what the brand's customer looks like when they're living their life.
This should paint a complete picture someone could cast and art-direct a shoot from.]

**UI / website art direction:**
[What will the brand's digital presence actually look like? Include: layout feeling (spacious/dense,
editorial/grid), background colors, how text and images are balanced, button style (minimal/bold),
how navigation feels, any special layout details (full-bleed images, whitespace-heavy, etc.),
and overall digital mood. Reference a real website aesthetic if helpful
(e.g. "like Mejuri — very white, generous whitespace, product does the talking")]

**Example brands:**
[3-4 real existing brands that live in a similar world — not competitors, but brands that share
the same energy, customer, or aesthetic. Helps the user immediately understand the territory.
Can be fashion brands, lifestyle brands, tech brands, Instagram accounts, or cultural references.
e.g. "Entireworld, Rowing Blazers, Madhappy — brands with a strong POV and a loyal community"]

Visuals (Required)

After presenting all 3 identity options in text, render a 3-page brand board PDF (one page per option, 1200×850 each) so the user can see each identity before committing. Do not generate generic AI "mood board" images — they look stocky and bad.

How to generate:

Build one self-contained HTML file per option, render each to PDF locally via Chrome headless, then merge into a single 3-page PDF. Each page MUST have a layout that physically embodies its option's design philosophy.

WS="${BUILD_A_BRAND_WS:-$HOME/build-a-brand-workspace}"
mkdir -p "$WS/boards"
CHROME="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

for i in 01 02 03; do
  "$CHROME" --headless --disable-gpu --no-sandbox --hide-scrollbars \
    --virtual-time-budget=8000 --no-pdf-header-footer \
    --print-to-pdf="$WS/boards/$i.pdf" \
    "file://$WS/boards/$i-"*.html
done

pdfunite "$WS/boards/01.pdf" "$WS/boards/02.pdf" "$WS/boards/03.pdf" "$WS/boards/brand-boards.pdf"

for i in 01 02 03; do
  "$CHROME" --headless --disable-gpu --no-sandbox --hide-scrollbars \
    --virtual-time-budget=8000 --window-size=1200,850 \
    --screenshot="$WS/boards/qa-$i.png" "file://$WS/boards/$i-"*.html
done

Read every PNG preview before sending the PDF path to the user. The check is not only "does it fit?" It must also look like a good brand board: one primary visual focal point with supporting required content grouped clearly, readable text, no empty placeholders, no muddy one-note palette, and no body copy intersecting decorative elements.

Each page MUST have a layout that physically embodies its option's design philosophy (not three template recolours — see brand-guidelines.md "Brand Board Layout — Differentiate per Option" for rules and examples).

Assets in the HTML should be local files under $WS/images and $WS/fonts, referenced via absolute file:// paths. Download generated image outputs before rendering.

Delivery: save $WS/boards/brand-boards.pdf to ~/Desktop/[brand-slug]-brand-boards.pdf and emit the local path. Do not upload or host the PDF unless the user explicitly asks for a hosted copy.

Design rules for each board:

• Each option panel uses its own background color from that option's palette
• Brand name displayed large in that option's display typeface (loaded via local @font-face file:// from $WS/fonts/)
• Color swatches shown as circles or rectangles with color names beneath
• Typography is clean and editorial — no generic fonts (no Inter / Karla / DM Sans default)
• Layout philosophy differs per board — a tabloid board looks like a newspaper, a fashion-house board looks like a lookbook spread, an archival board looks like a book frontispiece. See brand-guidelines.md "Brand Board Layout — Differentiate per Option" for the differentiation rule and brand-guidelines.md "Required content per board" for the per-page checklist.
• No generic AI mood-board collages. Each board may use one purpose-built gpt-image-2 mood image and one generated PNG symbol when that is the strongest logo route. No AI app mockups, AI product mockups, or extra AI filler assets.
• The whole thing should look like something a real brand studio would produce

Board copy budgets:

• Tagline: 8 words max.
• Voice sample: 14 words max.
• Brand story: 35 words max, min 2 sentences.
• World description: 22 words max, min 1 full sentence.
• Body text: 18px minimum. Labels: 14px minimum unless purely decorative.
• If copy needs to be smaller than that, rewrite. Do not shrink, layer, or cram until the board technically contains everything but looks bad.

Quality Bar

• Names: Should be memorable, say-able, and googleable. Avoid made-up words unless they're genuinely good.
• Colors: Give them real names (not "Dark Blue" — try "Ink", "Dusk", "Bone"). Specify roles.
• Voice examples: Write an actual sentence in the brand's voice (a headline, a button label, an error message), not a description of the voice.
• Logo concepts: Cover BOTH wordmark and symbol in every identity option — they're different things doing different jobs. Describe each visually — shape, reference, style. What you GENERATE depends on what the user has: use existing assets if the user wants to keep them, propose new ones if the user needs a logo or doesn't like their current one. For a new symbol, use gpt-image-2 with a transparent-background, no-text prompt and ship the symbol as PNG. If the user has a wordmark but no symbol, still propose a symbol — favicons and app icons need a non-typographic mark.
• Fonts must have character. Don't default to Inter / Karla / Outfit / DM Sans / Lato — they have no point of view. Explore the full Google Fonts library. See brand-guidelines.md "Font Selection — Must Have Character" for approved high-character options.
• Brand story: Should make someone feel something. Name the founder's origin if appropriate.

Example Identity Option

Option 1: Thread & Tide

Tagline: Made slowly. Worn forever.

Colors:

• Bone: #F5F0E8 (background)
• Sienna: #C2714F (primary)
• Bark: #6B4F3A (text/accent)
• Sage: #8A9E85 (secondary accent)

Typography direction: Soft serif headlines (elegant, unhurried) with minimal sans-serif body text.

Voice & tone: Warm, specific, unhurried, honest — "Each clasp is set by hand, so yours might be slightly different from the photo. That's the point."

Logo concept — wordmark + symbol:

• Wordmark: The brand name in a loose, hand-drawn serif. All-caps with light tracking. Slightly imperfect, like a signature.
• Symbol / mark: A small monogram T&T inside a hand-drawn circle, like a maker's hallmark stamped into clay. Used as the standalone identity at app-icon size.
• Lockup: Wordmark above symbol-circle for primary lockup; symbol-only at small sizes (favicon, avatar).

Brand story: Thread & Tide started on a kitchen table in 2021, when beads that were supposed to be a birthday gift turned into a small obsession. Every piece is made in small batches — no two exactly alike. We make jewelry for people who want something that feels like it was made for them. Because it basically was.

Product / hero subject photography direction: Natural light only — shoot near a window, never flash. Backgrounds: raw linen, unfinished wood, or stone. Props kept to a minimum — maybe a dried flower or two, never cluttered. Mood is quiet and a little intimate, like something found at a market stall you almost walked past. Close-up shots showing texture and knot detail are essential. Avoid white seamless — it reads too commercial for this brand.

Lifestyle photography direction: The world of Thread & Tide is weekend mornings and slow afternoons. Worn while making coffee in a light-filled kitchen, sitting cross-legged on a rumpled bed, at a farmers market with a canvas tote. The person in the photos is unhurried — no poses, caught mid-moment. Warm skin tones, natural hair, wearing pieces with a simple outfit (linen, denim, nothing loud). Color temperature is warm throughout — golden morning light, never cool or blue. Nothing aspirational in a luxury sense — aspirational in a "I want that quiet Saturday" sense.

UI / website art direction: Cream background (#F5F0E8), not white — warmer and more handmade-feeling. Generous whitespace. Full-bleed photography as hero, minimal text overlaid. Body font is a quiet serif. Navigation is simple — 3-4 items max, no mega-menus. Buttons are outlined, not filled — refined and light. Product grid is 2 columns on mobile, 3 on desktop with breathing room between items. No pop-ups or aggressive CTAs. Overall feel: like a well-made independent magazine. Reference: Aesop's website energy but warmer and more accessible.

---

Supporting file: references/brand-md-template.md

brand.md — Template Reference

This template defines the structure of the brand.md file delivered in Step 4's brand kit zip. It's a comprehensive, machine-readable brand spec that lets users (or downstream AI tools) produce on-brand work without needing the 14–16-page guidelines PDF.

Why this format

brand.md is the brand's portable form. Paste it into Claude, GPT, or any LLM along with a task ("write a launch tweet," "design a landing page hero," "draft an email") and the AI can produce on-brand output without the user manually re-explaining the brand. The format is intentionally:

• Scannable at the top (Quick Reference block) so an AI doesn't have to read 200 lines before producing something.
• Detailed below so the AI can dig in when a task needs more specificity.
• Markdown so it renders in GitHub, Notion, Cursor, Claude artifacts, etc.

Required sections (in this order)

1. Title + one-line description
2. Quick Reference (scannable top block)
3. Positioning
4. Target Customer
5. Mission
6. Values
7. Story (why we exist)
8. Voice & Tone
9. Colors
10. Typography
11. Logo
12. Icons
13. Imagery (Photography and/or Illustration)
14. Visual World
15. Touchpoints
16. Do & Don't
17. Reference Brands
18. Design Tokens (pointer to /tokens/ files)
19. AI Prompts (pointer to /prompts/ files)
20. How to Use This Spec

Template

# [Brand Name] — Brand Guide

> A complete brand spec. Paste this into Claude, GPT, or any AI tool along with a task to produce on-brand work. Or hand it to a designer or developer.

---

## Quick Reference

- **Name:** [Brand Name]
- **Tagline:** [Tagline]
- **One-line positioning:** [Positioning statement]
- **Primary color:** [Name] `#HEX`
- **Display font:** [Font name] (Google Fonts: [URL])
- **Body font:** [Font name] (Google Fonts: [URL])
- **Voice:** [3-4 adjectives separated by commas]
- **Logo symbol:** [One-line description — e.g. "outlined Δ delta with horizontal bar"]

---

## Positioning

[Positioning statement as a single declarative sentence.]

[1-2 paragraph expansion of what the brand stands for, what's different about it, what the wedge is.]

---

## Target Customer

[Customer name (real or representative), age, role.]

[2-3 sentence vivid description of who they are, what they care about, why they buy. Specific not demographic.]

---

## Mission

[Mission as a single sentence — the thing the brand exists to do.]

---

## Values

1. **[Value 1]** — [one-line explanation]
2. **[Value 2]** — [one-line explanation]
3. **[Value 3]** — [one-line explanation]
4. **[Value 4]** — [one-line explanation]
5. **[Value 5]** — [one-line explanation]

---

## Story — Why We Exist

[2-3 paragraphs of the brand's origin/why story, written in brand voice. This is the "about us" content — it should be real copy, ready to paste into a website.]

---

## Voice & Tone

**Adjectives:** [4 tone adjectives, comma-separated]

**How we sound:**
[1-2 sentences describing the voice.]

**Copy examples by context:**

| Context | Example |
|---|---|
| Headline | [Real example in brand voice] |
| Sub-headline | [Real example] |
| CTA button | [Real example — short, specific] |
| Error state | [Real example — warm not robotic] |
| Footer line | [Real example] |
| Social post | [Real example] |

**Words we never use:**
[Comma-separated list of forbidden words — usually marketing clichés the brand specifically avoids.]

---

## Colors

| Name | Hex | RGB | CMYK | Pantone | Role |
|---|---|---|---|---|---|
| [Name] | #HEXVAL | R, G, B | C, M, Y, K | XXX C | Primary |
| [Name] | #HEXVAL | R, G, B | C, M, Y, K | XXX C | Background |
| [Name] | #HEXVAL | R, G, B | C, M, Y, K | XXX C | Text |
| [Name] | #HEXVAL | R, G, B | C, M, Y, K | XXX C | Depth / accent |

**Primary pairings:** [Which colors go with which — e.g. "Primary on Background is the default; Primary on Text is for emphasis blocks."]

**Never:** [Color combos to avoid — e.g. "Never pair Primary with cool blues. Never tint Background gray."]

---

## Typography

**Display:** [Font name + weight], used for hero headlines at [size range]. [One-sentence note on its character.]
- Google Fonts: [URL]

**Body:** [Font name + weight], used for paragraph text at [size range].
- Google Fonts: [URL]

**Hierarchy:**

| Level | Font | Weight | Size | Line-height |
|---|---|---|---|---|
| Display | [Font] | [Weight] | 124–168px | 0.85–0.92 |
| H1 | [Font] | [Weight] | 64–72px | 0.92–0.95 |
| H2 | [Font] | [Weight] | 38–42px | 1.05–1.1 |
| H3 | [Font] | [Weight] | 22–24px | 1.15–1.2 |
| Body | [Font] | [Weight] | 16px | 1.45–1.55 |
| Caption | [Font] | [Weight] | 11px | 1.4, letter-spacing 0.28em uppercase |

**Pairing rules:** [Brief note — e.g. "Display font carries the brand. Body font supports it. Never use the display font for body or vice versa."]

---

## Logo

### Wordmark

[Description of the wordmark — which Google Font (or commercial font) it's set in, weight, letterspacing, why it matches the brand vibe. The wordmark is ALWAYS real font rendering, never a generated image.]

Files (in `logo/wordmark/`):
- `wordmark-[primary].svg` — Google Font converted to text-as-paths (renders without the font file installed)
- `wordmark-[primary].png` — 1024-wide raster fallback
- `wordmark-on-dark.svg/.png` — variants for dark backgrounds
- [etc — list all variants]

### Symbol

[Description of the symbol/mark — shape, what it evokes, how it relates to the brand. The symbol was generated via gpt-image-2 and ships as a high-resolution transparent PNG (NOT traced to SVG — only the wordmark gets vectorized). Style can be flat, dimensional, painted, photographic, gradient-rich — whatever fits the brand. Concept lane (mascot / product-feature / abstract / monogram / hybrid / container): [name the lane and explain how it links to the brand].]

Symbol output checks (all must pass):
- Conceptually linked to brand
- Feels unique (would fit ONLY this brand)
- Recognizable at 16×16 favicon size (passed mandatory PIL favicon test)
- No more than 3 dominant colors: [list them with hex]
- Shipped at 2048×2048+ master resolution
- No text inside the image
- True alpha=0 transparency verified

Files (in `logo/symbol/`):
- `symbol-[primary]-16.png` through `symbol-[primary]-2048.png` — primary color at 8 sizes, transparent background
- `symbol-on-dark-[sizes].png` — variant for dark backgrounds (if needed)
- [etc — variants ship as PNG only; symbol is NEVER vectorized to SVG]

### Lockup

[Description of how wordmark + symbol combine. Primary lockup (stacked or horizontal). Secondary lockups. When to use each. Measurements are PERFECTLY MEASURED and PERMANENTLY FIXED across all color variants — never let the wordmark drift between cream / pink / dark versions.]

**Locked measurements (specify both lockups):**
- Horizontal: symbol [WxH px], gap [X px], wordmark font-size [X px], alignment [optical center / baseline]
- Stacked: symbol [WxH px], vertical gap [X px], wordmark font-size [X px]

Files (in `logo/lockup/horizontal/` and `logo/lockup/stacked/`):
- `lockup-[orientation]-[color].svg` — symbol PNG embedded inline + wordmark as text-as-paths at locked measurements
- `lockup-[orientation]-[color].png` — assembled lockup as raster, 1024-wide
- [List all color variants]

**Clear space rule:** [Minimum space around the lockup — e.g. "Minimum one symbol-height of space on all sides."]

**Don'ts:** Don't stretch, rotate, recolor outside the palette, drop-shadow, or place on busy backgrounds.

---

## Icons

*(This section only applies to digital brands — app, web, SaaS, software platform. For non-digital brands (product, fashion, restaurant, service), delete this section entirely and skip the `/icons/` folder in the kit.)*

**Stroke weight:** [e.g. 1.5px / 2px / 3px]
**Corner radius:** [sharp / 2px / round]
**Line caps:** [butt / round / square]
**Style:** [outline / filled / mixed]
**Grid:** 24×24 base

**Set in this kit** (`/icons/`):
- arrow-right, arrow-down, check, close, plus, minus, search, user, settings, bell, menu, info
- [+ any brand-specific icons]

**For icons beyond this set:** Use [library name + weight] — e.g. "Phosphor Light" or "Lucide at 1.5px stroke."

Each icon SVG uses `stroke="currentColor"` so it adopts the surrounding text color in any application context.

---

## Imagery

Use this section's photography-OR-illustration block depending on the brand's medium. Delete whichever doesn't apply, or keep both if the brand is hybrid.

### Photography (if brand uses photography)

**Subject:** [Who/what is in the frame.]

**Light:** [Lighting style — direction, quality, time of day.]

**Color:** [Color grade direction.]

**Texture:** [Film, grain, composition guidance.]

**Forbidden:** [What this brand's photography never looks like — stock, studio, etc.]

**Cast diversity:** All lifestyle images featuring people must show racial diversity across the set. Vary body types. Default to mixed cast unless there's a deliberate reason for a single subject.

### Illustration (if brand uses illustration)

**Style:** [Flat vector / line art / geometric / 3D / hand-drawn / mixed. Be specific.]

**Color use:** [How brand colors apply — large fields vs accent dots, palette restraint per illustration.]

**Line / stroke:** [Stroke weight, corner radius, line caps. Or "no strokes, color fields only."]

**Character:** [Friendly / precise / playful / archival / geometric / organic. Match brand voice.]

**Composition:** [Asymmetric / centered, whitespace approach, framing rules.]

**Subject matter:** [What illustrations depict — scenes, objects, metaphors. Tied to the brand metaphor.]

**Forbidden:** [What kills the style — realistic detail in flat-vector brand, gradients, drop shadows, generic stock-illustration look, etc.]

**Reference brands' illustration style:** [2-3 brands whose illustration is close.]

---

## Visual World

[2-3 sentence description of the world the brand's imagery lives in — environments, time of day, mood, characters. Should paint a picture someone could art-direct a shoot from.]

---

## Touchpoints

The brand shows up on these surfaces. Each follows the rules above.

- **Web** — [hero treatment, color usage, typography rules]
- **Mobile app** — [UI palette and rules]
- **Social** — [tone, asset rules, posting cadence]
- **Print collateral** — [business cards, packaging, etc.]
- **Merch** — [stickers, mugs, totes, apparel]

---

## Do & Don't

**DO:**
- [Brand-specific do #1]
- [Brand-specific do #2]
- [Brand-specific do #3]
- [Brand-specific do #4]
- [Brand-specific do #5]

**DON'T:**
- [Brand-specific don't #1]
- [Brand-specific don't #2]
- [Brand-specific don't #3]
- [Brand-specific don't #4]
- [Brand-specific don't #5]

---

## Reference Brands

These brands share the territory. They're not competitors — they're cultural reference points the brand can borrow energy from.

- **[Brand]** — Borrow: [what to learn from them]
- **[Brand]** — Borrow: [what to learn from them]
- **[Brand]** — Borrow: [what to learn from them]
- **[Brand]** — Borrow: [what to learn from them]

---

## Design Tokens

Machine-readable versions of all visual tokens (colors, fonts, spacing, radius, shadow) live in the `/tokens/` directory:

- **`tokens/tokens.css`** — CSS custom properties. Drop the `:root { ... }` block into your stylesheet and reference as `var(--color-primary)`, `var(--font-display)`, etc.
- **`tokens/tokens.json`** — same content as JSON. Useful for AI tools, build pipelines, or any non-CSS context.
- **`tokens/tailwind.config.snippet.js`** — paste inside your `tailwind.config.js` `theme.extend` block. All brand tokens become Tailwind classes (`bg-primary`, `text-text`, `font-display`, `rounded-lg`, etc).

The token names match this spec — don't rename them or they'll fall out of sync with the rest of the brand documentation.

---

## AI Prompts

Pre-built prompts for common downstream tasks live in `/prompts/`:

**Copy prompts:**
- **`prompts/system-prompt.md`** — paste at the top of any Claude or GPT thread to prime the model on this brand's voice + visual identity. Then add your task below.
- **`prompts/tweet.md`** — task starter for writing tweets in brand voice
- **`prompts/landing-hero.md`** — task starter for landing page hero copy (headline + sub + CTA)
- **`prompts/email.md`** — task starter for marketing or transactional emails
- **`prompts/error-message.md`** — task starter for writing warm-but-specific error/empty/loading states

**Image prompts:**
- **`prompts/photography.md`** — task starter for generating brand photography via gpt-image-2 (or similar). Includes the brand's exact photo direction (subject / light / cast / texture), banned cliché concepts list, anti-stock guardrails, the no-text safeguard string, and subject substitutes for "person at laptop" defaults.
- **`prompts/illustration.md`** — *(only present if the brand uses illustration)* — task starter for generating brand illustrations. Includes the brand's illustration style rules, palette constraints, banned elements (gradients, drop shadows, etc.), and when to use illustration vs photography.

These prompts encode the brand voice rules from this spec into instructions the model will follow. Use them when you want consistent on-brand output without re-explaining the brand each time.

---

## How to Use This Spec

**With an AI tool (Claude, GPT, etc.):**
1. Paste `prompts/system-prompt.md` (or this whole `brand.md`) at the top of a new thread.
2. Add your task — "Write a launch tweet" / "Design a landing page hero" / "Draft an onboarding email."
3. Or use a specific task starter from `/prompts/` for the most consistent output.
4. Verify the output against the Do & Don't section before shipping.

**With a designer:**
- Hand them the `brand.md` + `/logo/` + `/icons/` directories. They have everything they need.

**With a developer:**
- Point them at `/tokens/` first. CSS variables / JSON / Tailwind config — pick whichever matches their stack.
- The icon SVGs in `/icons/` use `currentColor` for stroke so they inherit color from context.

**For self-checks:**
- Before delivering anything in this brand's voice, re-read the "Voice & Tone" section.
- Before delivering anything visual, re-read "Colors," "Typography," "Icons," and "Imagery."
- Always check the Do & Don't list last.

---

*Generated [DATE] by the build-a-brand skill. Update this file when the brand evolves.*

Filling guidelines

• Quick Reference must be scannable in 5 seconds. Don't bloat it.
• Voice copy examples must be REAL on-brand sentences, not placeholders. Pull from the guidelines PDF's Voice & Tone page.
• Colors table needs Pantone if you have it; mark as "—" if not specified.
• Typography Google Fonts URLs must be the actual https://fonts.google.com/specimen/[Name] link, not the embed URL.
• Logo file lists must match exactly what's in the zip. If a variant doesn't exist, don't list it.
• Reference brands with "borrow this" notes — the same content as the guidelines page 2.
• How to Use — the most important section for downstream usability. Tell the user how to actually apply this spec.

What NOT to include

• Don't include the full 14–16-page guidelines verbatim. The brand.md is the SPEC, not the manual. Keep it tight.
• Don't include marketing fluff. Every section should be either directly usable copy or actionable rules.
• Don't include build mechanics (WeasyPrint quirks, prompt templates, etc.). Those are skill-internal.