| name | ux-spec |
| description | Create a UX specification through six designer-mindset passes (mental model, IA, affordances, cognitive load, states, flow). |
| disable-model-invocation | true |
Skill: UX Specification
Adapted from PRD-to-UX translation skill
Overview
Translate product requirements into UX foundations through 6 forced designer-mindset passes. Each pass asks different questions that visual-first approaches skip.
Core principle: UX foundations come BEFORE visual specifications. Mental models, information architecture, and cognitive load analysis prevent "pretty but unusable" designs.
When to Use
- After
/prd or brainstorming, when the feature has a user interface
- Before creating visual designs, wireframes, or component specs
- When preparing design handoff for mockup tools (Figma, Stitch, etc.)
- Before planning phases for UI-heavy features
Not for: Backend-only work, API design, features with no user-facing interface.
The Iron Law
NO VISUAL SPECS UNTIL ALL 6 PASSES COMPLETE
- Don't mention colors, typography, or spacing until Pass 6 is done
- Don't describe screen layouts until information architecture is explicit
- Don't design components until affordances are mapped
Skipping passes to "save time" produces specs that need redesign. The 6 passes ARE the shortcut.
The 6 Passes
Execute IN ORDER. Each pass produces required outputs before the next begins.
Pass 1: User Intent & Mental Model
Ask: "What does the user think is happening?"
Force these questions:
- What does the user believe this system does?
- What are they trying to accomplish in one sentence?
- What wrong mental models are likely?
Output:
## Pass 1: Mental Model
**Primary user intent:** [One sentence]
**Likely misconceptions:**
- [Misconception 1]
- [Misconception 2]
**UX principle to reinforce/correct:** [Specific principle]
Pass 2: Information Architecture
Ask: "What exists, and how is it organized?"
Force these actions:
- Enumerate ALL concepts the user will encounter
- Group into logical buckets
- Classify each as: Primary / Secondary / Hidden (progressive disclosure)
Output:
## Pass 2: Information Architecture
**All user-visible concepts:**
- [Concept 1]
- [Concept 2]
**Grouped structure:**
### [Group Name]
- [Concept]: [Primary/Secondary/Hidden]
- Rationale: [Why this grouping]
This is where most AI UX attempts fail. If you skip explicit IA, visual specs will be disorganized.
Pass 3: Affordances & Action Clarity
Ask: "What actions are obvious without explanation?"
Force explicit decisions:
- What is clickable?
- What looks editable?
- What looks like output (read-only)?
- What looks final vs in-progress?
Output:
## Pass 3: Affordances
| Action | Visual/Interaction Signal |
|--------|---------------------------|
| [Action] | [What makes it obvious] |
**Affordance rules:**
- If user sees X, they should assume Y
Pass 4: Cognitive Load & Decision Minimization
Ask: "Where will the user hesitate?"
Force identification of:
- Moments of choice (decisions required)
- Moments of uncertainty (unclear what to do)
- Moments of waiting (system processing)
Then apply: collapse decisions, delay complexity (progressive disclosure), introduce defaults.
Output:
## Pass 4: Cognitive Load
**Friction points:**
| Moment | Type | Simplification |
|--------|------|----------------|
| [Where] | Choice/Uncertainty/Waiting | [How to reduce] |
**Defaults introduced:**
- [Default 1]: [Rationale]
Pass 5: State Design & Feedback
Ask: "How does the system talk back?"
Force enumeration of states for EACH major element:
- Empty, Loading, Success, Partial (incomplete data), Error
For each state: What does the user see? Understand? Can do next?
Output:
## Pass 5: State Design
### [Element/Screen]
| State | User Sees | User Understands | User Can Do |
|-------|-----------|------------------|-------------|
| Empty | | | |
| Loading | | | |
| Success | | | |
| Partial | | | |
| Error | | | |
This prevents "dead UX" — screens with no feedback.
Pass 6: Flow Integrity Check
Ask: "Does this feel inevitable?"
Final sanity check:
- Where could users get lost?
- Where would a first-time user fail?
- What must be visible vs can be implied?
Output:
## Pass 6: Flow Integrity
**Flow risks:**
| Risk | Where | Mitigation |
|------|-------|------------|
| [Risk] | [Location] | [Guardrail/Nudge] |
**Visibility decisions:**
- Must be visible: [List]
- Can be implied: [List]
**UX constraints:** [Hard rules for the visual phase]
THEN: Visual Specifications
Only after all 6 passes are complete, create:
- Screen layouts
- Component specifications
- Design system (colors, typography, spacing)
- Interaction specifications
- Responsive breakpoints
The 6 passes inform every visual decision.
Output
Write the UX specification to docs/plans/{topic}-ux-spec.md.
After the UX Spec
"UX spec is saved. Next steps:
- Start a new session with the planner agent to break this into implementation phases.
- Optionally, run
/ux-to-prompts to generate build-order prompts for external UI tools (v0, Bolt, etc.)."
Red Flags — Stop and Restart
| Violation | What You're Skipping |
|---|
| Describing colors/fonts | All foundational passes |
| "The main screen shows..." | Pass 1-2 (mental model, IA) |
| Designing components before actions mapped | Pass 3 (affordances) |
| No friction point analysis | Pass 4 (cognitive load) |
| States only in component specs | Pass 5 (holistic state design) |
| No "where could they fail?" | Pass 6 (flow integrity) |
Common Mistakes
Merging passes: "I'll cover mental model while doing IA" — You won't. Separate passes force separate thinking.
Skipping to visuals: "The PRD is clear, I can design screens" — Agents skip 4+ passes when allowed. Don't.
Implicit affordances: "Buttons are obviously clickable" — Map EVERY action explicitly. What's obvious to you isn't obvious to users.
Scattered state design: "I'll add states to each component" — Holistic state table in Pass 5 catches gaps that per-component approaches miss.
