Ux Flows

UX Flows

Design every screen by walking the user's journey, not by listing widgets.

The lens

Before building, answer for each state of the flow:

1. What did the user just do? The screen must acknowledge it instantly.
2. What do they want to know right now? Show exactly that — nothing else.
3. What will they most likely do next? Make that the one obvious CTA and lead them into it.
4. Where are they looking / where is their thumb? Feedback appears where they look; primary actions sit in the bottom bar or a bottom sheet (thumb zone). Never bury the next step at the top.

If a component's purpose is an action, the CTA must be unmissable. If its purpose is information, remove every label the content already implies (no "Truck" eyebrow above a plate number).

Questions 1–3 close the Gulf of Execution ("how do I do this?"); question 4 closes the Gulf of Evaluation ("what just happened?"). Mirror the user's mental model from USER-BRIEF.md (/understand-the-user) — the flow should match how they think the task works, not your schema. To make any single screen read clearly at a glance, run /make-it-obvious.

Feedback at its locality

The user's context stays in one place; the consequence of an action shows up right there.

• State changes animate in place (status color/progress on the same card), paired with haptics on mobile.
• Confirmations and results come up from the bottom (bottom sheet on mobile, inline/toast on web) — never navigate away to confirm.
• After creating something: highlight the new item in the list. After deleting: themed toast with Undo — the most likely next wish.
• Celebrate completions (Duolingo-style): one springy check moment at the end of a journey. Don't celebrate intermediate steps — that's noise.

Action weight

Match friction to consequence:

• Harmless / expected action → fires directly, button shows its own spinner.
• Irreversible or bulk action → one confirm sheet stating the consequence in plain words ("This can't be undone") with an easy way out ("Not Yet").
• Legal / responsibility moment → deliberate two-step: explicit checkbox statement gates the CTA.
• Catastrophic / irreversible at scale → a forcing function: type-to-confirm, or an interlock that makes the dangerous path harder than the safe one. Never let a single fat-fingered tap trigger it.

Never stack two celebrations or two confirms in a row.

Errors

• Map error codes to human views in a domain component (title + what happened + what to do), never raw messages.
• The primary CTA is the most likely recovery (Refresh when state is stale, Try Again for network). Dismiss is always available for recoverable errors.
• Errors appear at the same locality as the action that caused them (sheet over the same screen).
• Separate slips (right intent, wrong tap → prevent with constraints and undo) from mistakes (wrong intent → prevent with clearer feedback and a model that matches the user's). A slip needs a guardrail; a mistake needs better understanding.

Empty & loading states

• Empty state greets and points at the single way to begin.
• Every async CTA shows loading on the button itself; full-screen spinners only for initial load.

Modularization

Organize by domain, not by widget type. One common layout (adapt to your framework):

• Domain components (components//) — flow-specific pieces: sheets, summaries, status maps.
• Shared primitives (components/ui/) — reusable building blocks: button, card, checkbox, feedback sheet.
• Behavior layer (hooks//, or your framework's equivalent) — fetching, async + error→result mapping, haptics. View state (which sheet is open) stays inline in the screen.
• Readability over reusability: make components native to their domain instead of building generic abstractions.

Checklist before done

• [ ] Each flow state answers the four lens questions.
• [ ] One primary CTA per screen state, in the thumb zone.
• [ ] No redundant labels; content speaks for itself.
• [ ] Friction matches consequence (direct / confirm / checkbox).
• [ ] Errors are human, local, and lead to recovery.
• [ ] End-of-journey state celebrates, then offers a clean reset.

Once the screens exist, audit them against the heuristics with /ux-review.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JoseArron
• Source: JoseArron/skills
• License: MIT

Install and usage instructions live in the source repository linked above.