// Improve every piece of text in a UXSpec — descriptions, labels, error messages, empty states, and loading copy
| name | clarify |
| description | Improve every piece of text in a UXSpec — descriptions, labels, error messages, empty states, and loading copy |
Improve every piece of text in a UXSpec — $description fields, button labels, error messages, empty state copy, loading text. Words are design.
When reviewing a spec's text content. When $description fields are vague. When error states say "An error occurred." When empty states are blank.
These are the most-read part of a spec — they appear in PR reviews, agent prompts, and design handoffs. Write them like you're briefing someone who will build the UI without seeing a mockup.
Include: layout direction, spacing character, element hierarchy, color intent, emphasis, interactive affordances.
Explain what happened. Suggest a fix. Never blame.
These are opportunities, not dead ends. Describe what will appear. Explain the value. Offer a clear action.
Describe the action specifically. Active voice. Match the user's mental model.
Set expectations. Explain what's happening.
Confirm what happened. Guide to next steps.
State the specific action. Explain consequences.
Match the brand personality established in the gather phase:
Be consistent within a spec. If errors are friendly, success messages should be too.
Every string in a UXSpec is an interface with a human. Vague copy creates vague implementations. Specific, intentional text — even in $description fields that no end user sees — produces specific, intentional UIs.
Add purposeful motion to a UXSpec — $animations, onEnter choreography, and timing tokens
Identify repeated patterns and consolidate them into $elements and shared tokens for systematic reuse
Collect design context, audience, intent, and requirements before writing any UXSpec JSON
Strengthen a UXSpec against real-world conditions — overflow, missing data, network failures, and accessibility
Run a systematic quality audit on a completed UXSpec — design intent, consistency, accessibility, and state coverage
Walk through building a UXSpec (.uxspec.json) file — gathering requirements, making design decisions about layout/typography/color/motion/accessibility, designing the state machine, defining visuals, then compiling and verifying the output.