Turn a design rationale into outcomes engineers can verify

A mockup shows the layout. It may not explain why the team removed a step, kept a warning, or chose a particular order. Carry those reasons into the proposal so the engineer and coding agent can preserve the intended experience.

The input

A design decision, its reason, and any research behind it. For example:

• Decision: keep signup on one screen.
• Reason: participants lost their place when moving between screens.
• Boundary: the flow must work at a 320px viewport width.

These are illustrative statements. Attach your actual observations before presenting the reason as reviewed evidence. A Figma link or screenshot helps, but include the relevant reasoning in words too.

The flow

1. State the user result. What should become possible or easier? “A new user can complete signup without losing their entered details” describes behavior. A one-screen layout is a design decision about how to deliver it.

2. Record the choice and reason. Preserve the selected approach, alternatives you considered, and why you chose it. If the layout itself is mandatory, say so as a constraint rather than expecting the agent to infer it from a picture.

3. Attach the supporting observations. Capture the research in Evidence, review the relevant signals, and link them to the exact claims they support. A participant quote can support the problem without proving that the proposed layout will solve it.

4. Separate success from safeguards. Define the behavior the engineer can check at 320px. Record a requirement such as “signup completion must not fall below baseline” as a health metric, with a measurement plan. It is not proof of improvement from a single build check.

5. Review the agent’s interpretation. Give the design and reasoning to the coding agent. Compare its proposal with your request, correct anything that changes the intended experience, and review the revision before approval.

The output

• User-visible outcomes with concrete verification checks.
• Design decisions and reasons that remain available for later changes.
• Hard boundaries distinguished from preferences.
• Research backing distinguished from assumptions about the solution.

Try it with one design decision

Choose a decision you have had to explain more than once. Write the user result, the chosen design, the reason, and what would make you reconsider. Check whether the proposal preserves all four.

Related

• Anchor every outcome to user evidence
• Catch the experience gaps in a spec before build
• Review and correct an agent's proposal before it builds