UX Design

ux-design - product flow before pixels

Use this skill when the product has to be understandable and usable, not just attractive. The output should make the user path clearer, reduce unnecessary decisions, and define states that survive real use.

What This Skill Can Do

• Map core user journeys, task paths, branching flows, and recovery paths.
• Define information architecture, navigation, labels, content groups, and page/screen inventory.
• Design onboarding, activation, checkout, signup, forms, settings, dashboards, command palettes, and internal workflows.
• Specify empty, loading, error, permission, success, stale, retry, resume, and audit states.
• Define task ergonomics: frequency, risk, cognitive load, control model, speed paths, error prevention, recovery, and evidence tasks.
• Choose usable workflow patterns: guided setup, wizard with review, command surface, priority queue, master/detail, monitoring board, workbench, settings, permission matrix, transparent checkout, task-led docs, agent progress, collaboration thread, and mobile priority stack.
• Evaluate polished UI with heuristic review, cognitive walkthrough prompts, severity ranking, evidence, first repair, and re-check.
• Validate usability with scenario tests for first-run, returning-user, error/recovery, keyboard-only, and mobile/touch paths.
• Audit an existing UI for usability, hierarchy, conversion, repeated-use friction, accessibility risks, and missing states.
• Hand a compact UX decision brief to platform skills so visual design does not erase the product job.

Step 1 - Identify the job and user mode

Before designing screens, state the smallest useful context:

• Primary job: what the user is trying to finish.
• User mode: first-time, returning, power user, admin, buyer, creator, operator, or support.
• Frequency: one-time, occasional, daily, or high-volume repeated use.
• Risk: low-risk browse, reversible edit, money/data/security impact, or destructive action.

If any of these are unclear and materially affect the flow, ask one short question. If the answer is easy to infer from the request, infer it and continue.

Do not interrogate the user with a product-strategy questionnaire before helping. The skill should make useful assumptions, name them briefly, and move.

Step 2 - Map the flow

Write the minimum useful path:

1. Entry point
2. First meaningful action
3. Required decision
4. Feedback after action
5. Success state
6. Recovery path when something fails

Prefer fewer screens when the user is trying to finish one job. Prefer separate steps when the user is making risky, costly, or hard-to-reverse decisions.

Step 2.5 - Produce the UX decision brief

Before visual design or code, write a compact brief. Keep it short enough to pass into another skill:

UX decision brief
- Job: ...
- User mode: ...
- Frequency/risk: ...
- Pattern: ...
- Primary action: ...
- Secondary actions: ...
- Core path: entry -> action -> feedback -> success
- Recovery path: ...
- Required states: empty, loading, partial, error, permission, success, long-running
- Handoff constraints: ...

This brief is the contract. The platform skill may change visual treatment, but it must not erase the chosen job, action hierarchy, state coverage, or recovery path.

Step 2.6 - Produce the task ergonomics contract

For serious product UI, repeated-use workflows, risky actions, forms, checkout, dashboards, editors, agent runs, admin tools, settings, or any request that says "usable", "ergonomic", "not only good looking", or "real product", read ../../references/ux-patterns/task-ergonomics.md.

Write the compact contract before visual design:

Task ergonomics contract
- Core task:
- User mode:
- Frequency/risk:
- Success metric:
- Cognitive load:
- Control model:
- Speed path:
- Error prevention:
- Recovery:
- State matrix:
- Evidence plan:

This is stricter than the UX decision brief. It protects the tenth use, the error path, and the risky action path.

For forms, settings, checkout, onboarding, signup, admin configuration, filters, generation prompts, or any user input that can fail, also read ../../references/ui-patterns/form-state-validation-system.md before visual design or implementation. Add the form job, risk, pattern, field anatomy, validation timing, state model, preservation/recovery, review/confirmation, schema/library ownership, accessibility, responsive behavior, and QA checks to the UX handoff.

For onboarding, activation, empty dashboards, no-results screens, setup/import flows, permission gates, trial starts, workspace creation, or first project creation, read ../../references/ux-patterns/first-run-empty-state-system.md before visual design. Define user promise, first value action, minimum/deferrable setup, sample/demo content, empty-state type, CTAs, permission timing, progress/resume model, recovery states, contextual teaching, success handoff, and QA evidence.

For navigation, information architecture, app shells, docs platforms, dashboards, admin/settings, workspaces, command palettes, breadcrumbs, tabs, or multi-route products, also read ../../references/ui-patterns/navigation-information-architecture.md before visual design or implementation. Add the primary objects, route map, navigation model, current-location model, search/command model, breadcrumb/tab behavior, deep-link/state model, route states, mobile replacement, focus/scroll restoration, and QA checks to the UX handoff.

Step 3 - Design the states

Every production UI needs these states:

• Empty: what the user sees before data exists.
• Loading: what changes while the system is working.
• Partial: some data exists, some is missing.
• Error: what failed, why it matters, and the next action.
• Permission: what is blocked and how to request access.
• Success: what happened and what the user can do next.
• Long-running: progress, cancellation, retry, and resume behavior.

Do not ship only the happy path.

For public demos and generated proof projects, include at least one non-happy state in the visible UI: an empty state, blocked permission, failed sync, queued job, retry panel, stale data banner, or partial result. This makes the output feel like a real product instead of a polished poster.

Step 3.5 - Choose the usability pattern

For serious product UI or any request that says "usable", "not only good looking", "real product", "ergonomic", "dashboard", "editor", "checkout", "agent run", "settings", "permissions", "docs", or "mobile task", read ../../references/ux-patterns/usability-pattern-matrix.md after task-ergonomics.md.

Write the compact pattern brief before visual design:

Usability pattern brief
- Product job:
- User mode:
- Frequency/risk:
- Pattern chosen:
- Why this pattern fits:
- Primary action:
- Secondary actions:
- Speed path:
- Error prevention:
- Recovery path:
- Required states:
- Keyboard/touch model:
- Rejected patterns:
- Evidence tasks:

The selected pattern should reduce the riskiest failure mode. Reject patterns that optimize the wrong use, such as a marketing hero for repeated operations, a wizard for high-volume triage, a grid of cards for comparison, or a dashboard for a single linear task.

Step 3.6 - Define usability scenario tests

For serious product UI, "not only good looking" work, UX audits, risky/repeated workflows, attractive-but-confusing UI, or final QA, read ../../references/ux-patterns/usability-heuristic-evaluation.md after the usability pattern matrix and before scenario testing. Rank findings with severity, name evidence, choose the first repair, and re-check the same task step.

Then read ../../references/ux-patterns/usability-scenario-testing.md after the heuristic evaluation.

Write the compact scenario test before final visual polish or delivery:

Usability scenario test
- Surface:
- User persona/mode:
- Core task:
- First-run scenario:
- Returning-user scenario:
- Error/recovery scenario:
- Keyboard-only scenario:
- Mobile/touch scenario:
- Success criteria:
- Friction budget:
- Evidence captured:
- Usability failures:
- Fix applied:
- Re-check:
- Remaining risk:

The scenario test is the proof layer. A screen is not "usable" just because the task ergonomics contract sounds good; the main task, recovery path, keyboard path, and mobile path need evidence or clearly named remaining risk.

Step 4 - Reduce cognitive load

Apply these rules:

• Put the next action where the user's eye already is.
• Use one primary action per surface.
• Group by task, not by database object.
• Prefer progressive disclosure over dense first screens.
• Keep labels concrete: "Invite teammate", not "Manage".
• Make defaults safe and visible.
• Keep destructive actions separated, confirmed, and undoable when possible.
• Make repeated actions faster than first-time actions.

For high-frequency tools, optimize scan speed, keyboard flow, saved filters, bulk actions, and stable layout. For consumer onboarding, optimize motivation, trust, and the shortest path to first value.