Create design brief

Create Design Brief

Usage

/core-skills:create-design-brief [topic]

Prerequisite

Requires the DesignSync MCP tool (connected to the design project) and the chrome-devtools MCP for evidence capture.

Goal

Turn a design question into a grounded, request-not-decision brief in the design project's briefs/YYYY-MM-DD-<topic>/, so a fresh Claude Design chat can explore it. Produces a design-project artifact, not a repo task (the task comes later via /core-skills:ingest-design, when the handoff returns). Stops before exploration — Claude Design owns that.

Context

The mirror of ingest-design. Briefs are the inbound lane (Code → Design): a grounded problem statement that seeds an exploration. The design project owns the exploration, the recommendation, and the decision — this brief is a request, not a decision.

Runs on the main thread (uses the DesignSync MCP + the chrome-devtools MCP visual loop). It writes only to the design project — no permanent repo footprint (screenshots are captured to a repo temp dir, uploaded, then deleted).

Read the repo's frontend/design guidance doc (e.g. frontend/CLAUDE.md) before grounding, if one exists — this is design/frontend work.

Step 1: Scope the Brief

Identify the design question from the conversation (+ optional [topic] arg): the surface or behaviour to explore. If it's unclear or you find yourself assuming, stop and ask focused questions (recommended options + one-line reasoning), like /at:create-task Step 1. Don't invent specificity.

Step 2: Ground It in Code

Read the relevant frontend code + related tasks / decision records to capture current behaviour and the real, measured facts the design agent can't see — it has the design project's design system, but not this repo:

• Real tokens, selectors, measured values (e.g. the actual :focus-visible rule, a component's current treatment) — read the code / serve the app; never state from memory.
• Don't restate the design project's own DS (accent, borders, density, tokens) — it already knows. Carry only the frontend reality it can't infer.

Step 3: Capture Current-State Evidence

Only when an existing surface is involved (skip for a greenfield surface — nothing to show):

• Serve the app on deterministic fixture data (the project bindings' design-review serve command, if defined) → drive via the chrome-devtools MCP → screenshot the relevant states → crop with magick.
• Save to a temp dir inside the repo (the MCP can't write outside the workspace root). These are upload-only and get deleted in Step 6.
• Optional: a small real-DOM HTML snippet when the designer needs to restyle the actual element, not a mock.
• Evidence documents what exists today — never a proposed solution.

Step 4: Write the Brief

Author the README.md as a grounded problem statement. Sections:

• What to explore — the design question, one or two sentences.
• Current state (grounded) — measured facts + the named elements / tokens; reference the evidence.
• The core problem / constraint — what makes this hard (e.g. a coexistence case).
• Open questions — the calls the design team must resolve and recommend; their decision, not yours.
• Out of scope and Evidence (the files in this folder).

Discipline (the whole point):

• A request, not a decision — pose the problem + options; don't pre-decide the visual.
• Nothing inferable from the design project's own DS — only the frontend reality it can't see.
• Legible to a fresh Claude Design agent. It has the design system, the design project's own handoffs/ / briefs/ / explorations/, and the live app's design language — but not this repo, the task tracker, or Claude Code. Never cite task numbers or statuses (task 102, ready-for-dev), repo file paths (lib/columns.ts), or skill / CLI machinery. Refer to prior design work by its path in this design project (e.g. handoffs/2026-06-26-time-travel-as-of-date/), and describe frontend reality in plain terms, not via repo paths.
• Terse, plain English; point at the DS, don't restate it.

Step 5: User Review

The brief (<temp-dir>/README.md) is the single source of truth. Do NOT paraphrase or summarise it in chat — a second copy drifts. Instead:

1. State that the brief is ready; give its path (and any screenshot paths).
2. Raise only genuinely-open decisions that need the user. Anything else worth saying belongs in the brief, not in chat.
3. Revise on feedback. Get explicit sign-off before Step 6.

Step 6: Push to the Design Project

1. DesignSync list_projects → the design-system project.
2. finalize_plan + write_files into briefs/YYYY-MM-DD-<topic>/ — the README.md + screenshots (folder per topic, mirrors handoffs/).
3. Delete the repo temp dir from Step 3 — no repo footprint.

Step 7: Emit + Copy the Kickoff Prompt

The brief is self-contained (it references its own evidence and the design process is standing-instructed in the design project), so the prompt is a thin pointer — no screenshots, no process recap. Emit exactly this template, with the topic folder filled in:

See `briefs/<YYYY-MM-DD-topic>/README.md` and execute.

Then copy it to the clipboard so the user can paste it straight into a fresh Claude Design chat:

printf 'See `briefs/<YYYY-MM-DD-topic>/README.md` and execute.' | pbcopy

Tell the user it's on the clipboard. Stop here.