brand-guidelines
Brand Guidelines
Section titled “Brand Guidelines”Write user-facing copy following professional brand guidelines.
Tone Selection
Section titled “Tone Selection”Choose the appropriate tone based on context:
| Use Plain Speech | Use Brand Voice |
|---|---|
| Product UI (buttons, labels, forms) | 404 pages |
| Documentation | Empty states |
| Error messages | Onboarding flows |
| Settings pages | Loading states |
| Transactional emails | ”What’s New” announcements |
| Help text | Marketing copy |
Default to Plain Speech unless the context specifically calls for personality.
Plain Speech (Default)
Section titled “Plain Speech (Default)”Plain Speech is clear, direct, and functional. Use it for most UI elements.
- Be concise - Use the fewest words needed
- Be direct - Tell users what to do, not what they can do
- Use active voice - “Save your changes” not “Your changes will be saved”
- Avoid jargon - Use simple words users understand
- Be specific - “3 errors found” not “Some errors found”
Examples
Section titled “Examples”| Instead of | Write |
|---|---|
| ”Click here to save your changes" | "Save" |
| "You can filter results by date" | "Filter by date" |
| "An error has occurred" | "Something went wrong" |
| "Please enter a valid email address" | "Enter a valid email" |
| "Are you sure you want to delete?" | "Delete this item?” |
Brand Voice
Section titled “Brand Voice”Brand Voice adds personality in appropriate moments. It’s empathetic, self-aware, and occasionally playful.
Principles
Section titled “Principles”- Empathetic - Direct frustration at the situation, never the user
- Self-aware - Acknowledge the absurdity of software
- Fun but functional - Personality should enhance, not obscure meaning
- Earned moments - Only use when users have time to appreciate it
Examples
Section titled “Examples”404 Pages:
“This page doesn’t exist. Maybe it never did. Maybe it was a dream. Either way, let’s get you back on track.”
Empty States:
“No items yet. Your space awaits.”
Onboarding:
“Let’s get started. This won’t take long.”
Loading States:
“Crunching the numbers…” “Fetching your data…”
When NOT to Use Brand Voice
Section titled “When NOT to Use Brand Voice”- Error messages (users are frustrated)
- Settings pages (users are focused)
- Documentation (users need information)
- Billing/payment flows (users need trust)
General Rules
Section titled “General Rules”Spelling and Grammar
Section titled “Spelling and Grammar”- Use American English spelling (color, not colour)
- Use Title Case for headings and page titles
- Use Sentence case for body text, buttons, and labels
Punctuation
Section titled “Punctuation”- No exclamation marks in UI text (exception: celebratory moments)
- No periods in short UI labels or button text
- Use periods in complete sentences and help text
- No ALL CAPS except for acronyms (API, SDK, URL)
Word Choices
Section titled “Word Choices”| Avoid | Prefer |
|---|---|
| Please | (omit) |
| Sorry | (be specific about the problem) |
| Error occurred | Something went wrong |
| Invalid | (explain what’s wrong) |
| Success! | (describe what happened) |
| Oops | (be specific) |
Dash Usage
Section titled “Dash Usage”| Type | Use | Example |
|---|---|---|
| Hyphen (-) | Compound words, ranges | ”real-time”, “1-10” |
| En-dash (—) | Ranges, relationships | ”2023—2024”, “parent—child” |
| Em-dash (---) | Interruption, emphasis | ”Details---even small ones---matter” |
In most UI contexts, use hyphens. Reserve en-dashes for date ranges and em-dashes for longer prose.
UI Element Guidelines
Section titled “UI Element Guidelines”Buttons
Section titled “Buttons”- Use action verbs: “Save”, “Delete”, “Create”
- Be specific: “Create Project” not just “Create”
- Max 2-3 words when possible
- No periods or exclamation marks
Error Messages
Section titled “Error Messages”- Say what happened
- Say why (if helpful)
- Say what to do next
Good: “Could not save changes. Check your connection and try again.” Bad: “Error: Save failed.”
Empty States
Section titled “Empty States”- Explain what would normally be here
- Provide a clear action to populate the state
- Brand Voice is appropriate here
Good: “No projects yet. Create your first project to get started.”
Confirmation Dialogs
Section titled “Confirmation Dialogs”- Make the action clear in the title
- Explain consequences if destructive
- Use specific button labels (“Delete Project”, not “OK”)
Tooltips and Help Text
Section titled “Tooltips and Help Text”- Keep under 2 sentences
- Explain the “why”, not just the “what”
- Link to docs for complex topics
Anti-Patterns
Section titled “Anti-Patterns”Avoid these common mistakes:
- Robot speak: “Item has been successfully deleted” -> “Deleted”
- Passive voice: “Changes were saved” -> “Changes saved”
- Unnecessary words: “In order to” -> “To”
- Hedging: “This might cause…” -> “This will cause…”
- Double negatives: “Not unlike…” -> “Similar to…”
- Marketing speak in UI: “Supercharge your workflow” -> “Speed up your workflow”
References
Section titled “References”- Professional Voice Guidelines - Professional standards from Sentry
- Frontend Handbook - Industry best practices