/ux-design

name: ux-design
description: Use when the user asks for UX, product flow, user journey, wireframes, usability, conversion, onboarding, checkout, signup, navigation, forms, state design, dashboard workflows, command palettes, settings, permissions, long-running task progress, admin/internal tools, activation, retention, or making an app easier to use over time. Designs and audits user experience flows, information architecture, content hierarchy, forms, onboarding, dashboards, settings, empty/loading/error/permission/success states, recovery paths, and repeated-use product ergonomics before visual polish. Pair with platform UI skills after the UX flow is clear.

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 mode