ux-flows

ux-flows — Design HOW Users Move

Part of super-ux — see system-map.md for the whole pipeline and the four sync rules. After changes, run the linter (python3 docs/ux/lint.py).

Turns user stories into user flows AND maintains the UI map: task analysis → flow diagram (mermaid) → the screen registry screens.md (every screen and state with Figma frame, wireframe, coverage, resources) → optional wireframes/Figma mockups. Also the home of UX improvement: heuristic evaluation of existing flows and traced redesign proposals.

Two files owned: flows.md (flows referencing screens by SCR-ID) and screens.md (the canonical per-screen spec — the design map that ties UX, UI, Figma, and code together). A screen used by several flows is described once in screens.md.

Contracts: scenario-format.md (ux-contract v4, flows.md section) and ux-design-principles.md — read the principles doc before designing; it is the thinking playbook (task-analysis method, flow rules, PRN-01..24 heuristics, improvement procedure). Proven tactics: best-practices.md by stage tags. The catalog holds tactics; two files hold the order they go in. onboarding.md (ON-01..ON-18) assembles the path to the first value, and it rests on that value being defined first. internal-screens.md (IS-01..IS-18) covers everything after it: the screens someone uses because they already decided, where the four states are one design and a list is a working surface rather than a directory. Visual identity (which style pack the frames and the built UI obey, via the sheleg-design companion): visual-identity.md.

Real flows off the shelf, before you invent one: if the session exposes a reference server — Refero (mcp__refero__*), Mobbin (mcp__mobbin__*) or Lazyweb (mcp__lazyweb__*) — sweep it during step 2. Two of them return connected multi-step flows and they answer in different media: Refero gives each step as structure — a goal, an action, a system response — which is the shape this skill draws; Mobbin gives each step as a preview image, which is how you judge whether it actually reads. Read Refero to draw the diagram, look at Mobbin to check it. Gate on the tools present in the session, not on the config — a registered server nobody signed in to exposes nothing. None present → offer the one-time install once and continue either way; the flow is designed from the stories regardless.

A paid-acquisition funnel has a second shelf, and it is public: the competitor funnels running right now behind the ads in your category. funnel-research.md is the method for reading them — FR-01 where they are visible, FR-02 the four signals that survive when revenue is not, FR-03 the fields that make a corpus comparable, FR-06 the stop before copying. Its last section names the step chain the corpus keeps producing (ad → landing → quiz → loading → offer → paywall → checkout → success) and the practice that specifies each step, which is the diagram this skill draws. Every step there is a screen in screens.md and a scenario in scenarios.md, the loading screen and the missing-answer branch included — those two are the ones that get built and never recorded.

Position in the chain: foundation (WHY) → flows (HOW) + screens (UI map) → scenarios (WHAT). Stories in, flows and screens out; ux-scenarios then covers every node and edge with scenarios. If foundation is missing on a non-trivial product, recommend ux-foundation first. The chain's opt-out is spoken: "no scenarios" / «без сценариев» from the operator declines it — design without the chain and say so.

Money moments are first-class flows: when the foundation declares a Monetization section, design dedicated flows for each money moment — paywall (first-session placement, BP-069), upgrade-at-limit (the gated action's limit branch is a flow edge to the offer, BP-074), trial start/end, cancel + winback (BP-123), rating prompt after success moments (BP-076). When the foundation's purchase surface is web checkout or web2app, the web funnel (landing → pricing → signup → checkout, BP-116..121), recurring billing (dunning, BP-122) and the paid handoff (install → identify → entitlement restore, with every failure branch, BP-124..126) are flows of this product as well. Each money flow uses its checklist row from practice-selection.md step 3.