clarify

name	clarify
description	Improve every piece of text in a UXSpec — descriptions, labels, error messages, empty states, and loading copy

Clarify: Copy and Descriptions

Improve every piece of text in a UXSpec — $description fields, button labels, error messages, empty state copy, loading text. Words are design.

When to Use

When reviewing a spec's text content. When $description fields are vague. When error states say "An error occurred." When empty states are blank.

$description Fields

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.

• "Error state" → "A red-tinted banner appears above the form with an alert icon and the specific error message. The form remains editable. The submit button shows 'Try again' in its default style."
• "Loading" → "The submit button is replaced by a centered spinner with 'Signing in...' text. All form fields are visible but disabled. The form maintains its layout to prevent content shift."

Content Types

Error Messages

Explain what happened. Suggest a fix. Never blame.

• Bad: "Error 403: Forbidden"
• Good: "You don't have access to this resource. Contact your admin to request permission."
• Bad: "Invalid input"
• Good: "Email must include an @ symbol (e.g., [e-mail])"

Empty States

These are opportunities, not dead ends. Describe what will appear. Explain the value. Offer a clear action.

• Bad: "No items"
• Good: "No projects yet. Create your first project to start tracking tasks."

Button Labels

Describe the action specifically. Active voice. Match the user's mental model.

• Bad: "Submit", "Click here", "OK"
• Good: "Create account", "Save changes", "Send invitation"

Loading States

Set expectations. Explain what's happening.

• Bad: "Loading..."
• Good: "Checking your credentials..." or "Fetching latest data..."

Success States

Confirm what happened. Guide to next steps.

• Bad: "Success!"
• Good: "Account created. Check your email to verify your address."

Confirmation Dialogs

State the specific action. Explain consequences.

• Bad: "Are you sure?"
• Good: "Delete 'Project Alpha'? This removes all tasks and cannot be undone."

Copy Tone

Match the brand personality established in the gather phase:

• Professional: "We couldn't process your request. Please try again."
• Friendly: "Something went sideways — let's try that again."
• Technical: "Request failed (timeout after 30s). Retry or check network status."

Be consistent within a spec. If errors are friendly, success messages should be too.

Anti-patterns

• Jargon without explanation ("CSRF token expired")
• Passive voice in actions ("The form will be submitted" → "Submit the form")
• Blame language ("You entered an invalid email" → "Please enter a valid email address")
• Generic text that could apply to any app ("Welcome!" → "Welcome to [product]. Here's how to get started.")
• Inconsistent terminology (using "delete", "remove", and "trash" for the same action)

Principle

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.