AI User Flow Design (Mermaid Diagrams)

User flows are the part of UX work that lives in the designer's head and the whiteboard photo Slack-shared three weeks ago. The flow exists, the team agreed on it, the implementation followed the agreement. The flow itself, as an artifact, is in nobody's repository, in nobody's notion, and not in any kind of reviewable form. The next person who needs to extend the feature reverse-engineers the flow from the running product. The next person who needs to redesign the feature has no anchor for the conversation. The cost is paid in the meetings that re-derive the flow from scratch and the design changes that accidentally remove states the original flow had.

A useful flow artifact has three properties. It captures the screens and decision points the user moves through. It includes the error and edge states, not just the happy path. It is in a format that lives in the codebase next to the implementation rather than in a design tool the engineering team does not open. Mermaid flowcharts hit all three: they live in markdown files, they support branches and decision points, and they are version-controlled with the rest of the codebase. The discipline is to capture the flow at design time rather than describe it verbally and let it disappear. The /draft-flow skill encodes the discipline.

Why generalist AI produces shallow flows

Ask Cursor or ChatGPT to map a user flow. You get a happy-path sequence: signup, dashboard, action, confirmation. The output captures the linear path. It misses the error states (what happens when the form validation fails, when the upload times out, when the user denies email permissions). It misses the decision points (what happens when the user already has an account, when the feature flag is off, when the user has the basic plan rather than premium). It misses the entry and exit points (where does the user land after completing the flow, where do they go if they abandon halfway). The result is a flow that looks complete in a screenshot and breaks the moment a real user encounters anything but the happy path.

The other failure mode is the missing job-to-be-done framing. Flows are best understood as the sequence of steps a user takes to accomplish a specific job (close the books, invite a teammate, export the data). Without the JTBD framing, the flow is structured around features rather than tasks, and the feature-organized flow misses the cross-feature paths users actually take. /draft-flow starts from the JTBD so the flow follows the task, not the team's mental model of the feature.

What a useful flow artifact contains

A flow diagram has five elements. Entry points: where the user enters the flow (which page or trigger). Screens: the pages or modals the user sees, named with concrete labels. Decision points: branches where the path differs based on user state or input. Error states: what happens when something goes wrong (validation, network failure, permission denied). Exit points: where the user lands when the flow completes successfully or abandons. The diagram is rendered as Mermaid (or equivalent text-based diagram) so it lives in the codebase and version-controls cleanly.

The discipline is to make the diagram navigable for two audiences: the implementer (who needs to know what to build at each step) and the reviewer (who needs to see whether the flow has gaps). A diagram that mixes screens with internal logic confuses both audiences; a diagram that names each screen by what the user sees and each decision by what the user does is readable by both.

How /draft-flow works

Step one: identify the JTBD

When invoked, /draft-flow asks for the user's job: what is the user trying to accomplish, what is the trigger, what does success look like. The JTBD framing produces a flow that follows the task; without it, the flow follows the team's feature decomposition, which often does not match how users move through the product.

Step two: map the happy path

The happy path is the linear sequence of screens and actions for the most common user state. The skill names each screen with the user-visible label ("Settings - Team" rather than "team-settings.tsx") and each action with the user-visible verb ("Click invite" rather than "POST /invites"). The map is a starting point; the next steps add the branches.

Step three: branches and error states

For each step in the happy path, the skill asks what could go differently. Decision points: did the user already do this, are they on the right plan, do they have the permissions. Error states: what does the user see when the form fails, when the network is down, when the action is rejected by the server. Each branch is added to the diagram with the condition labeled. Hidden states (states the user does not see directly but the system tracks) are surfaced if they affect the flow.

Step four: entry and exit

Entry points name where the user enters the flow: a navigation click, a notification, a deep link, a system trigger. Exit points name where they go on success and on abandon. The exit points matter because they connect this flow to the next one; a flow that ends without naming the exit point is invisible to the rest of the product.

Tonone's /draft-flow skill maps user flows as Mermaid diagrams with screens, decision points, error states, and explicit entry and exit points, grounded in the user's JTBD.

When to use /draft-flow, and when not to

/draft-flow is the right call when a feature needs a flow diagram before visual design or engineering starts, when a complex feature has unclear UX and the team needs to agree on the flow, or when documenting an existing flow for onboarding or a redesign.

Skip the skill for trivial single-screen interactions. For information architecture across the whole product, /draft-ia is the right call. For wireframes that show the screen-level layout, /draft-wireframe is calibrated to that work. For usability evaluation of an existing flow, /draft-review is the right call.

A worked example: invite-teammate flow

Suppose the brief is: design the flow for inviting a teammate. Run /draft-flow.

# Flow: Invite teammate
JTBD: A team owner wants to give a colleague access to the workspace
so they can collaborate on existing projects.

```mermaid
flowchart TD
  ENTRY([Team Settings page or '+' icon in nav])
  ENTRY --> S1[Invite Modal]
  S1 -->|Email + role| C1{Email valid?}
  C1 -->|No| E1[Inline error:<br/>'Enter a valid email']
  E1 --> S1
  C1 -->|Yes| C2{User exists in another team?}
  C2 -->|Yes| S2[Confirm cross-team invite]
  S2 -->|Cancel| EXIT_ABANDON([Back to Team Settings])
  S2 -->|Confirm| ACTION1[Send invite]
  C2 -->|No| ACTION1
  ACTION1 --> C3{Send succeeds?}
  C3 -->|Network fail| E2[Toast: retry option]
  E2 -->|Retry| ACTION1
  E2 -->|Dismiss| EXIT_ABANDON
  C3 -->|Server rejects<br/>seat limit| E3[Modal: upgrade plan?]
  E3 -->|Upgrade| FLOW_UPGRADE([Upgrade flow])
  E3 -->|Cancel| EXIT_ABANDON
  C3 -->|Success| S3[Confirmation:<br/>invite sent + copy link]
  S3 -->|Done| EXIT_SUCCESS([Team Settings, invitee shown 'pending'])
  S3 -->|Invite another| S1
```

## States the diagram covers
- Happy path: 3 screens (modal, confirm, success), 2 actions.
- Error: invalid email, network failure, seat limit.
- Decision: cross-team invite confirmation, plan upgrade.

## Hand-off notes
- Modal copy: see /pitch-copy output for invite flow.
- Cross-team confirmation language: legal-reviewed wording in /docs.
- Upgrade flow: separate flow, /flows/plan-upgrade.md.
- Server-side seat check happens before send; client only validates email format.

Three screens, three decisions, three error states, two exit paths. The Mermaid lives in the markdown file alongside the rest of the design documentation. Engineering reads it before implementation and knows what to build at each step; design reads it during review and can add states the diagram missed. The flow stays current because changing it is editing the markdown rather than redrawing in a separate tool.

Related skills

/draft-flow covers task-level flows. For the broader information architecture across the product, /draft-ia is the right call. For wireframes that show screen layout for each step in the flow, /draft-wireframe is calibrated to that work. For usability review of an existing flow, /draft-review is the right call.

Install

/draft-flow ships with the Draft agent in the Tonone for Claude Code package. Install Tonone, invoke /draft-flow from any Claude Code session, and the skill produces a Mermaid flow diagram grounded in the user's JTBD with explicit error states and exit points.

Flows that survive past the design review are the ones captured as artifacts. The skill is built so the artifact is cheap enough to produce per feature.