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.
- 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:
- Entry point
- First meaningful action
- Required decision
- Feedback after action
- Success state
- 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 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 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.
Step 4.5 - Match the product type
Use the product type to decide what "good UX" means:
| Product type |
Optimize for |
Avoid |
| SaaS dashboard |
fast scanning, saved filters, drilldowns, clear priority, visible operational thesis |
marketing-page spacing, decorative cards, hidden filters, generic CRM furniture |
| CRM/admin/internal tool |
repeat speed, bulk actions, auditability, permissions, domain-specific task language |
oversized empty space, playful copy, modal chains, interchangeable labels |
| Creative/editor tool |
canvas focus, tool discoverability, undo/redo, stable panels |
layout shifts, buried controls, destructive defaults |
| Marketplace/ecommerce |
trust, comparison, price/shipping clarity, recovery |
surprise costs, forced account creation, vague stock states |
| Onboarding/setup |
first value, motivation, resumability, skip paths |
long forms before value, fake progress, no return path |
| AI agent/tool run |
plan preview, progress, artifacts, retry, stop/resume |
invisible work, ambiguous completion, no trace of outputs |
If the request sounds like a real product people will use repeatedly, bias toward operational density and predictable navigation. If it is a one-off marketing page, bias toward clarity, brand memory, and conversion path.
Step 4.6 - Load a contextual pattern brief
If the product type clearly matches one of these contexts, read the matching brief before choosing the final UX pattern:
| Context |
Read |
| Agent/tool run, background automation, long-running export/import |
../../references/ux-patterns/ai-agent-run.md |
| SaaS dashboard, CRM, admin panel, internal tool, support queue |
../../references/ux-patterns/operational-dashboard.md |
| First-run setup, trial activation, import/setup flow |
../../references/ux-patterns/activation-onboarding.md |
| Checkout, paywall, pricing, upgrade, plan comparison |
../../references/ux-patterns/checkout-upgrade.md |
| Editor, builder, canvas, creative tool, IDE-like surface |
../../references/ux-patterns/editor-canvas.md |
Use a brief only when the context fits. If no brief fits, proceed from the product type table and the user's actual constraints.
The brief should influence the UX decision brief, especially:
- Pattern
- Primary and secondary actions
- Required states
- Recovery path
- Handoff constraints
Do not copy a referenced app or blindly apply a pattern because it is common. A shipped screen is evidence that a real product team used a decision, not proof that it is best for every product.
Step 5 - Choose the UX pattern
Pick one pattern and name it before visual design:
| Need |
Pattern |
| First run |
Guided setup with skip/resume |
| Complex creation |
Wizard with review step |
| Frequent operations |
Command surface + saved views |
| Data-heavy work |
Master/detail + filters + bulk actions |
| Monitoring |
Dashboard with priority stack and drilldown |
| Settings |
Searchable grouped settings + inline validation |
| Checkout/signup |
Short form + transparent cost/risk + recovery |
| Collaboration |
Activity timeline + comments + ownership |
| AI/tool execution |
Plan preview + progress + artifacts + retry |
| Public demo/proof project |
Product-specific job + proof surface + one non-happy state |
If two patterns fit, pick the one that reduces the riskiest failure mode. For example, choose a wizard over a single dense form when errors are costly, but choose command surface + saved views for repeated internal operations.
Step 6 - Hand off to UI
After the UX shape is clear, route to the platform skill:
- Web visuals:
../web-design/SKILL.md
- Windows visuals:
../windows-design/SKILL.md
- Apple visuals:
../apple-design/SKILL.md
- Android visuals:
../android-design/SKILL.md
- Cross-platform translation:
../cross-platform-design/SKILL.md
Pass the UX decisions into that skill as constraints. Do not let visual direction erase task flow, state coverage, or platform idioms.
When a contextual pattern brief was used, include its name in the handoff constraints so the platform skill knows which product behavior must survive visual design.
UX audit checklist
Before final delivery, check:
- Is the primary job obvious in the first screen?
- Can a new user reach first value without reading documentation?
- Can a returning user repeat the core task faster?
- Are empty, loading, error, permission, and success states defined?
- Is there one clear primary action per surface?
- Are risky actions confirmed, separated, or undoable?
- Do form errors appear near the fields they describe?
- Does the layout support scanning, not just looking good in a screenshot?
- Does navigation match the user's mental model?
- Is the next step clear after every action?
If any answer is no, fix the flow before polishing visuals.
Source: hashgraph-online/awesome-codex-plugins → plugins/f0d010c/stark/skills/ux-design/SKILL.md
1---2name: ux-design-23description: 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.4---5
6
7# ux-design - product flow before pixels
8
9Use 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.
10
11## What This Skill Can Do
12
13- Map core user journeys, task paths, branching flows, and recovery paths.
14- Define information architecture, navigation, labels, content groups, and page/screen inventory.
15- Design onboarding, activation, checkout, signup, forms, settings, dashboards, command palettes, and internal workflows.
16- Specify empty, loading, error, permission, success, stale, retry, resume, and audit states.
17- Audit an existing UI for usability, hierarchy, conversion, repeated-use friction, accessibility risks, and missing states.
18- Hand a compact UX decision brief to platform skills so visual design does not erase the product job.
19
20## Step 1 - Identify the job and user mode
21
22Before designing screens, state the smallest useful context:
23
24- Primary job: what the user is trying to finish.
25- User mode: first-time, returning, power user, admin, buyer, creator, operator, or support.
26- Frequency: one-time, occasional, daily, or high-volume repeated use.
27- Risk: low-risk browse, reversible edit, money/data/security impact, or destructive action.
28
29If 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.
30
31Do not interrogate the user with a product-strategy questionnaire before helping. The skill should make useful assumptions, name them briefly, and move.
32
33## Step 2 - Map the flow
34
35Write the minimum useful path:
36
371. Entry point
382. First meaningful action
393. Required decision
404. Feedback after action
415. Success state
426. Recovery path when something fails
43
44Prefer 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.
45
46## Step 2.5 - Produce the UX decision brief
47
48Before visual design or code, write a compact brief. Keep it short enough to pass into another skill:
49
50```md
51UX decision brief
52- Job: ...
53- User mode: ...
54- Frequency/risk: ...
55- Pattern: ...
56- Primary action: ...
57- Secondary actions: ...
58- Core path: entry -> action -> feedback -> success
59- Recovery path: ...
60- Required states: empty, loading, partial, error, permission, success, long-running
61- Handoff constraints: ...
62```
63
64This 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.
65
66## Step 3 - Design the states
67
68Every production UI needs these states:
69
70- Empty: what the user sees before data exists.
71- Loading: what changes while the system is working.
72- Partial: some data exists, some is missing.
73- Error: what failed, why it matters, and the next action.
74- Permission: what is blocked and how to request access.
75- Success: what happened and what the user can do next.
76- Long-running: progress, cancellation, retry, and resume behavior.
77
78Do not ship only the happy path.
79
80For 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.
81
82## Step 4 - Reduce cognitive load
83
84Apply these rules:
85
86- Put the next action where the user's eye already is.
87- Use one primary action per surface.
88- Group by task, not by database object.
89- Prefer progressive disclosure over dense first screens.
90- Keep labels concrete: "Invite teammate", not "Manage".
91- Make defaults safe and visible.
92- Keep destructive actions separated, confirmed, and undoable when possible.
93- Make repeated actions faster than first-time actions.
94
95For 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.
96
97## Step 4.5 - Match the product type
98
99Use the product type to decide what "good UX" means:
100
101| Product type | Optimize for | Avoid |
102|---|---|---|
103| SaaS dashboard | fast scanning, saved filters, drilldowns, clear priority, visible operational thesis | marketing-page spacing, decorative cards, hidden filters, generic CRM furniture |
104| CRM/admin/internal tool | repeat speed, bulk actions, auditability, permissions, domain-specific task language | oversized empty space, playful copy, modal chains, interchangeable labels |
105| Creative/editor tool | canvas focus, tool discoverability, undo/redo, stable panels | layout shifts, buried controls, destructive defaults |
106| Marketplace/ecommerce | trust, comparison, price/shipping clarity, recovery | surprise costs, forced account creation, vague stock states |
107| Onboarding/setup | first value, motivation, resumability, skip paths | long forms before value, fake progress, no return path |
108| AI agent/tool run | plan preview, progress, artifacts, retry, stop/resume | invisible work, ambiguous completion, no trace of outputs |
109
110If the request sounds like a real product people will use repeatedly, bias toward operational density and predictable navigation. If it is a one-off marketing page, bias toward clarity, brand memory, and conversion path.
111
112## Step 4.6 - Load a contextual pattern brief
113
114If the product type clearly matches one of these contexts, read the matching brief before choosing the final UX pattern:
115
116| Context | Read |
117|---|---|
118| Agent/tool run, background automation, long-running export/import | `../../references/ux-patterns/ai-agent-run.md` |
119| SaaS dashboard, CRM, admin panel, internal tool, support queue | `../../references/ux-patterns/operational-dashboard.md` |
120| First-run setup, trial activation, import/setup flow | `../../references/ux-patterns/activation-onboarding.md` |
121| Checkout, paywall, pricing, upgrade, plan comparison | `../../references/ux-patterns/checkout-upgrade.md` |
122| Editor, builder, canvas, creative tool, IDE-like surface | `../../references/ux-patterns/editor-canvas.md` |
123
124Use a brief only when the context fits. If no brief fits, proceed from the product type table and the user's actual constraints.
125
126The brief should influence the UX decision brief, especially:
127
128- Pattern
129- Primary and secondary actions
130- Required states
131- Recovery path
132- Handoff constraints
133
134Do not copy a referenced app or blindly apply a pattern because it is common. A shipped screen is evidence that a real product team used a decision, not proof that it is best for every product.
135
136## Step 5 - Choose the UX pattern
137
138Pick one pattern and name it before visual design:
139
140| Need | Pattern |
141|---|---|
142| First run | Guided setup with skip/resume |
143| Complex creation | Wizard with review step |
144| Frequent operations | Command surface + saved views |
145| Data-heavy work | Master/detail + filters + bulk actions |
146| Monitoring | Dashboard with priority stack and drilldown |
147| Settings | Searchable grouped settings + inline validation |
148| Checkout/signup | Short form + transparent cost/risk + recovery |
149| Collaboration | Activity timeline + comments + ownership |
150| AI/tool execution | Plan preview + progress + artifacts + retry |
151| Public demo/proof project | Product-specific job + proof surface + one non-happy state |
152
153If two patterns fit, pick the one that reduces the riskiest failure mode. For example, choose a wizard over a single dense form when errors are costly, but choose command surface + saved views for repeated internal operations.
154
155## Step 6 - Hand off to UI
156
157After the UX shape is clear, route to the platform skill:
158
159- Web visuals: `../web-design/SKILL.md`
160- Windows visuals: `../windows-design/SKILL.md`
161- Apple visuals: `../apple-design/SKILL.md`
162- Android visuals: `../android-design/SKILL.md`
163- Cross-platform translation: `../cross-platform-design/SKILL.md`
164
165Pass the UX decisions into that skill as constraints. Do not let visual direction erase task flow, state coverage, or platform idioms.
166
167When a contextual pattern brief was used, include its name in the handoff constraints so the platform skill knows which product behavior must survive visual design.
168
169## UX audit checklist
170
171Before final delivery, check:
172
1731. Is the primary job obvious in the first screen?
1742. Can a new user reach first value without reading documentation?
1753. Can a returning user repeat the core task faster?
1764. Are empty, loading, error, permission, and success states defined?
1775. Is there one clear primary action per surface?
1786. Are risky actions confirmed, separated, or undoable?
1797. Do form errors appear near the fields they describe?
1808. Does the layout support scanning, not just looking good in a screenshot?
1819. Does navigation match the user's mental model?
18210. Is the next step clear after every action?
183
184If any answer is no, fix the flow before polishing visuals.
185
186---
187
188**Source:** [`hashgraph-online/awesome-codex-plugins`](https://github.com/hashgraph-online/awesome-codex-plugins) → `plugins/f0d010c/stark/skills/ux-design/SKILL.md`
thedixitjain