releavo
Templates · UX spec template
Product brief templatePRD templateUX spec templateArchitecture doc templateEpic templateUser story templateReadiness check templateTest plan templateChange request templateRelease notes template
Template 3 of 10

UX spec template

The UX spec turns the PRD's requirements into flows and screens, including the states designs usually forget: empty, loading, partial and error. It's what the designer draws from and the developer builds against.

Signed off by:
The product owner or the designer
Comes after:
PRD
Leads to:
Architecture doc
ux-spec.md
# UX spec · <feature>

## Flow: <name>
Covers: FR-1, FR-2
1. Entry point
2. …
3. Done

## Screens
### <screen name>
**Purpose:**
**Content and controls** (in priority order):
**States:**
- Empty:
- Loading:
- Partial:
- Error: (each error case in the PRD)
- Success:

## Copy
Labels, messages and errors, in the product's voice.

## Accessibility
Keyboard path, focus order, labels for icon buttons, contrast.

## Frames needed
Screens still to be designed, by story key.

When to write it

After the PRD is approved, before stories are estimated. Stories estimated without a UX spec usually grow once someone notices the error states.

How to fill it in

  • One flow per job. Number the steps from the entry point to done, and list the FR IDs each flow covers. A requirement no flow covers is either missing from the design or doesn't belong in the PRD.
  • Every state of every screen. Empty, loading, partial, error and success. Most rework comes from the states nobody drew: what the screen looks like with no data, half the data, or a failure halfway through.
  • Real copy. Write the actual button labels and error messages, not "error message here". Copy is design; it changes layouts and it's what users read.
  • Accessibility. Say the keyboard path and focus order through the flow, which icon buttons need labels, and which elements depend on colour.
  • Frames needed. List what still has to be drawn, by story key, so nobody builds a screen that hasn't been designed.

Wireframes are fine

A table per screen listing its parts in order, a flow diagram, or a clickable prototype all count. The spec needs to be unambiguous, not pretty.

Common mistakes

  • Only the happy path.
  • Placeholder copy that ships.
  • Behaviour invented in the spec that the PRD never asked for. Raise it as a question instead.

Example

UX spec · Bulk orders

Flow: Upload an order sheet

Covers: FR-1, FR-2, FR-3

  1. Buyer opens the cart and chooses Upload a sheet.
  2. Picks a file; matching starts at once.
  3. Review screen shows matched rows and rows that need attention.
  4. Buyer fixes or drops each flagged row, then Add 212 lines to cart.

Screens

Review

Purpose: fix problem rows before anything reaches the cart. Content and controls: rows needing attention first, each with its suggestions; then matched rows, collapsed; the add button, disabled until no row needs attention. States:

  • Loading: "Matching 212 rows…" with a progress count.
  • Partial: "198 matched. 14 need you."
  • Error (FR-1): "That file is over 5 MB. Split it or remove empty sheets."
  • Success: returns to the cart with "212 lines added."

Accessibility

Each suggestion is a radio group; arrow keys move between them, Enter picks one.

Have Releavo write the ux spec

In Releavo this lives at docs/ux-spec.md. Releavo drafts it from the docs before it and your team's conversations; every edit is a draft until the product owner or the designer approves it, and approved versions are never overwritten.

Start a project, freeHow Releavo works