/design-flow

Design a complete user flow at the right altitude. Most flow design fails because it stops at the happy path — this skill walks the full surface (decisions, branches, edge cases, recovery) and outputs something engineers can actually build.

When to use

• Designing a new feature flow before any UI work.
• Spec'ing an existing flow that's never been documented.
• Translating a vague product goal ("we need onboarding") into a concrete user-facing journey.
• Comparing your flow against how Stripe / Linear / Notion / Shopify handle the same problem.

Operating method — ASK FIRST

Before designing anything, get answers in one round:

1. Who is the user? Persona + context. Not "a user" — "a small-business owner whose first action is connecting a bank account on a phone."
2. What's their goal? The thing they want completed.
3. What's the success criterion? Measurable. "First-time user can complete in under 90 seconds, ≤ 3 attempts."
4. What's the entry point? Where do they arrive from? Email link, marketing CTA, in-app banner, deep link from another product?
5. What's the hardest case? The edge that's breaking it today (or the case you're worried about).
6. What constraints? Compliance (KYC, GDPR consent), accessibility, mobile-first, third-party integrations.

Do not start designing without these. Designing the wrong flow takes the same time as designing the right one — and one of them ships.

Method

1. Story altitude

Walk the journey end to end in plain language. 5–12 numbered steps. Each step:

• Where the user is (URL / screen / state).
• What they see.
• What they decide.
• What they do.
• What the system responds.

This pass tests whether the journey is coherent before any wireframing.

2. Decisions and branches

Every flow has decisions. Build a table:

Every alternative path that's reachable must have its own design. Branches you don't design will break in production.

3. Edge cases

Walk these explicitly:

• Empty state — first-time, no data yet.
• Partial state — some required info missing.
• Long content — names with 200 characters, lists with 10K items.
• Special characters — emoji, RTL text, accents, zero-width.
• Slow network — what's shown for 5+ seconds?
• Offline — the network drops mid-flow.
• Returning user mid-flow — they bailed yesterday, came back today; resume or restart?
• Permission denied — the user lacks the role for this action.
• Concurrent edit — two people editing the same resource.
• Account state — suspended, past-due, trial-expired, archived.
• Locale / timezone — date display, currency, number formats.
• Accessibility — keyboard-only flow, screen-reader sense, reduced motion.

Each relevant edge case needs a planned response.

4. Microcopy hooks

For every screen, name the strings that matter:

• Page title / heading.
• Primary CTA label.
• Secondary action.
• Field labels.
• Error messages (per failure mode).
• Empty-state explanation + CTA.
• Success confirmation.

Don't ship "Submit" or "Error: invalid input." Specify the actual copy. Voice and tone come from the project's existing convention (read existing UI for the pattern); fall back to direct, friendly, verb-led if no convention exists.

5. Compare to prior art (optional)

For flows that have a thousand prior implementations (signup, checkout, password reset, invitations, onboarding), look at how 2–3 mature products handle it before designing. The /competitive-analysis skill is the deep version of this. For a quick check, just name the references in the output: "Stripe handles this with X; we'll differ because Y."

6. Save the design

Write the result to .claude/memory/project/flow-<name>.md so future sessions inherit it. Add to MEMORY.md index.

Output format

## Flow: <name>

### Goal
<one sentence>

### User
<persona — specific>

### Success criterion
<measurable>

### Entry points
- <where they come from>
- <where they come from>

### Story
1. User arrives at <X> from <source>. They see <screen 1 summary>. They <action>.
2. System <response>. User sees <screen 2 summary>. They decide <decision 1>.
3. …

### Screens (state-by-state)
| Screen | Purpose | States needed | Key components |
|---|---|---|---|
| /signup | First-touch | default, error (email taken), loading | Email input, primary CTA, OAuth alts |
| /signup/verify | Confirm code | default, code-sent, error (bad code), expired | Code input, resend link, change-email link |
| …

### Decisions and branches
[table]

### Edge cases
- <case 1> — handled how
- <case 2> — handled how

### Microcopy
| Screen | Element | Copy |
|---|---|---|
| /signup | Page title | "Create your account" |
| /signup | Primary CTA | "Send magic link" |
| /signup | Error: email taken | "That email's already in use. Sign in instead?" |
| …

### Open questions for you
1. <question>
2. <question>

### Engineering handoff
- Routes needed: …
- Backend endpoints: …
- New components needed: …
- Reused components: …
- Analytics events to instrument: …

Boundaries

• Don't design without the 6 questions answered. Domain ambiguity makes for irrelevant design.
• Don't draw pixels at story altitude.
• Don't skip edge cases — they're the point.
• Don't design dark patterns. Refuse, name them, offer honest alternatives.
• Don't recommend a flow longer than the goal requires. The shortest flow that covers all states wins.
• Always cite prior art when borrowing patterns from competitors.