Ux Flow Designer

UX Flow Designer

Bridge between Product (PRD/features) and Visual Design. Generate user flow documentation, Mermaid diagrams, and HTML wireframes.

Role and Context

• Input: PRD (docs/product/prd.md) or user-provided feature descriptions
• Output: Diagrams + wireframes in docs/ux-flows/
• Downstream: Outputs feed into ui-ux-pro-max for visual design
• Standalone: Usable independently or as saas-pipeline Phase 4 step 1

Prerequisites

On every invocation, verify:

CHECK ~/.claude/skills/ui-ux-pro-max/ exists
  IF missing → READ references/install-commands.md, offer install

CHECK docs/product/prd.md exists
  IF missing → CHECK ~/.claude/skills/product-manager-toolkit/
    IF missing → READ references/install-commands.md, offer install
    OR accept direct user input as feature descriptions

IF user mentions "figma" or "export to figma" →
  INFORM user of all requirements (see "Figma Export" section below)
  WAIT for user confirmation before reading references/figma-integration.md or checking MCPs

Workflow

Designing app flows involves these steps. ALL four phases are mandatory and must be executed in order.

1. Extract use cases (from PRD or user input) 2. Generate Mermaid flow diagrams (screen map + per use case) 3. Generate HTML wireframes as a clickable prototype (with inter-screen navigation) and offer browser preview — NEVER skip this phase 4. Consolidate into master handoff document

---

Phase 1 — Use Case Extraction

Read docs/product/prd.md if it exists. If no PRD, ask user for feature list or use case descriptions.

For each use case, document:

Save to docs/ux-flows/use-cases.md.

Present the use case list to user for approval before proceeding. Do not advance to Phase 2 without explicit confirmation.

---

Phase 2 — Mermaid Diagrams

Read references/mermaid-patterns.md for syntax patterns and best practices.

Step 1: Master Screen Map

Generate docs/ux-flows/diagrams/screen-map.md — a flowchart showing ALL screens and general navigation paths of the entire app.

Step 2: Per Use Case Diagrams

For each approved use case, generate 3 diagrams:

1. Flowchart (graph TD) — screen-to-screen navigation with decision nodes 2. State diagram (stateDiagram-v2) — app states (loading, error, success, idle, etc.) 3. Sequence diagram (sequenceDiagram) — frontend-backend interaction with HTTP methods

Save to docs/ux-flows/diagrams/{use-case-id}/:

• flow.md — flowchart
• states.md — state diagram
• sequence.md — sequence diagram

Constraints:

• Max 15-20 nodes per diagram
• Split into sub-flows if more complex (link with click or reference)
• Use classDef for consistent styling across diagrams

Generate index at docs/ux-flows/diagrams/INDEX.md listing all diagrams with links.

---

Phase 3 — HTML Wireframes (Clickable Prototype)

MANDATORY: This phase MUST NOT be skipped, summarized, or deferred. Every invocation of this skill that reaches Phase 2 MUST continue to Phase 3. Do not ask the user whether to proceed — just do it.

Step 1: Generate HTML files

For each unique screen identified in the flowcharts, generate an HTML file using assets/wireframe-template.html as the base template.

Requirements:

• Self-contained: inline CSS only, no external dependencies
• Mobile-first: 375px viewport width
• Wireframe aesthetic: grays (#f5f5f5 bg), dashed borders (#ccc), placeholder text (#666)
• Use template CSS classes: .wf-header, .wf-input, .wf-button, .wf-card, .wf-nav, .wf-list-item, .wf-tab-bar, .wf-icon-placeholder, .wf-link, .wf-back
• Include screen name and related use case in footer metadata

Step 2: Add inter-screen navigation

Every wireframe must link to other screens using <a href="target.html" class="wf-link">. This creates a clickable prototype navigable in any browser — no JavaScript needed.

Navigation rules:

• Buttons that logically navigate: wrap in <a href="target.html" class="wf-link"><div class="wf-button">Label</div></a>
• Tab bar: each tab is an <a class="wf-link"> pointing to its screen. Tab bar must be consistent across all screens that share it.
• Back buttons: <a href="previous.html" class="wf-link wf-back">&larr; Back</a> in the .wf-nav bar
• Tappable list items: wrap in <a href="detail.html" class="wf-link"><div class="wf-list-item">...</div></a>
• Tappable cards: wrap in <a href="target.html" class="wf-link"><div class="wf-card">...</div></a>
• No dead ends: every screen must have at least one outgoing link (back button, tab bar, or action button)
• No JavaScript: pure HTML <a> navigation only — no onclick, no form submissions, no JS

Step 3: Save and generate index

Save all wireframes to docs/ux-flows/wireframes/.

Generate inventory at docs/ux-flows/wireframes/INDEX.md:

Step 4: Offer browser preview

After generating all wireframes, propose opening the main entry screen in the browser:

• If Chrome DevTools MCP is available: use navigate_page to open the file
• Fallback: use open docs/ux-flows/wireframes/{entry-screen}.html via Bash

Do not wait for the user to ask — proactively offer the preview.

---

Phase 4 — Consolidation and Handoff

Generate master document docs/ux-flows/UX-FLOWS.md:

# UX Flows — [App Name]

## Master Screen Map
Link to screen-map.md

## Screen Inventory
| Screen | Purpose | Wireframe | Use Cases |
|--------|---------|-----------|-----------|
| ...    | ...     | link      | UC-001    |

## Use Case Diagrams
### UC-001: [Name]
- Flow: link
- States: link
- Sequence: link

## Clickable Prototype Links
| From Screen | Element | To Screen |
|-------------|---------|-----------|
| login.html  | [Login] button | home.html |
| ...         | ...     | ...       |

## Navigation Patterns
Summary of recurring navigation patterns (tab bar, back navigation,
modal flows, drawer menus, etc.)

## Open Questions
Design decisions and open questions for ui-ux-pro-max phase.

After completing the handoff document, inform the user:

• The wireframes can be exported to Figma using the official Code to Canvas integration
• Only requires Figma desktop app with Dev Mode MCP Server enabled (2-step setup)
• If interested, the user can request "export to figma" and the setup steps will be presented

---

Output Structure

docs/ux-flows/
├── UX-FLOWS.md                          # Master handoff document
├── use-cases.md                         # All use cases
├── diagrams/
│   ├── INDEX.md                         # Diagram index
│   ├── screen-map.md                    # Master app navigation
│   ├── uc-001-{name}/
│   │   ├── flow.md                      # Flowchart
│   │   ├── states.md                    # State diagram
│   │   └── sequence.md                  # Sequence diagram
│   └── ...
└── wireframes/
    ├── INDEX.md                         # Screen inventory
    ├── home.html
    ├── login.html
    └── ...

Figma Export (Optional)

This skill can export wireframes to Figma. Do not check for Figma MCP automatically.

When to mention: At the end of Phase 4 (handoff), inform the user that Figma export is available as an optional next step.

When the user requests Figma export, follow this protocol: 1. First: Inform the requirements before attempting anything:

• Figma desktop app with Dev Mode MCP Server enabled (Preferences → Enable "Dev Mode MCP Server")
• MCP added to Claude Code: claude mcp add --transport sse figma-dev-mode-mcp-server http://127.0.0.1:3845/sse
• Chrome DevTools MCP (already used for wireframe preview)
• See full details in references/figma-integration.md

2. Then: Ask user to confirm they have or want to set up these prerequisites 3. Only then: Read references/figma-integration.md and follow the export workflow

Never silently attempt Figma operations. Always present the requirements first.

UX Flow Designer

Claude Code skill that bridges the gap between Product (PRD) and Visual Design by generating user flow documentation, Mermaid diagrams, and HTML wireframes.

What It Does

Given a PRD or feature descriptions, this skill generates:

• Use case documentation — actors, flows, preconditions, postconditions
• Mermaid diagrams — flowcharts, state diagrams, and sequence diagrams per use case
• Master screen map — full app navigation overview
• Clickable HTML prototype — mobile-first wireframes with inter-screen navigation, previewable in any browser
• Handoff document — consolidated index linking all artifacts

Output Structure

docs/ux-flows/
├── UX-FLOWS.md              # Master handoff document
├── use-cases.md              # All use cases
├── diagrams/
│   ├── INDEX.md              # Diagram index
│   ├── screen-map.md         # Master app navigation
│   └── uc-001-{name}/
│       ├── flow.md           # Flowchart (graph TD)
│       ├── states.md         # State diagram (stateDiagram-v2)
│       └── sequence.md       # Sequence diagram
└── wireframes/
    ├── INDEX.md              # Screen inventory
    ├── home.html
    ├── login.html
    └── ...

Installation

# Copy the skill to your Claude Code skills directory
cp -r ux-flow-designer ~/.claude/skills/

Usage

The skill activates when you mention flows, wireframes, user journeys, screen maps, navigation flows, or use cases. Examples:

"Design the user flows for my task management app"
"Create wireframes for the onboarding flow"
"Generate a screen map for the app"
"Document the use cases from the PRD"

Workflow

1. Use Case Extraction — Reads PRD or accepts feature descriptions, documents use cases, asks for approval 2. Mermaid Diagrams — Generates master screen map + 3 diagrams per use case (flow, states, sequence) 3. Clickable Prototype — Creates mobile-first wireframes with inter-screen <a> navigation and offers browser preview 4. Consolidation — Produces master handoff document linking all artifacts

Skill Contents

ux-flow-designer/
├── SKILL.md                              # Skill definition and workflow
├── references/
│   ├── mermaid-patterns.md               # Mermaid syntax patterns and examples
│   ├── figma-integration.md              # Figma export toolchain (optional)
│   └── install-commands.md               # Related skills and tools
└── assets/
    └── wireframe-template.html           # HTML wireframe base template

Optional Integrations

License

MIT

Figma Integration

Only load this file when user explicitly requests Figma export.

Table of Contents

• Code to Canvas
• Export Workflow

---

Code to Canvas

Figma's official Code to Canvas integration captures rendered UI from the browser and converts it into editable Figma frames.

Requirements

Setup (2 steps)

1. Enable Dev Mode MCP Server in Figma desktop:

• Open Figma desktop → Preferences → Enable "Dev Mode MCP Server"

2. Add the MCP to Claude Code:

   claude mcp add --transport sse figma-dev-mode-mcp-server http://127.0.0.1:3845/sse

Capabilities

• Bidirectional: Code → Figma and Figma → Code
• Semantic reading: Understands components, variables, styles, and layout structure
• Browser capture: Converts rendered HTML directly into editable Figma frames
• Official support: Maintained by Figma

---

Export Workflow

Prerequisites

1. Figma desktop app with Dev Mode MCP Server enabled 2. Chrome DevTools MCP installed (already used for wireframe preview in Phase 3) 3. Connection verified: Dev Mode MCP Server responding on http://127.0.0.1:3845/sse

Steps

1. Verify toolchain

• Check Dev Mode MCP Server is active in Figma desktop
• Check Chrome DevTools MCP is available
• Offer install commands for any missing tool (see references/install-commands.md)

2. Open wireframes in browser

• Use Chrome DevTools MCP or open to load each wireframe from docs/ux-flows/wireframes/
• Wireframes are already mobile-first (375px) from Phase 3

3. Send to Figma

• For each wireframe open in the browser, use "Send this to Figma" via the Dev Mode MCP
• Each screen becomes an editable Figma frame

4. Organize in Figma

• Group frames by use case flow
• Add flow connections between screens
• Name all frames matching the screen inventory from docs/ux-flows/wireframes/INDEX.md

5. Apply design tokens (if design system exists)

• Read existing design tokens via the MCP
• Map wireframe elements to design tokens
• Apply colors, typography, spacing

Install Commands

Tools, skills, and MCPs that ux-flow-designer can propose to the user.

Auxiliary Skills

Figma MCP (only if user requests Figma)

Browser Preview MCP

Mermaid Diagram Patterns

Ready-to-use syntax patterns for UX flow diagrams.

Table of Contents

• Flowchart Patterns
• State Diagram Patterns
• Sequence Diagram Patterns
• Best Practices

---

Flowchart Patterns

Node Shapes

Use consistent shapes across all flowcharts:

[Screen Name]       — Rectangle: screens/pages
{Decision?}         — Diamond: conditional branch
((Start))           — Circle: entry point
([Action])          — Stadium: user action
[[Sub-flow]]        — Subroutine: link to another diagram
>Result]            — Asymmetric: outcome/redirect

Subgraphs for Screen Groups

Group related screens:

graph TD
    subgraph Auth["Authentication"]
        Login[Login Screen]
        Register[Register Screen]
        ForgotPW[Forgot Password]
    end

    subgraph Main["Main App"]
        Home[Home Screen]
        Profile[Profile Screen]
        Settings[Settings Screen]
    end

    Login -->|Success| Home
    Login -->|New User| Register
    Login -->|Forgot| ForgotPW
    Register -->|Complete| Home
    Home --> Profile
    Home --> Settings

Complete Login Flow Example

graph TD
    Start((Entry)) --> Splash[Splash Screen]
    Splash --> CheckAuth{Authenticated?}
    CheckAuth -->|Yes| Home[Home Screen]
    CheckAuth -->|No| Login[Login Screen]

    Login --> InputCreds([Enter Credentials])
    InputCreds --> Validate{Valid?}
    Validate -->|Yes| Home
    Validate -->|No| ShowError([Show Error])
    ShowError --> Login

    Login -->|Forgot Password| ForgotPW[Forgot Password]
    ForgotPW --> SendEmail([Send Reset Email])
    SendEmail --> Login

    Login -->|Sign Up| Register[Register Screen]
    Register --> FillForm([Fill Form])
    FillForm --> ValidateForm{Valid?}
    ValidateForm -->|Yes| VerifyEmail[Verify Email]
    ValidateForm -->|No| ShowRegError([Show Error])
    ShowRegError --> Register
    VerifyEmail --> Home

    classDef screen fill:#e8e8e8,stroke:#999,stroke-width:2px
    classDef decision fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    classDef action fill:#d4edda,stroke:#28a745,stroke-width:1px
    class Login,Register,ForgotPW,Home,Splash,VerifyEmail screen
    class CheckAuth,Validate,ValidateForm decision
    class InputCreds,ShowError,SendEmail,FillForm,ShowRegError action

Decision Branches

graph TD
    Screen[Current Screen] --> Action([User Action])
    Action --> Check{Condition?}
    Check -->|Option A| ScreenA[Screen A]
    Check -->|Option B| ScreenB[Screen B]
    Check -->|Option C| ScreenC[Screen C]

---

State Diagram Patterns

Basic State Transitions

stateDiagram-v2
    [*] --> Idle
    Idle --> Loading: Submit
    Loading --> Success: 200 OK
    Loading --> Error: 4xx/5xx
    Error --> Idle: Retry
    Success --> [*]

Nested States

Use nested states for complex screen behaviors:

stateDiagram-v2
    [*] --> FormScreen

    state FormScreen {
        [*] --> Empty
        Empty --> Filling: User Types
        Filling --> Validating: Submit
        Validating --> Invalid: Validation Error
        Validating --> Submitting: Valid
        Invalid --> Filling: Edit
        Submitting --> Success: 200
        Submitting --> ServerError: 5xx
        ServerError --> Filling: Retry
        Success --> [*]
    }

Parallel States

For screens with independent state regions:

stateDiagram-v2
    state Dashboard {
        state "Data Section" as Data {
            [*] --> DataLoading
            DataLoading --> DataLoaded: Fetched
            DataLoading --> DataError: Failed
        }
        --
        state "Notifications" as Notif {
            [*] --> NotifIdle
            NotifIdle --> NotifNew: Push
            NotifNew --> NotifIdle: Dismiss
        }
    }

Auth Flow States Example

stateDiagram-v2
    [*] --> Unauthenticated

    state Unauthenticated {
        [*] --> LoginIdle
        LoginIdle --> Authenticating: Submit Credentials
        Authenticating --> LoginError: Invalid Credentials
        Authenticating --> TokenReceived: Valid Credentials
        LoginError --> LoginIdle: Retry
    }

    TokenReceived --> Authenticated

    state Authenticated {
        [*] --> SessionActive
        SessionActive --> SessionExpiring: Token Near Expiry
        SessionExpiring --> SessionActive: Token Refreshed
        SessionExpiring --> SessionExpired: Refresh Failed
    }

    SessionExpired --> Unauthenticated
    Authenticated --> Unauthenticated: Logout

---

Sequence Diagram Patterns

Basic Request Flow

sequenceDiagram
    actor User
    participant App as App (Frontend)
    participant API as API Server
    participant DB as Database

    User->>App: Tap Submit
    App->>API: POST /resource
    API->>DB: INSERT INTO resource
    DB-->>API: OK
    API-->>App: 201 Created
    App-->>User: Show Success

Authenticated Request Example

sequenceDiagram
    actor User
    participant App as App (Frontend)
    participant API as API Server
    participant Auth as Auth Service
    participant DB as Database

    User->>App: Enter email + password
    App->>Auth: POST /auth/login {email, password}
    Auth->>DB: SELECT user WHERE email=?
    DB-->>Auth: User record
    Auth->>Auth: Verify password hash

    alt Valid credentials
        Auth-->>App: 200 {accessToken, refreshToken}
        App->>App: Store tokens
        App-->>User: Navigate to Home
    else Invalid credentials
        Auth-->>App: 401 Unauthorized
        App-->>User: Show error message
    end

    Note over App,API: Subsequent authenticated requests

    User->>App: Request data
    App->>API: GET /data (Authorization: Bearer token)
    API->>Auth: Validate token

    alt Token valid
        Auth-->>API: User context
        API->>DB: Query data
        DB-->>API: Results
        API-->>App: 200 {data}
        App-->>User: Display data
    else Token expired
        Auth-->>API: 401
        API-->>App: 401
        App->>Auth: POST /auth/refresh {refreshToken}
        Auth-->>App: 200 {newAccessToken}
        App->>API: Retry GET /data
        API-->>App: 200 {data}
        App-->>User: Display data
    end

Error Handling Pattern

sequenceDiagram
    actor User
    participant App as App (Frontend)
    participant API as API Server

    User->>App: Action
    App->>App: Show loading state
    App->>API: Request

    alt Success
        API-->>App: 200 OK
        App->>App: Update state
        App-->>User: Show result
    else Client Error
        API-->>App: 400/422 {errors}
        App-->>User: Show validation errors
    else Server Error
        API-->>App: 500
        App-->>User: Show generic error + retry
    else Network Error
        App->>App: Timeout/no connection
        App-->>User: Show offline message
    end

Actors Reference

Standard actors for UX flow diagrams:

---

Best Practices

Diagram Size

• Max 15-20 nodes per diagram
• If more complex, split into sub-flows with cross-references
• Use subgraphs to group related screens (max 3-4 subgraphs)

Splitting Complex Flows

When a flow exceeds 20 nodes:

1. Identify logical boundaries (auth, onboarding, core feature) 2. Create a high-level flow with [[Sub-flow]] nodes 3. Create separate detailed diagrams for each sub-flow 4. Link with a note: See: uc-001/flow-checkout.md

Consistent Styling

Define classDef once and reuse across all diagrams:

classDef screen fill:#e8e8e8,stroke:#999,stroke-width:2px
classDef decision fill:#fff3cd,stroke:#ffc107,stroke-width:2px
classDef action fill:#d4edda,stroke:#28a745,stroke-width:1px
classDef error fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Naming Conventions

• Screens: PascalCase — HomeScreen, LoginScreen
• Actions: camelCase verbs — submitForm, loadData
• States: PascalCase — Loading, Error, Success
• Edges: Short labels — Success, Fail, Tap, Submit

File Naming

• Use kebab-case: screen-map.md, flow.md, states.md
• Use case folders: uc-001-registration/, uc-002-login/