design-brief

name	design-brief
description	Produces a design contract (DESIGN.md + DTCG tokens) by querying the seeded design KB, write-back on a miss. Use before the first UI wave or when visuals drift; primes the aesthetic gate.

design-brief

The front-end of the theme system. You turn "what they're building" into a concrete design contract — a DESIGN.md plus real DTCG design tokens — by searching the seeded design KB first, not by inventing from defaults. This is the v7 fix to v6's design-brief: v6 read prose references; you query the 417-drawer KB (kb-system) and emit machine-readable tokens (dtcg-emit), and on a miss you research, synthesize, and write the result back so the next project in the niche is a hit. The output primes the aesthetic gate's Phase-B audit.

What this does / does not do

Does: interpret the brief, query the design KB for a matching palette/style/type-pairing, adopt the hit (or synthesize + write-back on a miss), emit DTCG tokens via dtcg-emit and a DESIGN.md that wraps them, and gate the result (non-default fonts, single restrained accent, no pure black/white, token policy, ≥10 project bans, injection block). Does not: build screens (that's executor), run the visual audit (that's the aesthetic gate — design-brief feeds it), or apply to non-visual targets.

When NOT to use

• The target has no visual surface (api-service, library-package, cli, data-pipeline) — there is no design contract to write; the visual gates are N/A.
• A current, committed DESIGN.md already fits and nothing drifted — re-running rewrites a contract downstream UI is built against; edit the token config instead.
• The user wants the visual verdict on built UI — that's the aesthetic gate, not design-brief.

Reference Routing

Situation	Reference
The DESIGN.md contract template (9 sections + injection block)	references/design-md-template.md
KB query / write-back, token emit	../README.md (theme system) · ../../knowledge/kb-system.py · ../dtcg-emit.py

Inputs

• The brief: product, audience, vibe (2–3 concrete adjectives), platform, light/dark default, one anchor color (or ask).
• Mode B only: existing *.html / *.css / tailwind.config.* to extract tokens from.
• The design KB (seeded — library/systems/theme/kb-seed/), via kb-system query.

How to do it

Mode A — from intent

Step 0 — elicit a SHARP brief (before the KB query; the brief is the moat). Most briefs are vague ("modern, clean app") and produce generic output — everyone has the KB; almost no one has a sharp brief. Force these decisions, one sentence each, and push back on weak answers (show a weak-vs-sharp contrast; reject banned generic words: modern, clean, minimal, premium, professional, elegant, sleek, beautiful):

1. Feeling — what the visitor feels in 3 seconds (uncomfortable, sensory, specific — "watched by something invisible", not "professional").
2. Audience + anti-audience — one real person it's for, and, just as load-bearing, who it's not for.
3. Hero object — the one thing the first screen shows (usually not "the product").
4. Job — one verb the design does (seduce / convince / disarm), not two done badly.
5. The cut — which 60–80% of the usual sections are deleted (sharpness is subtraction).
6. Three-second memory — the one image/word/feeling a visitor would describe to a friend.

Then extract three logics — color (the relationship, not hex), type (the contrast, not fonts), spatial (the point of view). These six decisions + three logics ARE the KB query and the token values; a brief that survives this is specific enough that the hit (or synthesis) is sharp, not generic. (Adapted from the decision-maker reference — ref-deep-analysis G17. This is the anti-slop front of design: vague designs prompt slop.)

Step 1 — query the KB (do this before choosing anything), using the sharp brief + the 3 logics. Search palette, style, and type-pairing:

python library/systems/knowledge/kb-system.py query --intent "<product + vibe>" --room ui-palette
python library/systems/knowledge/kb-system.py query --intent "<product + vibe>" --room ui-style
python library/systems/knowledge/kb-system.py query --intent "<product + vibe>" --room type-pairing

Step 2 — hit vs miss.

• Hit (resolution=hit): adopt the matched palette/style/pairing as the starting contract; cite the drawer id in the receipt. Tune values to the brief — the KB seeds the decision, it does not end it.

• Miss: research and synthesize a bespoke palette/style/pairing, then write it back so the niche becomes a hit next time:

  python library/systems/knowledge/kb-system.py write-back --topic "ui-palette: <niche> — <rationale>" \
    --room ui-palette --evidence "<the chosen tokens>" --confidence 0.7 --source design-brief
  

Step 3 — emit the tokens (the artifact). Build a 3-layer DTCG config (primitive → semantic → component) from the chosen values and emit + validate it:

python library/systems/theme/dtcg-emit.py --config <chosen-tokens.json>

The LLM chooses the values; dtcg-emit emits and validates the artifact (every alias must resolve).

Step 4 — write DESIGN.md. Fill references/design-md-template.md with the chosen values; link the emitted token file. DESIGN.md is the human-readable contract; the DTCG file is the machine one.

Mode B — from code

Glob the project's CSS/HTML; extract colors (by frequency + role), fonts, spacing, radii, shadow stance; infer density/variance; fill gaps from a KB query; flag existing values that violate the gate. Then Steps 3–4 as above, and optionally write-back the extracted system as a KB drawer.

Gate (before marking complete)

• No banned primary font (Inter / Roboto / Arial / system-ui as the primary face).
• No pure #000000 / #ffffff in the palette; one accent, saturation < 80%.
• Token policy: every visual value is a token (no raw hex/px in the contract's component layer).
• Section 8 has ≥ 10 named, project-specific bans; Section 9 injection block present (< 10 lines).

A gate failure is fixed before lock, not waived. These mirror the aesthetic gate so the contract passes the audit it primes.

Output

• DESIGN.md at the product root (or .stitch/DESIGN.md if that dir exists) — persistence: Spec-Anchored (versions with the product). The 9-section contract + the AI-generation injection block.
• DTCG tokens JSON (validated by dtcg-emit) — design-as-data the product consumes.
• receipt (<workspace>/receipts/design-brief-receipt.json): base schema + mode, kb_resolution (hit|miss), kb_drawer (cited id on hit), wrote_back (bool), tokens_emitted, design_md_path, gate_checks. persistence: Spec-Anchored.

Proactive Triggers

• KB miss on a common product type: that is a seed gap — synthesize well and write back (don't just emit locally); the KB should learn this niche.
• The brief's adjectives are all banned generic words ("modern, clean, minimal, premium, professional, elegant, sleek, beautiful"): run Step 0 — push back for a sharp feeling + the six decisions before choosing a palette; generic in, generic out.
• dtcg-emit reports an unresolved alias: a semantic/component token points at a missing primitive — fix the config; do not ship an invalid token file.

Completion Criteria

Done when: a DESIGN.md and a validated DTCG token file exist for the project; the KB was queried (and written back on a miss); the gate checklist passes; a design-brief receipt records mode + kb_resolution + gate results.

Not done if: the contract was written from defaults without querying the KB; a banned font or pure black/white survived; the token file has an unresolved alias; it was run for a non-visual target.

Next step: the aesthetic gate audits the built UI against this contract; executor builds screens.

Related Skills

• aesthetic gate: Audits built UI against this contract (Phase B). design-brief writes the contract; the gate enforces it.
• theme system (kb-system, dtcg-emit): the engine design-brief drives. NOT a substitute — the system supplies search + emit; design-brief supplies the judgment.