Skip to content
Skills Library
Design & UX · Conversion & formats

user-flow-maps

/user-flow-maps

Use when a user flow, journey, or screen-to-screen behaviour needs to become a visual flow map — "draw the flow", "make a flow map", "user flow diagram", "map the screens", "turn these journeys into diagrams", or when acceptance criteria need a picture reviewers can sign off on. Renders a spec of screens, decisions and transitions into standalone HTML posters — numbered screen wireframes, decision diamonds, Start/End markers naming where a flow hands off, orthogonal connectors routed from the data, and an authoritative edge table. Layout, routing and label collision are handled by the bundled

Repository
sdlc-skills ↗
Licence
MIT
Last repository change
26.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
6
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/build-flowmaps.mjs, scripts/flowmap.js

What it does and when to use it

Use when a user flow, journey, or screen-to-screen behaviour needs to become a visual flow map — "draw the flow", "make a flow map", "user flow diagram", "map the screens", "turn these journeys into diagrams", or when acceptance criteria need a picture reviewers can sign off on. Renders a spec of screens, decisions and transitions into standalone HTML posters — numbered screen wireframes, decision diamonds, Start/End markers naming where a flow hands off, orthogonal connectors routed from the data, and an authoritative edge table. Layout, routing and label collision are handled by the bundled

Triggers from the description

draw the flowmake a flow mapuser flow diagrammap the screensturn these journeys into diagrams
Original author description

Use when a user flow, journey, or screen-to-screen behaviour needs to become a visual flow map — "draw the flow", "make a flow map", "user flow diagram", "map the screens", "turn these journeys into diagrams", or when acceptance criteria need a picture reviewers can sign off on. Renders a spec of screens, decisions and transitions into standalone HTML posters — numbered screen wireframes, decision diamonds, Start/End markers naming where a flow hands off, orthogonal connectors routed from the data, and an authoritative edge table. Layout, routing and label collision are handled by the bundled

How it works

  1. The one rule
  2. Workflow
  3. How ids drive layout
  4. What lands on the poster
  5. Conventions worth keeping
  6. Styling
  7. Files
Original SKILL.md headings · 90 lines, 704 words
SKILL.md preview
---
name: user-flow-maps
description: Use when a user flow, journey, or screen-to-screen behaviour needs to become a visual flow map — "draw the flow", "make a flow map", "user flow diagram", "map the screens", "turn these journeys into diagrams", or when acceptance criteria need a picture reviewers can sign off on. Renders a spec of screens, decisions and transitions into standalone HTML posters — numbered screen wireframes, decision diamonds, Start/End markers naming where a flow hands off, orthogonal connectors routed from the data, and an authoritative edge table. Layout, routing and label collision are handled by the bundled flowmap.js; you supply data, never coordinates. NOT for architecture or sequence diagrams, NOT for visual/UI design of the screens themselves (that is a design role's job), and NOT a mermaid replacement — the source diagram stays canonical.
---

# User-flow maps

Turn a flow — screens, decisions, branches, failure paths — into a reviewable
HTML poster. The output is one self-contained file per flow plus an index that
links them; it opens straight from disk, no server and no network.

## The one rule

**You supply data. The library supplies every coordinate.**

Hand-positioning a flow map is a trap: it looks fine until an edge is added,
then captions collide, arrows point into empty space, and each fix creates the
next one. `scripts/flowmap.js` owns layout, lane packing, orthogonal routing,
anchor selection and label de-collision. Never write pixel maths in a spec.

## Workflow

1. **Write a spec.** One JSON file describing the whole set. See
   `references/spec-schema.md` for the contract and a worked example.
2. **Build.**
   ```bash
   node scripts/build-flowmaps.mjs <spec.json> --out <dir>
   ```
3. **Verify before you claim it works.** Open the pages and check them — the
   library is deterministic but a spec can still describe a flow badly (a
   dangling target, a decision with no outcomes). `references/verifying.md`
   has a copy-paste browser audit that reports edge/caption collisions,
   overlapping labels and orphan nodes. Run it. A flow map that *looks* drawn
   but routes an arrow through a screen is worse than no diagram.

## How ids drive layout

Node ids are the layout instruction — there is no other positioning input:

- **Whole numbers** (`0`, `1`, `2`) form the main row, left to right in order.
- **Decimals** (`1.1`, `2.1`) are branches off the step they hang from, drawn
  on the row above, in their own column.
- Number them so reading the ids in order tells the story.

Everything else — which edge gets which lane, which side a connector enters,
where a label sits so it clears the artwork — is computed.

## What lands on the poster

- **Screen nodes** render as a wireframe skeleton chosen by `archetype`
  (`list`, `detail`, `form`, `dialog`, `confirmation`, `empty-state`,
  `error-state`, `loading-state`, `notice`, `split`, `handoff`). The
  `regions` array says what information is on the screen; it drives the
  skeleton, and it is *structural* — never visual design.
- **Decisions** render as diamonds, with the question inside and outcome
  labels on the edges.
- **Start** marks where the flow is entered.
- **End** marks every exit, and names where it leads. Give a node a `handoff`
  archetype, or point a transition at a target outside the flow, and it
  becomes an End marker resolved through the flow's `outs` / `names` maps.
- **The edge table** repeats every transition exactly. It is generated from
  the same data as the drawing, so the two cannot disagree — say so in review,
  because a poster always simplifies and the table is the authority.

## Conventions worth keeping

- **Behaviour, not design.** A flow map states what must happen and when.
  Layout, components and styling belong to whoever owns the design system.
  Keep that line; it is what makes the map reviewable by non-designers.
- **Tag every edge with the criterion it satisfies** (`ac`). That back-
  reference is what turns a picture into an acceptance artifact. The renderer
  chips real ids and keeps any trailing prose as a note.
- **Record what you could not draw.** If an acceptance criterion has no node —
  a metric, a cross-cutting copy rule, an option with no destination — that is
  a finding about the criterion. Put it in `findings`, don't invent a node.
- **Mark superseded paths rather than deleting them.** `[N/A UNDER <decision>]`
  in a label keeps the reasoning visible when scope changes.

## Styling

The look is Material Design 3 adapted for legibility: M3 colour roles, type
scale, shape and elevation, with full light/dark token sets. Override by
redefining the custom properties in `FlowMap.css` — every colour resolves
through a token, so a palette swap is a token edit, not a rewrite.

## Files

| Path | What it is |
|---|---|
| `scripts/flowmap.js` | The renderer. Browser (`window.FlowMap`) and Node (`require`). Inlined into every generated page, so output stays self-contained. |
| `scripts/build-flowmaps.mjs` | CLI: spec → a set of linked HTML pages. |
| `references/spec-schema.md` | The spec contract, field by field, with an example. |
| `references/verifying.md` | The audit to run before calling a map done. |
Files in this package (6)
  • SKILL.md 5 KB
  • references/example-hotelbooking.flowspec.json 53 KB
  • references/spec-schema.md 5 KB
  • references/verifying.md 6 KB
  • scripts/build-flowmaps.mjs 12 KB
  • scripts/flowmap.js 36 KB

Versions

RepositoryScoreLicence
This page · arozumenko/sdlc-skills100MIT
arozumenko/sdlc-skills100MIT

Database snapshot: 13.11.2026 · package version bb454b27c9d4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100screen-specs
    Use when screens need designing or documenting as reference a developer or agent can build from — "design the screens", "screen specs", "what should this screen look like", "turn the flows into designs", "document the UI", or when a flow map's nodes need to become actual…
  • 90journey-map
    Document a user journey from screen references and a user story: outcome, screen flow, components consumed, critical states, accessibility, security, performance. Use when mapping a user flow across screens. Do not use for a single screen (use screen-spec) or a reusable pattern (use pattern-doc).
  • 100screen-flow
    Map an app's navigation as a screen flow built from real screenshots, delivered as one standalone HTML file with an infinite, zoomable canvas. Screens are placed as cards with arrows between them, the main navigation is grouped together, and each feature's screens get their own…
  • 90map-user-flow
    Map an in-product flow across screens, decisions, transitions, native platform surfaces, and recovery states. Use for a feature or user journey that spans multiple screens or states, before visual UI design or technical architecture.
  • 90user-flow-diagram
    Diagram screen-level paths, decision points, and branch logic. Use when specifying how a feature is traversed. For the emotional end-to-end arc, use `journey-map` (design-research).
  • 100user-flow
    Use when the user wants user journeys mapped through a feature or product: user flow, user journey, flow diagram, decision points, friction, error states, or edge cases.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.