design shaping · file structure

How the design file is organised

The wireframes themselves are made in Figma (or whatever spatial tool the team uses) and cannot be reproduced in a printed volume. What can be described is how the file is structured — because the structure is where meaning is carried or lost.

One file per Feature. One page per Epic. States as named frames inside each page.

A Feature Brief for Gal's grading produces one Figma file: Exam Grading. Inside it, one page per Epic: Grade and mark, Review and correct, Submit to school. Inside each page, frames named for what the person experiences: all-students-overview, per-student-marking, submission-confirm, school-unreachable. The names are the same ones the developer will see in the test file, the Gherkin Given, and the PR title.

What lives on each Figma page

• Current-state flow — drawn first, from discovery. Gal's actual steps today, friction points visible. Not a design; a record.
• New-flow diagram — happy path, then edges, then errors. Each node corresponds to a named frame.
• Wireframe frames — named for what the person experiences. The name travels: per-student-marking in the flow, in the frame, in the Gherkin, in the test, in the PR.
• Annotations — brief references, friction-mark links, open questions for amigos.

When the flow is settled and the states are named, fidelity increases — for release-1 stories only. Release-2 and release-3 frames stay at fat-marker resolution until their stories approach amigos.

Types of flow the team draws

Different questions need different diagrams. The designer and tech lead each reach for the one that answers the question in front of them:

• User flow (design shaping) — how the person moves through the experience. Nodes are named states; edges are actions the person takes.
• Sequence diagram (technical shaping) — how a request moves through services. Actors across the top; messages down. Covered in Part Four.
• State machine — what a thing can become over time. Used when transitions matter more than sequence.
• Data flow — how data moves between systems, especially at integration boundaries.

Next — How design and technical artifacts cross-reference →