Write User-Facing Copy Following Brand Guidelines
Sentry's brand voice guide - Plain Speech vs. Sentry Voice, plus concrete rules for buttons, errors, and empty-state copy.
Why it matters
Ensure all user-facing copy adheres to Sentry's established brand voice and style. This skill helps maintain consistency across UI text, documentation, marketing materials, and more.
Outcomes
What it gets done
Generate UI text, onboarding flows, and empty states.
Craft marketing copy and documentation content.
Apply Sentry's 'Plain Speech' and 'Sentry Voice' tones appropriately.
Ensure adherence to grammar, spelling, and punctuation rules.
Install
Add it to your toolbox
Run in your project directory:
curl -fsSL https://spark.entire.vc/get/ag-brand-guidelines | bash Overview
Brand Guidelines
Brand voice guide for writing user-facing Sentry copy - deciding between functional Plain Speech (product UI, docs, errors) and personality-driven Sentry Voice (404 pages, empty states, onboarding), with concrete rules for punctuation, word choice, dash usage, buttons, error messages, empty states, and confirmation dialogs, plus a documented list of anti-patterns to avoid. Use it whenever writing or rewriting user-facing copy in Sentry's voice - UI text, onboarding, empty states, docs, or marketing - and need to know which tone fits the context and how to execute it concretely.
What it does
This skill governs how to write user-facing Sentry copy by choosing between two tones and applying concrete rules. Plain Speech is the default: concise, direct, active-voice, jargon-free, and specific (used for product UI, documentation, error messages, settings, transactional emails, help text). Sentry Voice adds personality - empathetic snark, self-awareness about the absurdity of software - but only in appropriate moments: 404 pages, empty states, onboarding flows, loading states, and "what's new" announcements, never in error messages, settings, documentation, or billing/payment flows where users need trust or focus rather than humor.
When to use - and when NOT to
Use it whenever writing or rewriting user-facing copy in Sentry's voice - UI text, onboarding, empty states, docs, or marketing copy - and specifically when deciding whether a given piece of text should be Plain Speech or Sentry Voice. Default to Plain Speech unless the context specifically calls for personality; Sentry Voice examples given include a 404 page ("This page doesn't exist. Maybe it never did.") and an empty state ("No errors yet. Enjoy this moment of peace while it lasts."), while error messages and billing flows are explicitly listed as places Sentry Voice should never appear.
Inputs and outputs
Concrete mechanical rules cover American English spelling, Title Case for headings versus Sentence case for body/buttons/labels, no exclamation marks in UI text (except celebratory moments), no periods in short labels but periods in complete sentences, no ALL CAPS except acronyms, and specific dash usage (hyphens for compounds/ranges in most UI text, en-dashes for date ranges, em-dashes reserved for longer prose interruption). Word-choice guidance replaces vague filler ("Please," "Sorry," "Error occurred," "Success!") with specific, direct alternatives. Element-specific guidance covers buttons (action verbs, 2-3 words max, no punctuation), error messages (say what happened, why if helpful, what to do next), empty states (explain what belongs there plus a clear action, Sentry Voice is appropriate here), confirmation dialogs (specific button labels like "Delete Project" instead of "OK"), and tooltips (under two sentences, explain why not just what). A documented anti-pattern list flags robot speak ("Item has been successfully deleted" instead of "Deleted"), passive voice, unnecessary words ("in order to" instead of "to"), hedging, double negatives, and marketing speak leaking into UI copy.
Integrations
Full guidance lives in Sentry's own Voice Guidelines and Frontend Handbook (develop.sentry.dev), which this skill operationalizes into concrete, checkable rules for day-to-day copywriting.
Who it's for
Anyone writing Sentry product copy - engineers, designers, or marketers - who need consistent tone decisions and concrete phrasing rules instead of guessing at voice on a case-by-case basis.
Source README
Brand Guidelines
Write user-facing copy following Sentry's brand guidelines.
When to Use
- You need to write or rewrite user-facing copy in Sentry's voice.
- The task involves UI text, onboarding, empty states, docs, marketing copy, or other branded content.
- You need guidance on when to use Plain Speech versus Sentry Voice.
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
- 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
| 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
- Empathetic snark - 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
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
- 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
- Explain what would normally be here
- Provide a clear action to populate the state
- 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
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
FAQ
Common questions
Discussion
Questions & comments · 0
Sign In Sign in to leave a comment.