Build Brand System

Build Brand System

Turn a product brief into a brand a developer can ship from. Two deliverables, nothing else:

• brand/BRAND.md — the spec. Exact hex values, real licensed fonts, logo construction, voice, usage rules. This is the source of truth.
• brand/brand-board.png — one 3x3 image showing the system applied. This is a showcase, not a spec: it proves the direction reads, and it is what the user looks at to say yes.

Write the spec first, then generate the board from it. Never read colours or type off a generated image — the image inherits its values from BRAND.md, not the other way round.

Prerequisites

• taskfuel CLI connected (taskfuel whoami), balance ≥ ~$0.20 (each board is ~$0.05; budget 2–3 attempts).
• blockrun.ai in the gateway's allowed domains (taskfuel discover).
• Base taskfuel skill covers payment mechanics — read it first if you haven't.

If the environment has its own image generation, use that instead and skip the paid call. Without either, still produce BRAND.md and hand over the board prompt — say plainly that no image was generated.

Workflow

1. Brief

Infer everything you can from the conversation, an attached moodboard, or the repo if the user pointed at one — don't treat an unrelated cwd as evidence. Then ask at most three questions, and only ones that change the output:

• what the product is and who it's for
• anything that must survive (existing name, mark, colour, tone)
• where it has to work (web app, CLI, print, packaging, dark mode)

Don't ask for a preferred aesthetic. Proposing is the job. If you have enough, state your assumptions and start.

2. Kernel — hold this in your head, not in a file

Before any visual choice, pin down four things and say them back in two or three sentences:

• Job: who needs this and what progress they're making.
• Promise: what the brand should make credible in one second.
• Category stance: which conventions to embrace, which to resist.
• Three tensions, each as desired → avoid: "calm authority → institutional coldness", "technical precision → developer-only signalling". Adjective piles ("modern, clean, bold") are not a kernel — they can't reject anything later.

If you can't use the kernel to reject an attractive-but-wrong direction, it isn't specific enough yet.

3. Three directions → user picks one

Propose three directions in text. Cheap, fast, no images yet. Each gets four lines:

• Idea — one strategic argument derived from the kernel.
• System — type logic, geometry, colour logic, imagery treatment.
• Feels like — the one-second read.
• Risk — where it fails. A direction with no risk is vague.

They must differ in at least four of: metaphor, category relationship, emotional temperature, type logic, geometry, colour logic, imagery, materiality. Three palettes of the same layout are one direction, not three. Never name real brands or living designers as shorthand — describe observable behaviour.

Stop here and get an explicit pick. Don't merge directions, don't generate a board, don't touch frontend code. If the user asks to see them before choosing, board the top two (~$0.05 each) and present side by side. Separate image quality from system quality — a well-rendered weak idea should not win.

4. Write brand/BRAND.md

Every value is authored by you and exact. Sections:

• Brand idea — 2–3 sentences: the kernel, resolved.
• Palette — named roles with hex: ink, surface, surface-alt, primary, accent, plus semantic success/warning/danger if the product needs them. Give dark-mode counterparts. Verify body text hits 4.5:1 against its surface and UI/large text 3:1 — compute the ratios and state them; fix the value, don't hedge. Say what each colour is for, and name the one that must stay rare.
• Typography — real, licensable families (default to Google Fonts unless the user wants to buy type), one display and one text face, plus mono if it's a dev product. Record weights, the type scale, tracking on display sizes, and the fallback stack.
• Logo — construction in words: mark idea, geometry, clear space, min size, lockups, what breaks it. The board's mark is a sketch; the real one gets redrawn in vector.
• Graphic language — grid, radii, borders, elevation, iconography style, motion character. Concrete values, not moods.
• Imagery — photography/illustration/texture treatment, and what's banned.
• Voice — three rules with a good and bad example each.
• Do / don't — the five rules most likely to be broken.
• Open questions — what's unresolved. Say it rather than inventing it.

Keep it one file. If the project later needs machine-readable tokens, generate them from this file — don't fork the truth.

5. Generate the board

One image, 3x3, 9 panels. Fixed roles so the board covers the whole system:

Swap panel 9 (and only 9) for whatever fits — packaging, signage, merch, a social card. Build the prompt straight out of BRAND.md:

One single image: a 3x3 grid brand board, 9 equal panels, thin neutral
gutters, no captions or numbers anywhere.
PALETTE: use exactly #RRGGBB (ink), #RRGGBB (surface), #RRGGBB (primary),
#RRGGBB (accent, sparingly) in every panel.
TYPE: <display family>, <text family>, <weights>.
SYSTEM: <geometry, radii, iconography, imagery treatment from BRAND.md>.
PANELS: 1 <role>. 2 <role>. ... 9 <role>.
AVOID: <the avoid list — clichés, effects, motifs the direction rejects>.

Pick the model deliberately — don't inherit a default. List what's on offer and read the prices:

curl -s https://blockrun.ai/api/v1/models | jq -r '.data[]
  | select(.categories[]? == "image")
  | "\(.id)\t$\(.pricing.per_image)\t\(.description)"'

Default to openai/gpt-image-2 ($0.06) for brand boards. A board is nine panels of typography — a wordmark, a type specimen, button labels — and image models differ enormously here. Verified 2026-07-30 on the same prompt: google/nano-banana ($0.05) rendered garbled pseudo-text in every text panel across two attempts, while gpt-image-2 produced a correctly-spelled wordmark, a legible a–z specimen, and accurate button labels first try. One cent buys the entire difference between a usable board and an unusable one.

Build the body with jq -Rs so the prompt's quotes and newlines survive, then quote before paying. --body takes inline JSON only — there is no @file support, so pass "$(cat …)":

jq -Rs '{model: "openai/gpt-image-2", prompt: .}' prompt.txt > board.json
taskfuel call https://blockrun.ai/api/v1/images/generations \
  --method POST --body "$(cat board.json)" --quote      # confirm ~$0.064
taskfuel call https://blockrun.ai/api/v1/images/generations \
  --method POST --body "$(cat board.json)" > resp.json

Two response shapes. Fast models return the image inline as data[0].url. Slower ones — gpt-image-2 included — return status: "queued" with a poll_url; taskfuel call "https://blockrun.ai<poll_url>" every ~20s until status: "completed", which takes about a minute. Payment settles on completion, so a queued response already means you've been charged.

Either way the URL is an ordinary hosted PNG (not a data URI) — curl -sSL it to brand/brand-board.png. The response embeds an unquoted tx_hash, so jq can fail to parse it; grep -o 'https://blockrun.ai/api/media[^"]*\.png' is the reliable extraction. Save the final prompt in a fenced block at the bottom of BRAND.md so the board can be regenerated.

Keep rendered text minimal. Image models mangle small copy — treat any type in the board as indicative of attitude, never as a specimen to measure.

6. Check, revise once at a time, deliver

Read the generated image back and grade it against BRAND.md:

• Are the palette colours the ones you specified, in roughly the intended proportion?
• Is the type attitude right (weight, contrast, density)?
• Is the geometry consistent across all nine panels, or did three of them drift into a different system?
• Does it survive the kernel's tensions, or did it land on the "avoid" side?

Fix one identified failure per regeneration, naming it in the prompt, and state the correction and its opposite — "a continuous chart LINE, not a solid filled mound", reinforced by adding the wrong reading to the AVOID list. Naming only the thing you want reliably gets you the thing you don't. If drift keeps coming back, the fix is in BRAND.md — sharpen the spec, don't pile on adjectives. Two or three attempts is normal; more means the direction is underspecified.

Observed failure modes worth pre-empting in the first prompt: the model fills any "hill/curve/area" language into a solid opaque shape; it picks label colours on filled buttons at random, so state the label colour per button; and a "sticker sheet" panel leaks its white outline into every other panel unless you scope it ("the ONLY panel where creatures have outlines"). All three are fixed by naming the constraint and its opposite — a per-panel scope reliably holds.

Know when to stop. Some spec items no image model will hit — per-letter baseline rotation in a wordmark failed three times across two models here. That's not a prompt problem, and a fourth attempt is just money. Logo geometry is on the "rebuild in real tools" list anyway, so note the gap and move on. Stop when the only remaining deltas are things BRAND.md already declares the board non-authoritative for.

Then show the user the board and the spec, and say in one line what's directional (the mark, any rendered type) versus what's exact (hex, families, values).

Rules that keep this honest

• The board never overrides BRAND.md. If they disagree, the file is right and the board gets regenerated.
• Rebuild in real tools before shipping: logos as vector, type as licensed webfonts, UI in code. Generated raster is final only for texture, imagery, and campaign art.
• Don't build frontend to compare directions. That's what the board is for.
• Don't rerun this skill for routine assets. Read the existing BRAND.md and apply it. Rerun only for a rebrand, or when the system fails a new requirement.
• Preserve anything the user said must survive, even when a direction would be stronger without it — surface the tension, let them decide.

Costs (observed 2026-07, quote to confirm)

A normal run lands around $0.10–0.20. Kernel, directions, and BRAND.md cost nothing — only images are paid.