| name | impeccable-clarify |
| description | Improve UX copy, labels, error messages, and microcopy in a user interface. Use when interface text is unclear, ambiguous, jargon-heavy, or inconsistent — rewrite it so users understand what happened, what matters, and what to do next. |
| license | Apache-2.0 |
Rewrite unclear interface text so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice.
Audit the language
Read the entire interaction path, not isolated strings. Identify:
- ambiguous nouns, verbs, and actions;
- internal jargon or assumed knowledge;
- vague labels, outcomes, and system states;
- missing consequences, recovery, or timing;
- inconsistent terminology and capitalization;
- redundant headings, intros, helper text, and confirmations;
- text that breaks at realistic widths or in translation;
- tone that ignores stress, risk, success, or urgency.
Infer audience and task from product context and surrounding UI. Ask before changing factual claims, legal meaning, or a term that may be domain-specific.
Set the message hierarchy
For each state, decide:
- the one fact the user needs now;
- the action available next;
- supporting context that changes the decision;
- the appropriate tone for this moment.
Say each idea once. If the heading already explains the state, the introduction should add new information or disappear.
Rewrite by function
Actions and navigation
Use a specific verb and object when the outcome is not already obvious. Labels should describe what will happen, not the gesture used to trigger it. Keep the same noun and verb for the same concept throughout the product.
For destructive actions, name the object and consequence. Prefer undo over confirmation when recovery is safe. When confirmation is necessary, name the action on both the message and button instead of using Yes, No, OK, or Submit.
Forms
Use persistent labels; placeholders are examples, not labels. Put format and eligibility requirements before submission. Explain why information is requested only when it is not obvious. Required and optional treatment should be consistent.
Validation says what needs attention and how to correct it without blaming the user. Keep related instructions near the field and announce errors accessibly.
Errors and permissions
An actionable error answers:
- what failed;
- why, when known and useful;
- how to recover or what alternative remains.
Do not expose internal codes as the primary message. Do not promise a cause or resolution the system cannot know. Treat privacy, payment, deletion, access loss, and blocked work seriously; warmth is welcome, jokes are not.
Loading, empty, and success states
Loading text names the real operation and sets an honest expectation when the wait is meaningful. Show determinate progress when available; never invent progress.
An empty state distinguishes first use, no results, filters, permissions, and failure. Explain the state and provide the next useful action.
Success confirms the completed outcome and mentions the next consequence only when it changes what the user should do. Routine success should be brief.
Help and instructional text
Helper text answers an implicit question instead of restating the control. Use progressive disclosure for uncommon detail. Link text must make sense out of context; icon-only controls need accessible names.
Voice, accessibility, and localization
Voice stays consistent; tone adapts to the moment. Use plain language without flattening terminology the audience genuinely knows.
- Write complete translatable messages rather than concatenated fragments.
- Keep variables and numbers structured so translators can reorder them.
- Allow expansion instead of abbreviating prematurely.
- Make alt text convey the image's information; use empty alt for decoration.
- Keep screen-reader names aligned with visible labels and outcomes.
- Do not rely on punctuation, color, or iconography to carry the message alone.
Maintain a short terminology glossary when inconsistency spans the product. Do not vary words for literary effect in an interface.
Verify
Read the flow in context and test:
- comprehension without hidden product knowledge;
- actionability at errors, empty states, and decision points;
- factual accuracy and consistent terminology;
- scanability at target widths and 200% zoom;
- long names, localization expansion, pluralization, and dynamic values;
- accessible names and announced state changes;
- tone appropriate to consequence and emotional context.
The final copy is as short as it can be without removing meaning or recovery.
