# User Flow

Map actions, decisions, system responses, and recovery before choosing screen layouts. Start with the first user intent and end with a confirmed outcome.

[Kit README](README.md) · [Project Overview](Project%20Overview.md) · [PRD](Full%20PRD%20Template.md) · [Master Build Prompt](Master%20Build%20Prompt.md) · [Completion Checklist](Project%20Completion%20Checklist.md)

## Primary Flow

| Step | User Intent | User Action | System Response | Data Change | Success Signal |
| --- | --- | --- | --- | --- | --- |
| 1 | Enter the experience | [ENTRY ACTION] | Shows relevant starting context | None or session | User knows the next step |
| 2 | Provide minimum input | [INPUT] | Validates locally and/or server-side | Draft | Specific errors if invalid |
| 3 | Request core outcome | [PRIMARY ACTION] | Authorizes and processes | [RECORD/EVENT] | Progress without layout shift |
| 4 | Review result | [CONFIRM/EDIT] | Explains result and limitations | [STATE] | Result matches input |
| 5 | Finish | [SAVE/EXPORT/CONTINUE] | Confirms durable outcome | Final record | understand the offer within ten seconds |

## Alternate Paths

### First-Time User

Explain only prerequisites needed for the next action. Delay optional settings, permissions, or advanced configuration until their value is visible.

### Empty State

State why nothing is shown, whether this is normal, and the one action most likely to create useful data. Do not display a blank chart, table, or canvas without explanation.

### Failure and Recovery

For unclear positioning, oversized media, broken mobile navigation, document the detection signal, user message, preserved state, retry rule, escalation path, and whether the operation might already have succeeded.

### Return Visit

Restore safe context without hiding important changes. Show freshness or sync status if cached data can be stale.

## Flow Review Questions

- [ ] Can the primary task be completed without visiting an unrelated section?
- [ ] Does every decision have a clear default or explanation?
- [ ] Are role and permission changes visible before an action?
- [ ] Can the user cancel, go back, or retry without corrupting state?
- [ ] Does the final confirmation prove what happened instead of merely saying “Done”?
- [ ] Are optional or deferred capabilities absent from the main path?

## Usability Test

Give a participant this task without describing the interface: **“Using [PROJECT NAME], understand the offer within ten seconds.”** Record completion, time, wrong turns, questions, and confidence. Pass when at least [TARGET OF 4/5] representative users complete without coaching and no high-severity issue remains.