fattain-naime/engineering-docs/ux-flow-specification

Purpose

Produce a UX flow specification that documents how a user moves through a product: the information architecture, the step-by-step journey for each key task, every screen involved, and every state each screen can be in.

A flow spec is not a visual design. It says "after a failed payment, the user sees an inline error on the same screen with the amount preserved and a retry button" - it does not say what color that error is. Visual language belongs in design-system-specification; this document belongs to behavior and structure.

Input

Works best with: The name of the product or feature and the primary task(s) a user is trying to accomplish. Also valuable: Existing personas or user research, known edge cases, any regulatory or accessibility requirements affecting flow (e.g., mandatory confirmation steps).

Example invocation: Document the user flow for account signup through first successful login. Users sign up with email, verify via a emailed code, set a password, and land on an empty-state dashboard. Needs to handle: expired verification code, wrong code entry, and a user who already has an account.

Key Concepts

Information Architecture (IA)

The structural map of every screen/page in the product and how they nest or relate - the site map. IA answers "where does this screen live and how does a user get there," independent of any single task flow.

User Journeys vs. Screen Flows

• User Journey: The end-to-end narrative of a user accomplishing a goal, often crossing multiple sessions or channels (e.g., "discovers product → signs up → completes onboarding → invites a teammate").
• Screen Flow: The literal sequence of screens and user actions for one specific task (e.g., the exact screens involved in "reset password").

Document journeys for the big picture, screen flows for implementation-level precision.

The Four States Every Screen Needs

A screen isn't specified until all of these are described:

• Loading - what shows while data is being fetched
• Empty - what shows when there is legitimately no data yet (first-time use, not an error)
• Error - what shows when something failed, and what recovery action is offered
• Populated / Success - the normal, expected state

Omitting any of these is the single most common source of "the happy path works but everything else is undefined" bugs.

Navigation and Recovery

Every screen needs an answer to: how does a user get here, and how do they leave (forward, back, or abandon)? Dead ends - screens with no way out except closing the app - are a UX defect to catch at spec time, not discover in testing.

Accessibility in Flow (not just visual)

Keyboard/tab order through a screen, focus management after an action (e.g., where does focus land after a modal closes), and whether a flow can be completed without a mouse or without sight are flow-level concerns, not just visual ones.

Responsive / Multi-Device Flows

When a product is used across devices (desktop, tablet, mobile), specify how the flow adapts:

• Breakpoint behavior: What elements collapse, hide, or reflow at each breakpoint?
• Touch vs. pointer: What interactions change? (e.g., hover states become tap-and-hold, swipe replaces click-and-drag)
• Context-aware defaults: Does the mobile experience prioritize different actions? (e.g., "quick approve" button prominent on mobile, full detail view on desktop)
• Cross-device continuity: Can a user start a flow on one device and continue on another? What state is preserved?

State Management (Client-Side and Offline)

Specify how the application manages state across the flow:

• Form state: What happens to partially-filled forms on navigation away, browser refresh, or network loss?
• Undo / redo: Which actions support undo? How far back can the user go?
• Offline behavior: What can the user do without connectivity? What is queued for sync? What fails immediately?
• Client-side caching: What data is cached locally for instant display? When does it become stale?

Animation and Transition Specification

Animations are not decoration — they communicate state changes and guide attention. Specify:

• Purposeful transitions: What state change does this animation communicate? (e.g., slide-left = forward navigation, fade = content update)
• Duration and easing: Keep under 300ms for UI transitions; use ease-out for entrances, ease-in for exits
• Reduced motion: Respect prefers-reduced-motion — provide instant alternatives for all animations
• Loading indicators: Skeleton screens for content, spinners for actions, progress bars for known-duration operations

Error Taxonomy

Classify every error a user can encounter and specify the recovery path for each:

Confirmation Patterns

Define when and how the system asks users to confirm actions:

• Destructive actions: Always require explicit confirmation for irreversible operations (delete, revoke, publish). Use a confirmation modal with the action name and consequence stated.
• Undo over confirmation: For reversible actions, prefer undo (toast with "Undo" button for 5-10 seconds) over blocking confirmation dialogs.
• Double confirmation: For catastrophic actions (delete organization, revoke all access), require typing the resource name or entering a code.
• Confirmation placement: Inline for minor actions, modal for significant actions, full-page for account-level changes.

Notification Patterns

Define how the system communicates with users across contexts:

Conflict Resolution

When your analysis conflicts with the user's stated preference:

1. Present both positions — show your analysis and their preference side by side
2. Explain the trade-off — what are the consequences of each choice?
3. Recommend with reasoning — state your recommendation and why
4. Respect the user's decision — they own the final call
5. Document the decision — record it as an [owner-specified] override with reasoning

Document Length

Target length: 5-10 pages (excluding appendices).

Shorter is better than longer. If the document exceeds the target, check for:

• Redundant content that can be cut
• Overly verbose explanations
• Content that belongs in a separate reference document
• Material the agent already knows (don't explain what HTTP is)

If the document is significantly shorter than the target, check for:

• Missing sections
• Insufficient detail in critical areas
• Unaddressed edge cases

Application

Phase 1: Socratic Clarification & Brainstorming (Mandatory Interview)

Interview Mechanism: Use tool calls (e.g., AskUserQuestion) to present questions — do NOT ask inline in the conversation. The user selects from options rather than typing responses. One question per tool call, multiple-choice options preferred, with "I don't know, you decide" as an escape hatch.

Context Loading: Before asking ANY questions, read ALL prior documents in .engineering-docs/ to extract already-known information. Look for:

• Team size, budget, timeline (from business-plan)
• Tech stack, hosting (from system-architecture)
• Target users, JTBD (from user-personas)
• Constraints, regulatory requirements (from business-plan)
• Scope, features (from technical-specification)

If information exists in a prior document, USE IT — do not re-ask.

Maximum 2-3 questions per skill. Only ask about:

• Skill-specific details not covered in prior documents
• Technical decisions that affect this specific document
• Clarifications on ambiguous requirements

Ask questions to resolve:

1. Primary task(s): What is the single most important thing a user is trying to accomplish in this flow?
2. Known edge cases: Are there specific failure modes, permission levels, or unusual paths that must be handled (e.g., expired session, no data yet, insufficient permissions)?

Wait for the user's response to these questions before drafting the final specification.

Phase 2: Information Architecture (60 min)

Map every screen/page and how they nest or link. Produce a site map.

Phase 3: User Journey Mapping (40-60 min)

Narrate the end-to-end journey(s) for the primary task(s), including any cross-session or multi-channel steps.

Phase 4: Screen-by-Screen Flow (2-3 hrs)

For each screen in the journey: entry point, primary action(s), all four states (loading/empty/error/success), and every exit/navigation option.

Phase 5: Edge Cases and Recovery Paths (40-60 min)

Walk through every known failure mode and unusual path. Ensure none result in a dead end.

Phase 6: Accessibility Pass (30-40 min)

Verify keyboard navigation order, focus management, and that the flow is completable without a mouse.

Phase 7: Revision (After User Review)

If the user requests changes after reviewing the document:

1. Read the user's feedback carefully — understand what they want changed
2. Check for conflicts — does the requested change conflict with prior documents?
3. Apply changes — update the document
4. Re-run consistency check — verify the change doesn't break cross-document consistency
5. Update metadata — set last_updated to today's date
6. Confirm with user — show the changes and get approval

Gotchas