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
- Author
- arozumenko ↗
- Repository
- sdlc-skills ↗
- Licence
- MIT
- Last repository change
- 26.10.2026
Assessment and security
- Files in this package
- 6
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 26.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 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
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
- The one rule
- Workflow
- How ids drive layout
- What lands on the poster
- Conventions worth keeping
- Styling
- Files
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
| Repository | Score | Licence |
|---|---|---|
| This page · arozumenko/sdlc-skills | 100 | MIT |
| arozumenko/sdlc-skills | 100 | MIT |
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.