build-a-brand

name	build-a-brand
description	Use when the user asks for build a brand or a task matching the examples below. Build a practical brand identity from any input — an idea, an existing website, a list of reference brands, product photos, or "I want to rebrand X". Default to a fast quick-brand path for founder-kit users, and offer the full 14-16-page guidelines as an opt-in upgrade. Use when someone wants a brand identity but does NOT need a full commerce launch (no Shopify, no product listings, no social posting). Trigger phrases: "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".
argument-hint	<idea-or-url-or-reference-brands> [photos=<paths-or-urls>] [refresh=<existing-brand>] [--quick] [--full] [--config <path>]
required-capabilities	["generate_image","task_status","identity_balance"]

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.