# UX Spec

> Create a UX specification through six designer-mindset passes (mental model, IA, affordances, cognitive load, states, flow).

- Skill: `theyoungastronauts/ux-spec` (Agent Skill)
- Install (CLI): `npx skillmds@latest add theyoungastronauts/ux-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/theyoungastronauts/ux-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: theyoungastronauts (https://skillmd.com/u/theyoungastronauts)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/theyoungastronauts/ux-spec

---


# 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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:**
```markdown
## 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.