Documentation Index
Fetch the complete documentation index at: https://mintlify.com/pbakaus/impeccable/llms.txt
Use this file to discover all available pages before exploring further.
Make every word earn its place. Don’t repeat information users can already see.
The Button Label Problem
Never use “OK”, “Submit”, or “Yes/No”. These are lazy and ambiguous.
| Bad | Good | Why |
|---|
| OK | Save changes | Says what will happen |
| Submit | Create account | Outcome-focused |
| Yes | Delete message | Confirms the action |
| Cancel | Keep editing | Clarifies what “cancel” means |
| Click here | Download PDF | Describes the destination |
- “Delete” not “Remove” (delete is permanent, remove implies recoverable)
- “Delete 5 items” not “Delete selected” (show the count)
Error Messages: The Formula
Every error message should answer:
- What happened?
- Why?
- How to fix it?
<!-- Good -->
<p class="error">
Email address isn't valid. Please include an @ symbol.
</p>
<!-- Bad -->
<p class="error">Invalid input</p>
Error Message Templates
| Situation | Template |
|---|
| Format error | ”[Field] needs to be [format]. Example: [example]“ |
| Missing required | ”Please enter [what’s missing]“ |
| Permission denied | ”You don’t have access to [thing]. [What to do instead]“ |
| Network error | ”We couldn’t reach [thing]. Check your connection and [action].” |
| Server error | ”Something went wrong on our end. We’re looking into it. [Alternative action]“ |
Don’t Blame the User
Reframe errors:
✅ "Please enter a date in MM/DD/YYYY format"
❌ "You entered an invalid date"
✅ "Password must be at least 8 characters"
❌ "Your password is too short"
Empty States Are Opportunities
Empty states are onboarding moments:
- Acknowledge briefly
- Explain the value of filling it
- Provide a clear action
<!-- Good -->
<div class="empty-state">
<h3>No projects yet</h3>
<p>Create your first project to start organizing your work.</p>
<button>Create project</button>
</div>
<!-- Bad -->
<div class="empty-state">
<p>No items</p>
</div>
Voice vs Tone
Voice is your brand’s personality—consistent everywhere.
Tone adapts to the moment.
| Moment | Tone Shift |
|---|
| Success | Celebratory, brief: “Done! Your changes are live.” |
| Error | Empathetic, helpful: “That didn’t work. Here’s what to try…” |
| Loading | Reassuring: “Saving your work…” |
| Destructive confirm | Serious, clear: “Delete this project? This can’t be undone.” |
Never use humor for errors. Users are already frustrated. Be helpful, not cute.
Writing for Accessibility
Link Text
Must have standalone meaning:
<!-- Good -->
<a href="#">View pricing plans</a>
<!-- Bad -->
<a href="#">Click here</a>
Alt Text
Describes information, not the image:
<!-- Good -->
<img src="chart.png" alt="Revenue increased 40% in Q4">
<!-- Bad -->
<img src="chart.png" alt="Chart">
<!-- Decorative images -->
<img src="divider.png" alt="">
Icon Buttons
Need aria-label for screen reader context:
<button aria-label="Close dialog">
<svg><!-- X icon --></svg>
</button>
Writing for Translation
Plan for Expansion
German text is ~30% longer than English. Allocate space:
| Language | Expansion |
|----------|-----------||
| German | +30% |
| French | +20% |
| Finnish | +30-40% |
| Chinese | -30% (fewer chars, but same width) |
Translation-Friendly Patterns
Keep numbers separate:
✅ "New messages: 3"
❌ "You have 3 new messages"
✅ "Your account was created successfully"
❌ "Your" + "account" + "was created successfully"
✅ "5 minutes ago"
❌ "5 mins ago"
Consistency: The Terminology Problem
Pick one term and stick with it:
| Inconsistent | Consistent |
|---|
| Delete / Remove / Trash | Delete |
| Settings / Preferences / Options | Settings |
| Sign in / Log in / Enter | Sign in |
| Create / Add / New | Create |
Build a terminology glossary and enforce it. Variety creates confusion.
Avoid Redundant Copy
If the heading explains it, the intro is redundant. If the button is clear, don’t explain it again. Say it once, say it well.
<!-- Redundant -->
<h2>Delete Account</h2>
<p>This will delete your account.</p>
<button>Delete Account</button>
<!-- Better -->
<h2>Delete Account</h2>
<p>This action cannot be undone. All your data will be permanently removed.</p>
<button>Delete account</button>
Loading States
Be specific:
✅ "Saving your draft..."
❌ "Loading..."
"Generating report... This usually takes 30 seconds"
"Processing 47 of 120 files..."
Confirmation Dialogs: Use Sparingly
Most confirmation dialogs are design failures—consider undo instead.
When you must confirm:
- Name the action
- Explain consequences
- Use specific button labels
<!-- Good -->
<dialog>
<h2>Delete project?</h2>
<p>This will permanently delete "Website Redesign" and all its files. This can't be undone.</p>
<button class="danger">Delete project</button>
<button>Keep project</button>
</dialog>
<!-- Bad -->
<dialog>
<p>Are you sure?</p>
<button>Yes</button>
<button>No</button>
</dialog>
Form Instructions
Show format with placeholders, not instructions:
<!-- Good -->
<label>Phone number</label>
<input type="tel" placeholder="(555) 123-4567">
<!-- Avoid -->
<label>Phone number (format: 555-123-4567)</label>
<input type="tel">
<label>Date of birth</label>
<input type="date">
<p class="help-text">We use this to verify your age</p>
Guidelines
- Use specific verb + object button labels
- Answer what happened, why, and how to fix in error messages
- Design empty states that teach and motivate
- Write link text that makes sense out of context
- Build a terminology glossary
- Be specific in loading states
DON’T
- Use jargon without explanation
- Blame users (“You made an error” → “This field is required”)
- Write vague errors (“Something went wrong”)
- Vary terminology for variety
- Use humor for errors
- Repeat information users can already see
