ui-spec

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:

1. Default: The "Happy Path".
2. Loading: Bone skeletal screens or spinners.
3. Empty: Context-aware messages when no data exists.
4. Error: User-friendly error messages with recovery actions (Retry/Reset).
5. 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).

Output

Save UI spec to design/specs/ui-[feature-name].md:

\\\`markdown

UI Spec: [Feature Name]

Component Tree

[Hierarchical list of components]

State Matrix

| Component | Default | Loading | Empty | Error | Partial | |-----------|---------|---------|-------|-------|---------|

Interactions

[Component] -> [Trigger] -> [Response]

Responsive Behavior

[Breakpoint-specific layout changes]

Accessibility

[Keyboard nav, ARIA labels, contrast requirements]

Open Questions

[Items needing design decision] \\\`

Related Skills

• design-review — review implemented UI against spec
• frontend-design — aesthetic direction and design system
• design-system — reusable component library
• review-spec — general spec review workflow