Skip to content
BoB — Big ol' Brain

Produce a Design Brief

Produce a design brief

Section titled “Produce a design brief”

Goal: elicit and write a complete, structured design brief for a feature or product surface — the hand-off contract between “what we want” and downstream design work (a human designer, the category: design skills, or an external design generator). The format is defined in the design-brief schema reference.

Prerequisites

Section titled “Prerequisites”
  • The design-brief registry command is provisioned to the project (cdprov add command design-brief) — it targets web-app projects, like the other category: design items.
  • Optional but valuable: a committed DESIGN.md at the project root (explanation) — the elicitation reads it instead of re-asking tone/token/component questions.

Full elicitation

Section titled “Full elicitation”
/design-brief checkout flow

The command walks the seven schema sections in order, pre-filling from project evidence (DESIGN.md, package.json, component directories) and asking only what the project can’t answer. Any prompt can be skipped — skipped sections are emitted as explicit, falsifiable assumptions, never asserted as fact.

Two sections cannot be assumed: purpose and audience. Vacuous or missing answers get one sharper re-prompt; if still missing, the command refuses rather than briefing the wrong thing with confidence. Contradictions (between answers, or between an answer and DESIGN.md) are surfaced with the conflicting values quoted for you to resolve.

Express mode

Section titled “Express mode”
/design-brief checkout flow --quick

One question round — purpose, audience, key screens — and a usable brief with every other section filled as labeled assumptions. The artifact records mode: quick; re-run without --quick to upgrade it.

Output

Section titled “Output”

The brief is written to docs/design-briefs/<date>-<slug>.md and printed to the terminal as one copy-pasteable block. Commit it when you’re happy — the command never commits for you below the automation level that covers commits.

Refine an existing brief

Section titled “Refine an existing brief”

Re-run the command for a feature that already has a brief:

/design-brief checkout flow

The command detects the existing brief in docs/design-briefs/, summarizes it (date, mode, how many sections are stated / derived / assumed, any tailored variants), and asks: refine or start fresh?

Choosing refine shows the seven sections as a multi-select — pick the ones that changed and only those are re-asked; everything else carries through verbatim, content and provenance both. The artifact is updated in place (same file — the filename keeps its original date), the front matter gains a revised: date, and the whole brief is re-validated, since a new answer can contradict an untouched section. Any tailored variants are now stale: the command offers to regenerate them, and names them if you decline so the staleness stays visible.

Choosing start fresh runs the normal flow and writes a new artifact dated today; the prior brief is left untouched. When no prior brief exists there is no prompt at all — the command goes straight to elicitation.

Tailored variants

Section titled “Tailored variants”

After constraints settle, the command asks which generator(s) the brief targets. Name a catalogued tool and you get a tailored variant next to the generic brief (<date>-<slug>.<generator>.md), restructured to that tool’s input conventions from the design-generator catalog. Answer undecided and the generic brief stands alone with 1–3 candidate tools suggested from your constraints. Name an uncovered tool and you get the generic brief, an explicit no-variant-available flag, and an offer to add the tool to the catalog — once its entry exists, tailoring works with no other change.

Adding a new generator format

Section titled “Adding a new generator format”

Tailoring is data-driven from the catalog — there are no per-tool templates. To support a new tool, add a catalog entry with the standard fields (the Input and Prompting conventions rows are what the tailoring layer reads; see the catalog’s Maintenance section for the full field set). No command or schema change is needed.

Worked example — v0 variant

Section titled “Worked example — v0 variant”

A generic brief section set like this:

### Purpose / problem
Self-serve plan upgrades; success = fewer support tickets for billing.


### Constraints
Next.js + Tailwind; tokens in DESIGN.md; WCAG AA; desktop + mobile.


### Component inventory
Reuse: PricingCard, PlanBadge. New: ProrationPreview, ConfirmDialog.

becomes a v0 variant shaped by the catalog’s v0 entry (prose prompt; attachments for design context; stock-shadcn bias; stack stated up front):

---
variant_of: 2026-07-02-plan-upgrades.md
target: v0
date: 2026-07-02
---


**Attach first:** the shadcn registry / tokens.css exported from DESIGN.md
(v0 honors coded tokens; don't restate hex values in prose).


**Prompt:**


Build a self-serve plan-upgrade flow in Next.js + Tailwind + shadcn/ui.
Users: existing customers changing tiers; must work desktop and mobile.
Screens: current-plan summary → plan comparison → proration preview →
confirmation. Reuse our PricingCard and PlanBadge components from the
attached registry; create ProrationPreview and ConfirmDialog using stock
shadcn primitives. Every interactive element must meet WCAG AA contrast
and be keyboard-navigable — treat this as a hard requirement, not a
preference. Goal: a customer completes an upgrade without contacting
support.

The variant is structurally distinct — one attachment directive plus one flowing prompt, ordered stack-first per v0’s conventions, with the token source moved out of prose and into an attachment — while every stated constraint (stack, tokens, WCAG AA, responsive, components) carries through. The generic brief remains the source of truth; regenerate variants after editing it.

Section titled “Related”