# UX Flows > Use to derive the user flows of a UI-touching feature after the spec is clarified — one mermaid flowchart per UI-touching §4 user story (happy + alt/error branches from §5 ACs), a screen inventory (SCR-NN ids), and an AC→flow map, written to docs/features/{slug}/ux-flows.md. Triggers on "ux flows for {slug}", "user flows for {slug}", "screen flow for {slug}", "/sdd:ux-flows {slug}", "юзер-флоу для {slug}", "потік екранів {slug}", "намалюй флоу користувача". Always markdown + mermaid regardless of the design tool; the Socratic pass confirms each flow in prose, never raw mermaid. Feeds design (target-surface evidence), sequences (SCR alignment), screens (the inventory) and plan-tests (e2e-through-UI paths). Hard-refuse if spec.md is missing; skipped for features with no human-facing UI. - Skill: `genkovich/ux-flows` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add genkovich/ux-flows` - Raw SKILL.md: https://api.skillmd.com/api/skills/genkovich/ux-flows/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: genkovich (https://skillmd.com/u/genkovich) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/genkovich/ux-flows --- # Skill: ux-flows Draws **how the user moves** through a UI-touching feature — after `clarify`, before `design`. For each UI-touching §4 user story it produces a mermaid `flowchart` (happy path + the alt/error branches the §5 ACs demand), builds the **screen inventory** (`SCR-NN` — the id contract `screens` details later), and maps every UI-touching AC to the flow/branch that shows it. The artifact is **always markdown + mermaid** whatever `docs/design-system.md` picks as the drawing tool — flows are flow-altitude, not visual design. `design` then reads it as **evidence** for the target-surface + UI-architecture decisions (the formal `target_surfaces` declaration stays `design`'s); `sequences` aligns UI-driven flows on the SCR ids; `plan-tests` takes the e2e-through-UI paths from here. **This stage is optional by surface, not by size:** its N/A condition (no human-facing UI) lives in [`../_shared/size-matrix.md`](../_shared/size-matrix.md) and is evaluated by `clarify`'s handoff (`specify`'s when clarify was legally skipped). Invoked directly, it always runs. Question phrasing → [`../_shared/ask-style.md`](../_shared/ask-style.md); each diagram is confirmed **in prose, never as raw mermaid** → [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md). Flow labels + prose follow `artifact_language` — mermaid keywords, SCR ids and AC ids stay English → [`../_shared/artifact-language.md`](../_shared/artifact-language.md). ## Owner PM + designer (or whoever owns the user experience). The PM confirms each flow matches a real user story; the Tech Lead flags flows that imply architecture (they become `design` input, not decisions here). ## Inputs - `` — feature slug. - **Gate (hard-refuse if missing):** `docs/features//spec.md` — the flows derive from §4 user stories + §5 ACs. Absent → STOP: «run `specify ` first — ux-flows derives from its user stories». - (Expected) `docs/design-system.md` — the platform posture (the default platform assumption) + the tool. **Absent → not a block**: work in `code`-mode assumptions, recommend `/sdd:design-system` in the handoff. - (Optional) `CONTEXT.md` (both levels, per-feature wins) — canonical roles for the actors. - (Optional) `docs/features//.size` / `.route` — depth + handoff resolution; absent → default M / standard and say so in the handoff. ## Protocol 1. **Gate + read.** `test -f docs/features//spec.md` → missing = refuse with the pointer above. Read spec §1 (context), §4 (user stories — which touch a UI?), §5 (ACs), `CONTEXT.md` glossary, and `docs/design-system.md` (posture + tool; note its absence for the handoff). 2. **Set the depth dial + platform.** Read `interview_depth` from `.claude/sdd.local.md` (else medium); unless `--depth=` was passed, ask ONE depth-selection `AskUserQuestion` per [`../_shared/ask-style.md`](../_shared/ask-style.md), then confirm the **platform posture** in the same call (second question): the design-system posture as «(Recommended)», deviation allowed + recorded with its why. Depth governs the per-flow question volume (→ [`../_shared/interview-depth.md`](../_shared/interview-depth.md)); coverage never shrinks. 3. **Derive flows + inventory.** For every **UI-touching** §4 user story: one flow — happy path + an alt/error branch per relevant §5 AC. Collect every screen the flows visit into the **Screen inventory** (`SCR-NN` + purpose/entry/exit); flow nodes reference the SCR ids. A backend-only user story is listed as out of scope, not drawn. 4. **Socratic pass — prose, never raw mermaid.** Per [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md): write each flow into `docs/features//ux-flows.md` (from [`./templates/ux-flows.md`](./templates/ux-flows.md)), validate it parses per [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md), then describe it in plain words (every branch) and confirm — at medium/hard one `AskUserQuestion` per flow (Accept / Fix / Save-as-OQ / Drop); at **easy**, write + one-line summary into the assumptions ledger and proceed. 5. **Fill the AC map + write + commit.** Complete the AC-coverage table (every UI-touching §5 AC → flow/node/branch, or an explicit `N/A: `), re-validate every mermaid block, stamp `updated_at`, propose commit `ux-flows: `. 6. **Structural self-check** — per [`../_shared/self-check.md`](../_shared/self-check.md): re-read the file from disk and verify **4 items**: (1) every UI-touching §4 user story has a flow; (2) every flow node's SCR id exists in the inventory (and every inventory row appears in ≥1 flow); (3) every UI-touching §5 AC appears in the coverage table with a flow/branch or an explicit N/A; (4) every mermaid block parses. Fix + re-check ≤2 cycles; surface anything unresolved. 7. **Handoff.** Emit the **stage-handoff block** per [`../_shared/handoff.md`](../_shared/handoff.md) — *What I did* (incl. «self-check: 4/4 pass»; + «`docs/design-system.md` absent — run `/sdd:design-system`» when it was) + *Review* (`docs/features//ux-flows.md`) + *Run next*: `/clear`, then `/sdd:design ` (it reads these flows as target-surface evidence). ## Definition of Done - `docs/features//ux-flows.md` exists: platform decisions, the SCR-NN inventory, one flow per UI-touching §4 user story (happy + AC-demanded branches), the AC-coverage table — zero silently uncovered UI ACs. - Every flow was confirmed in prose (or written + ledgered at easy); every mermaid block parses. - No visual design leaked in: no component names, no layout, no styling — flow altitude only (screens is where states + components live). ## Anti-patterns - **Drawing screens here.** Components, states, layout belong to `screens`; this artifact is the movement between screens, not their content. - **Deciding architecture here.** «SPA vs SSR», «this needs a websocket» — flag it as design input; `design` decides and declares `target_surfaces`. - **Raw mermaid as the confirmation prompt** — the anti-pattern [`diagram-presentation.md`](../_shared/diagram-presentation.md) exists to kill. - **Skipping backend-only stories silently.** List them as out of scope with one line — the reader must see they were considered. - **Blocking on a missing design-system.** Its absence degrades (code-mode assumptions + a handoff recommendation), never blocks the flow work. ## References & template - [`./templates/ux-flows.md`](./templates/ux-flows.md) — output scaffold; inline comments are the generation contract. - [`../_shared/diagram-presentation.md`](../_shared/diagram-presentation.md) · [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md) — confirm-in-prose + parse-validation. - [`../_shared/size-matrix.md`](../_shared/size-matrix.md) — the N/A condition (no human-facing UI) evaluated by the upstream handoff. - [`../_shared/interview-depth.md`](../_shared/interview-depth.md) — the depth dial set in step 2.