fireworks-design

An open-source Claude Code workflow that replicates ClaudeDesign — fan out many distinct design directions, judge them like a panel, synthesize the best, and adversarially refine to a single world-class frontend page.

English · 简体中文

One-sentence pitch: Stop rolling the dice on a single model output. fireworks-design explores 6–8 independent aesthetics in parallel, scores each across 6 design dimensions, grafts the winners together, then critique-fix-loops the result until it's shippable.

📦 Install

In Claude Code, just say:

Install fireworks-design into this project — repo is yizhiyanhua-ai/fireworks-design.

Claude drops the workflow into .claude/workflows/ and adds a /fireworks-design slash command — done.

mkdir -p .claude/workflows .claude/commands
curl -fsSL -o .claude/workflows/fireworks-design.js \
  https://raw.githubusercontent.com/yizhiyanhua-ai/fireworks-design/main/fireworks-design.js
curl -fsSL -o .claude/commands/fireworks-design.md \
  https://raw.githubusercontent.com/yizhiyanhua-ai/fireworks-design/main/.claude/commands/fireworks-design.md

🚀 Usage

Type the slash command, then your request:

/fireworks-design a landing page for a coffee shop, save to ~/design/coffee, 6 directions, brand #7c3aed

Claude runs the workflow in the background (watch it live with /workflows) and hands you a finished final.html. Or just ask in plain language:

Use fireworks-design to build a landing page for a coffee shop. Save it to ~/design/coffee.

Tweak it conversationally — …explore 8 directions, refine 3 rounds, brand color #7c3aed.

What you get: a single self-contained final.html (plus the explored draft-*.html directions) and a summary of which aesthetic won and why.

Workflow({
  name: "fireworks-design",
  args: { prompt: "...", outputDir: "/abs/path", variants: 6, refineRounds: 2 }
})

✨ Featured outputs (效果解读)

14 real pages across totally different domains — all live on GitHub Pages · full table + deep-dives. Four highlights:

🎬 LUMIÈRE — movie rating · Dark Premium	🎵 NOVA · AURORA — album · Bold Editorial
🎨 OBJECT & ECHO — studio · Bold Editorial	✈️ AZORES — travel · Bold Editorial

Winner diversity proves the point: across 14 briefs, Bold Editorial won ×8, Dark Premium ×3 (movie/restaurant/ecommerce), Swiss Minimal ×2 (fitness/edtech), Editorial ×1 (nonprofit). Different briefs crown different winners — that's why we judge instead of generating once. Full 效果解读 (winning rationale, signature moments, real bugs the refine/polish pass caught) in examples/README.md.

🖼️ Gallery — all 14 live examples

LUMIÈRE	MAISON NOIR	OBJECT & ECHO	NOVA · AURORA
PULSE	AZORES	LUMEN	ECHOES OF THE VOID
Brightwater	AURA ONE	BUILD/2026	vector
tideline	Lin Hua

🎨 Style Study — 10 styles × 10 themes

Each of the 10 newer aesthetics, paired with a domain that fits it (a synthwave arcade bar, a 1920s speakeasy, a couture lookbook, a punk-band tour, a kids' learning app…). Same workflow, single-lens runs.

PIXEL DIVE · synthwave	FORM & FUNCTION · bauhaus	THE GILDED HOUR · art deco	RIOT DECK · memphis	INK & PAPER · riso
HYGGE & CO · scandi	PRISM · holographic	VESPER · couture	BLACKOUT · punk zine	BLOOM · claymorphism

→ Full table + per-style details in examples/README.md.

🧠 How it works — six phases

① Brief — distill a design system

One agent turns your prompt (+ optional brand) into a shared creative brief: product framing, audience, required sections, and concrete design tokens (font pairings, palette hexes, mood, references). These tokens are injected into every subsequent agent, so the whole pipeline stays on-brand.

② Diverge — wide exploration (the quality core)

Each agent commits fully to one aesthetic and produces a complete, self-contained HTML file. Each generator internally plans → self-critiques → produces, rather than dumping a first draft.

③ Judge — panel scoring

Every direction × every design dimension, scored 1–10 by independent critics (~36 critiques in parallel for 6 directions). Each verdict also returns its single highest-leverage fix, which feeds the next phase.

④ Synthesize — graft the best

Reads the Top-3 directions' source, uses the strongest as the base, folds in the best elements of the others, and fixes every issue the judges flagged. The output must clearly beat any single direction.

⑤ Refine — adversarial polishing

A ruthless reviewer returns prioritized issues (severity-tagged); a fixer applies them surgically. Looped refineRounds times (default 2). This is ClaudeDesign's "fine-grained controls," engineered.

⑥ Polish — ship-ready QA

A final gate checks and fixes: responsiveness (375/768/1280+), all interactive states, prefers-reduced-motion, semantic HTML + ARIA, WCAG AA contrast, no console errors, no leftover placeholders — then writes final.html.

✨ Why this exists

Even experienced designers ration exploration — there's rarely time to prototype a dozen directions, so you settle for two. From the Claude Design announcement:

"Even experienced designers have to ration exploration — there's rarely time to prototype a dozen directions, so you limit yourself to a few."

A single LLM generation is one draw from a distribution. Its taste, mood, and prompt interpretation are locked into that one version. fireworks-design turns that variance into a quality floor by:

• Exploring widely — N parallel agents, each committed to a distinct aesthetic.
• Judging independently — a panel scores every direction across separate design dimensions.
• Synthesizing — taking the winner as the skeleton and grafting the best of the runners-up.
• Refining adversarially — critique → fix, looped until it clears the bar.

🧩 Built on Claude Code's Dynamic Workflow

fireworks-design is not a prompt, a library, or a hosted service. It's a single JavaScript file that the Claude Code Workflow runtime executes as a Dynamic Workflow — deterministic code that spawns model agents, runs them in parallel, and composes their schema-validated outputs. Control flow belongs to the script (loops, fan-out, barriers), not to the model, so every run is reproducible and resumable. Bring it your model; it brings the orchestration.

The whole pipeline is ~270 lines with a shape you can read at a glance:

// fireworks-design.js — condensed to its bones
phase('Brief');    const brief    = await agentRetry(briefPrompt, { schema: BRIEF_SCHEMA })

phase('Diverge');  const variants = await parallel(LENSES.map(l => () =>          // fan-out: N directions
                    agent(generate(l), { schema: VARIANT_SCHEMA }))).filter(Boolean)

phase('Judge');    const verdicts = await parallel(variants.flatMap(v =>          // panel: N × 6 dimensions
                    DIMS.map(d => () => agent(judge(v, d), { schema: SCORE_SCHEMA }))))

phase('Synthesize'); await agentRetry(synthesize(top(variants, verdicts)))        // graft the best

for (let i = 0; i < REFINE_ROUNDS; i++) {                                         // critique ↔ fix loop
  const issues = await agentRetry(critique, { schema: CRITIQUE_SCHEMA })
  await agentRetry(fix(issues))
}

phase('Polish');   await agentRetry(polish)                                       // ship-ready QA
return { outputPath: FINAL_PATH, winner, ranking, summary: polish }

What makes this a dynamic workflow rather than a script that calls a model:

• Deterministic orchestration — parallel() is a real barrier, phase() groups live progress, the for loop is yours. The model never decides what runs next.
• Schema-validated agents — every agent() returns typed JSON, so the pipeline composes data, not prose. No regex-parsing model output.
• Resumable — edit a prompt and re-run; the unchanged prefix replays from cache (resumeFromRunId).

Full file: fireworks-design.js.

🔬 Under the hood — orchestration, not iteration

This isn't a "generate, then ask the same model to improve it" loop. It's a deterministic multi-agent pipeline that composes several modern inference-time techniques into one reproducible run — built on the Claude Code Workflow runtime (parallel() / pipeline() / agent() primitives, schema-validated returns, resumable execution).

The net effect: you're not hoping the model has a good day. You're engineering a quality floor out of sampling, judging, and refinement — the same inference-time-scaling ideas behind best-of-N and self-consistency, applied to design instead of math.

⚙️ Arguments

🎚️ Customization

Aesthetic lenses (LENSES)

The distinct directions explored in phase ②. Edit the LENSES array to add your own styles:

Judge dimensions (DIMS)

What the panel scores on: hierarchy · typography · color/contrast · motion · engineering craft · delight/originality.

🤖 Model choices

Every agent() call omits the model parameter, so all subagents inherit the current session model. Run it on Opus for top quality, on Sonnet for speed, or on any model your harness exposes — no code changes needed.

💼 Example cases

A few prompts to try (all outputDir set to an absolute path):

🔗 Mapping to ClaudeDesign

💰 Cost & considerations

• 6 variants × full pipeline ≈ 40+ agent calls. This is deliberate — quality is the point.
• Token cost scales with variants, refineRounds, and page complexity.
• Workflow agents read full HTML files for judging/synthesis, so very long pages cost more.
• Want budget-aware scaling? Tie VARIANT_COUNT to budget.total (the workflow exposes budget).

❓ FAQ

Do I need a specific model? No. It inherits your session model. A strong model (Opus-class) gives the best results.

Can I use just one direction? Then you don't need this workflow — run a normal frontend-design pass instead. The value is the parallel exploration + judging.

Where do the draft files go? In your outputDir. They're not committed (see .gitignore); keep or delete them freely.

Can I plug in my design system? Yes — pass it via brand. Brief will fold your tokens into every agent.

🤝 Contributing

Contributions welcome — new aesthetic lenses, judge dimensions, or smarter synthesis. Open an issue first to discuss scope. See CONTRIBUTING.md.

❤️ Donate

If fireworks-design helps you ship, donate via PayPal — it funds new aesthetic lenses, more example domains, and keeps the workflow sharp. No US account needed; works internationally.

→ paypal.me/yizhiyanhua · or choose your own amount

📄 License

MIT © yizhiyanhua-ai