Design-Brief Schema

Design-Brief Schema

The single generic schema every brief produced by /design-brief follows — the same section set and front matter on every project, so briefs are comparable across projects. The elicitation flow that fills it lives in the command; this page owns the format.

File artifact

Property	Value
Path	docs/design-briefs/<YYYY-MM-DD>-<feature-slug>.md (date via timelord)
Format	YAML front matter + one markdown section per schema row, in order
Ownership	Project file, committed by the developer — never a GitHub issue

Front matter

---
feature: checkout flow          # what is briefed (slug source)
date: 2026-07-02                # authored date, YYYY-MM-DD
revised: 2026-07-09             # optional — date of last in-place refinement
mode: full                      # full | quick
provenance:                     # one entry per section, in schema order
  purpose: stated
  audience: stated
  screens_flows: stated
  brand_voice: derived          # derived entries name their source in-section
  visual_tone: assumed
  constraints: derived
  component_inventory: assumed
---

mode: quick marks an express-mode brief (at most three stated inputs; everything else assumed or derived). revised appears only on briefs that have been updated in place by the command’s refine flow — date is the original authored date (and the filename’s date component), revised the last refinement.

Sections

Every brief contains exactly these seven sections, in this order:

#	Section (heading)	Front-matter key	Captures
1	Purpose / problem	purpose	What the surface is for, the problem it solves, the success signal
2	Audience / personas	audience	Who uses it — context, expertise, devices
3	Key screens / flows	screens_flows	Screens and user flows in scope, entry/exit points
4	Brand / voice	brand_voice	Product personality, tone of copy, brand adjectives
5	Visual tone	visual_tone	Density, mood, visual references
6	Constraints	constraints	Stack, design system in use, accessibility level, platform/responsive targets
7	Component inventory	component_inventory	Components the flows need — existing to reuse and new to design

Provenance states

Each section is in exactly one state, recorded both in the front matter and visibly in the section body:

State	Meaning	Body marking
stated	The developer answered	None — plain content
derived	Read from project evidence	Names the source, e.g. (derived from DESIGN.md)
assumed	Skipped; filled with a defensible assumption	The assumed marker below

The assumed marker

A skipped section is never asserted as fact. Its heading carries an (assumed) suffix and its body opens with an explicit blockquote:

### Audience / personas *(assumed)*

> **Assumed** — not confirmed by the developer: general consumers on
> mobile-first devices, low domain expertise. Revise if wrong.

Assumptions must be concrete enough to be falsifiable.

Tailored variants

A brief may have generator-tailored renderings alongside it, produced by the command’s tailoring layer from the design-generator catalog:

Property	Value
Path	docs/design-briefs/<YYYY-MM-DD>-<feature-slug>.<generator>.md (e.g. …-checkout-flow.v0.md)
Front matter	variant_of: <generic brief filename>, target: <generator>, date
Structure	Defined by the catalog entry’s input conventions — not the seven generic sections
Ownership	Derived artifact — regenerate from the generic brief after edits; never edit a variant directly

The generic brief is the source of truth; a variant that drifts from it is stale by definition.

Refinement (in-place update)

The command’s refine flow updates an existing brief in place rather than writing a new artifact:

Rule	Value
Path / filename	Unchanged — the filename keeps the original date (identity, not freshness)
Untouched sections	Preserved verbatim: prior content and prior provenance carry through exactly
Re-elicited sections	Fresh provenance (stated / derived / assumed) per the new answer
date / revised	date keeps the authored date; revised is stamped with the refinement date
mode	Flips quick → full when refinement states sections beyond the express set
Variants	Stale after any refinement — regenerate from the updated brief

Validity rules below apply to the refined brief as a whole, not just the changed sections.

Validity rules

• purpose and audience may never be assumed — a brief missing either is invalid and must not be emitted (the command re-prompts, then refuses).
• In mode: quick, purpose, audience, and screens_flows are the stated set; all other sections are assumed or derived.
• derived values reference their source (e.g. DESIGN.md tokens); a brief never forks a value the source owns.