| name | ui-spec |
| description | Guidelines and procedures for creating comprehensive UI Specifications from PRDs and prototypes. |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write |
| effort | 3 |
| argument-hint | [prd, prototype, or feature name] |
Skill: /ui-spec
Use this skill when moving from a PRD (Requirements) to a technical UI design. This skill bridges the gap between wireframes and code.
The UI Spec Lifecycle
1. Analysis Phase
- Map ACs: Map every Acceptance Criterion from the PRD to a UI screen or interaction.
- Prototype Ingestion: If prototype code exists (e.g., from
prototyper), read it to understand components and states.
2. Decomposition Phase
- Define the Component Tree.
- Identify which components can be reused from the existing codebase vs. which need to be new.
3. Specification Phase
Fill out the ui-spec-template including:
- State Matrix: Explicitly define what the user sees during
Loading, Error, and Empty states.
- Interactions: Use EARS format (Condition-Trigger-Response) for all interactive elements.
4. Integration Phase
- Link the UI Spec in the feature's [Design Doc].
- Use the UI Spec as the checklist for the
frontend-developer.
The State x Display Matrix
Every component MUST define behavior for these 5 states:
- Default: The "Happy Path".
- Loading: Bone skeletal screens or spinners.
- Empty: Context-aware messages when no data exists.
- Error: User-friendly error messages with recovery actions (Retry/Reset).
- Partial: Behavior when some data is missing or loading.
Accessibility (A11y) Rules
- Every interaction must have a keyboard equivalent.
- Every interactive element must have an ARIA role and label.
- Color contrast ratios must meet WCAG 2.1 Level AA (4.5:1 for normal text).
