A 13-section brief Claude Design reads on its own

Why it stands alone

The file opens with “For Claude Design (paste this file alone) or /design @docs/design-brief.md inside Claude Code. Goal, audience, layout and content are all here; the flows at the end are the exact logic every screen must show.” That is the contract: a pointer at docs/flows/ would point a designer at files they cannot open, so the flows, the legend to read them and the integration calls are embedded. Copy design brief on the done screen puts the file on the clipboard, shown in blue because it goes to a different tool than the other three chips. The same file is in the zip, and the kickoff tells Claude Code to read the design/ folder Claude Design hands off into before planning a milestone with screens.

Sections 1 to 4: product, audience, tone, platform

1. Product is the one-liner, the same sentence as in CLAUDE.md, KICKOFF.md and the spec, followed, when you arrived from Whole system, by “The brief (verbatim — the founder's own words)” in a fenced block. 2. Audience & personas lists the plan's user actors, or the spec's personas when there is no plan, one bullet each with the goal, “uses it on: <platform>” and, when a persona matches, “may: <permissions>”; then “What they struggle with today: <problem>” from the spec's overview and “Systems behind the screens (never personas): …” listing the plan's system, service, database, queue and external actors with their kinds, so nobody designs a screen for the database.

3. Tone & brand gives Tone from the spec's design block or “not stated in the brief — propose three adjectives in the design chat and record them in docs/decisions.md”, Avoid from the same block or a default against decorative illustration that hides a step and labels that paraphrase the flows, and Design system from the reference given or “none — propose one and export its tokens (colors, type scale, spacing) as text with the handoff”. 4. Platform & responsive gives Platform from the spec, or “not stated in the brief — design for web first and confirm (open question)”, fixed breakpoints at 360, 768, 1024 and 1440 px with a 360 px minimum viewport and no horizontal scroll, and Dark mode as not required unless docs/decisions.md says so, with both themes then meeting the contrast numbers of section 9.

Sections 5 to 8: journeys, screens, components, copy

5. Navigation & journey (milestone order) is one numbered line per flow, the milestone order first, in the form “**F1 Saha Tahsilatı** (SC-1 Tahsilat Ekranı): <journey>”. The journey is the happy path walked from the flow text: every top-level step, every decision as “<question> (F1.D2: Evet / Hayır)” followed by the first happy branch marked “(F1.D2.evet)” before the step it leads to, “enter <field> (F1.I1)” for an .input, “wait: <event> (F1.W1)” for a .wait, and “run F3 Prim Hesaplama” or “hand off to F2 Kapanış” for a .do or .go, joined with arrows down to the terminal step. 6. Screen inventory repeats the spec's screen blocks under the same “### SC-n — Name” headings: Purpose, Hosts (the F id), Key elements, Data displayed, Actions as “<label>” → id with the id's text in parentheses, then States: the four fixed ones, empty, loading, error and success, plus any domain state. A screen the spec gave no copy for gets it from the flow: empty before the first .input is entered, loading while the .wait lines or the called sequence are pending, error listing every .fail with its id and recovery, success when the last step is reached; and a flow the spec gave no screen at all gets a derived screen whose key elements are its inputs, decisions, pending waits and hand-off links.

7. Components (reused on ≥ 2 screens) lists every key element that appears, case-insensitively, on two or more screens, and, under the same two-screen rule, the element kinds the flows imply: InputForm (one per .input line), DecisionPrompt (one button per .then label), ErrorState (message from the .fail text, action from the recovery), PendingState (while a .wait or a sequence call is open) and HandoffLink (to the flow a .do or .go names), each with the screens it sits on and its variants. A kind only one flow implies, such as a single flow with an .input, is not listed. With nothing shared the section says “none yet — every screen is unique; name any element you reuse so prompts can reference it”. 8. Copy & content rules: every label, button, status, error and empty-state text uses the exact wording of the flows and the brief in their language; a Terminology line with the flow names, the roles, the status words of every stateful entity and the .then labels as choices; the number, date and currency formats found in your texts, such as 5.000 TL, 30 saniye or 12.03.2026, up to eight of them; and the rule that error copy always shows the recovery the flow prescribes.

Sections 9 to 13: accessibility, order, scope, flows, handoff

9. Accessibility (WCAG 2.2 AA) is four fixed bullets: text contrast at least 4.5:1, large text (24 px, or 19 px bold) and non-text UI parts at least 3:1; pointer targets at least 24 by 24 CSS px, 44 by 44 preferred on touch; every action reachable by keyboard in reading order with a visible focus ring; every input labelled, every error naming the field and the fix, state never conveyed by colour alone. These are the same numbers the spec's appended WCAG row commits to. 10. What to design first: Milestone 1's screens in the order of section 5, success state first; then their error and empty states, every .fail of the entry flow with its recovery; then Milestone 2. It closes with “Design one variant of the first journey, not a canvas of ten; iterate in the chat and record the decisions.” 11. Out of scope for design lists the spec's out-of-scope items and the avoid list; Milestone 1's own out-of-scope ids are deliberately not here, because section 10 asks for exactly those failure states to be drawn.

12. The flows (exact logic — read before drawing) explains that every .if is a decision the user sees or a branch that changes the screen, every .then label a state the UI must show, every .fail an error state with recovery, and .wait and .input pending states or forms; then “How to read a flow” with the process legend, and every ticked flow fenced under “### F1 — Name (design this first) — docs/flows/<slug>.runic”, the first one tagged, the rest headed the same way without the tag. Then “Integration touchpoints the screens must expose”: per sequence diagram a line with its S id, name, file and systems, and a table of ID, Call and Needs on screen, read off the actor kinds: a message from a user needs a visible trigger and a pending state while it waits; a reply to a user needs a result state; a non-reply to a user is a message they receive off-screen, an SMS or a push, and a screen state only where a flow step shows it; a call to an external system after a user trigger is what the pending state waits on and its reply what that state resolves to; a hop to a database, a service or a queue is backend only, printed as nothing visible; a failure section adds a failure state, or the note that it reaches a screen only through a .fail a flow draws; a .loop adds the retry; a message inside an alternative section is marked only in that section. 13. Handoff: Export → “Hand off to Claude Code”, the bundle lands in design/; every decision from the design chat goes into docs/decisions.md with the SC and branch ids it affects; artboards are named SC-n, states by branch id, and a screen missing one of its four states is not finished.

Limits and gotchas

The brief is rendered, never written by a model, so it says only what the spec object, the plan and the flows say. Tone, platform and a design system appear only when the interview or the brief gave them; otherwise the file asks the designer to propose and record. The journey walks the first happy branch of every decision; a decision with no happy branch is passed without entering either branch, and the journey continues with the next step at the same level, or ends at the question when nothing follows it. A screen exists for every ticked process, either from the spec or derived, but a sequence diagram produces no screen of its own, only touchpoints. The state copy for a derived screen is read off the flow's own lines, so a flow with no .input has “nothing to show yet” as its empty state and one with no .fail has a generic error line. Section 12 embeds every ticked flow, which is most of the file's size; a brief for a forty-flow package is long, and Claude Design reads it whole. The file is fixed English apart from the values, which are in the language of your flows and brief.

How to use it

1. 1
   Generate the package

   Click Build, answer the interview and click Generate package. Give the tone, platform and design system in the interview if you have them; they land in sections 3 and 4.
2. 2
   Copy the brief

   On the done screen click Copy design brief, the blue chip. It flips to Copied ✓; the same file is docs/design-brief.md in the zip.
3. 3
   Paste it into Claude Design

   Start a new design and paste the whole file as the first message. Nothing else is needed; the flows and the legend are inside.
4. 4
   Design section 10 first

   Milestone 1's screens in section 5 order, success state first, then their error and empty states. One variant of the first journey, not a canvas of ten.
5. 5
   Hand off to Claude Code

   Export → Hand off to Claude Code and put the bundle in design/ inside the unzipped repo. Step (a) of the kickoff reads it before planning any milestone with screens.
6. 6
   Log the decisions

   Summarise what was decided in the design chat into docs/decisions.md with the SC and branch ids it affects, as section 13 asks.

Commands & shortcuts

Tips

• Write the .then labels as the words you want on the buttons. The brief's DecisionPrompt component has one button per label, and the copy rule forbids paraphrasing them.
• Put the user on the sequence diagram as an actor of kind user. Only then does a message get a visible trigger, a pending state and a result state in the touchpoints table; a diagram of systems alone prints nothing visible.
• Give the platform in the interview, even as one word. Without it section 4 says design for web first and confirm, and every persona's uses it on line points at that open question.
• Name key elements consistently across screens in your answers. A field called Tutar alanı on two screens becomes a component; the same field spelled two ways becomes two.
• Keep the brief and the spec from the same run. The screen headings are byte-identical between them by construction, and the verbatim tell checks it; a brief from an older package names screens the spec no longer has.

Questions