/brand-guidelines

name: brand-guidelines
description: Write copy following Sentry brand guidelines. Use when writing UI text, error messages, empty states, onboarding flows, 404 pages, documentation, marketing copy, or any user-facing content. Covers both Plain Speech (default) and Sentry Voice tones.

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/)