ux-spec

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:

1. Enumerate ALL concepts the user will encounter
2. Group into logical buckets
3. 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.