brand-guidelines

# Brand Guidelines Write user-facing copy following Sentry's brand guidelines. ## Tone Selection Choose the appropriate tone based on context: | Use Plain Speech | Use Sentry 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) Plain Speech is clear, direct, and functional. Use it for most UI elements. ### Rules 1. **Be concise** - Use the fewest words needed 2. **Be direct** - Tell users what to do, not what they can do 3. **Use active voice** - "Save your changes" not "Your changes will be saved" 4. **Avoid jargon** - Use simple words users understand 5. **Be specific** - "3 errors found" not "Some errors found" ### 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?" | ## Sentry Voice Sentry Voice adds personality in appropriate moments. It's empathetic, self-aware, and occasionally snarky. ### Principles 1. **Empathetic snark** - Direct frustration at the situation, never the user 2. **Self-aware** - Acknowledge the absurdity of software 3. **Fun but functional** - Personality should enhance, not obscure meaning 4. **Earned moments** - Only use when users have time to appreciate it ### 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 errors yet. Enjoy this moment of peace while it lasts." **Onboarding:** > "Let's get your first error. Don't worry, it's not as scary as it sounds." **Loading States:** > "Crunching the numbers..." > "Fetching your data..." ### When NOT to Use Sentry Voice - Error messages (users are frustrated) - Settings pages (users are focused) - Documentation (users need information) - Billing/payment flows (users need trust) ## General Rules ### 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 - **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 | 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 | Type | Use | Example | |------|-----|---------| | Hyphen (-) | Compound words, ranges | "real-time", "1-10" | | En-dash (--) | Ranges, relationships | "2023--2024", "parent--child" | | Em-dash (---) | Interruption, emphasis | "Errors---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 ### 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 1. Say what happened 2. Say why (if helpful) 3. Say what to do next **Good:** "Could not save changes. Check your connection and try again." **Bad:** "Error: Save failed." ### Empty States 1. Explain what would normally be here 2. Provide a clear action to populate the state 3. Sentry Voice is appropriate here **Good:** "No projects yet. Create your first project to start tracking errors." ### 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 - Keep under 2 sentences - Explain the "why", not just the "what" - Link to docs for complex topics ## 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 - [Sentry Voice Guidelines](https://develop.sentry.dev/frontend/sentry-voice/) - [Sentry Frontend Handbook](https://develop.sentry.dev/frontend/)