Setting the file. One moment.
Subchapter 3.8
reference/clarify.mdMarkdown4 KBView on GitHub
Additional context needed: audience knowledge and emotional state.
Rewrite unclear interface text so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice.
Read the entire interaction path, not isolated strings. Identify:
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.
For each state, decide:
Say each idea once. If the heading already explains the state, the introduction should add new information or disappear.
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.
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.
An actionable error answers:
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 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.
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 stays consistent; tone adapts to the moment. Use plain language without flattening terminology the audience genuinely knows.
Maintain a short terminology glossary when inconsistency spans the product. Do not vary words for literary effect in an interface.
Read the flow in context and test:
The final copy is as short as it can be without removing meaning or recovery.
When the language reads cleanly, hand off to /impeccable polish for the final pass.