UX Writing Style Guide

A comprehensive reference for UX writing at Apollo. The rules in this guide draw on trusted writing sources and our own team's years of expertise.

Introduction

UX writing is the practice of crafting the words that appear in digital interfaces—buttons, labels, error messages, onboarding flows, empty states, and every other element a user encounters while using a piece of software. Unlike marketing copy, UX writing doesn't persuade; it serves, helping users accomplish their goals with as little confusion as possible.

Great UX writing is often invisible. When the words are clear and the flow is logical, users don't notice them—they complete the task. When copy fails, users get stuck, make errors, or abandon the flow entirely. A single unclear label can undo an otherwise polished experience.

The five principles

Good UX writing has these five qualities. When in doubt, check your copy against each one.

• Correct—Accuracy is non-negotiable. Every label, message, and instruction must reflect what the product actually does.

• Clear—Use plain language. Write for comprehension at first glance—not after re-reading.

• Concise—Eliminate every unnecessary word. Users scan interfaces, not documents.

• Conscientious—Consider who's reading and what they're feeling. Write with empathy, not just craft.

• Compelling—Move people, not just pixels. Writing that inspires earns attention; writing that delights earns trust.

How to use this guide

Start with Voice and tone to establish your product's foundational character. A clearly defined voice makes every writing decision easier. Then work through Writing patterns as you encounter specific UI copy challenges.

The Microcopy and Accessibility sections cover copy that's easy to overlook in early design stages but significantly affects usability. Use the Style section as a mechanical reference—consult it when you have a specific question about capitalization, punctuation, numbers, or abbreviations.

Compelling copy

Clear writing gets users to start reading. Compelling writing makes them want to finish. Those two things are not in conflict, and the best UX copy does both.

Compelling writing in a product context isn't about poetry. It's about the difference between copy that users process and copy that users feel. A single well-chosen word, a sentence with unexpected rhythm, a moment of earned warmth—those are what separate forgettable interfaces from ones that build genuine loyalty.

Lead with outcomes, not processes

Users aren't motivated by steps; they're motivated by what those steps make possible. Compelling copy names the destination first, then the path.

• Don't: "Use our time-tracking tools to log hours against each project and generate reports."

• Do: "Know exactly where your time goes—and where it's going next."

Vary sentence length—short sentences hit harder

Long sentences build context; short ones deliver impact. Alternating between them creates rhythm, which is more engaging and easier to remember. The most powerful sentence on a screen is often the shortest one. Use it deliberately, at the moment of highest consequence.

• Don't: "Your project has been successfully published and is now live on the web and accessible to everyone."

• Do: "Your project took three weeks of work. It's been live for 30 seconds. Go tell someone."

Choose the specific word over the general one

Specific language is more vivid, more credible, and more memorable than general language. The closer a word is to the precise truth of the situation, the more the word resonates. Vague words ("things," "stuff," "various") bleed into the background; precise words stick.

• Don't: "A lot of teams use this to manage their work."

• Do: "More than 40,000 teams use this to ship on time."

Use parallelism to build rhythm and momentum

Parallel sentence structure—matching the grammatical form of items in a list or series—creates a rhythm that propels the reader forward. When three things share a structure, the reader's brain anticipates the pattern and follows it willingly.

• Don't: "Collaborate with your team, projects can be shared easily, and you'll ship faster."

• Do: "Collaborate in real time. Share without friction. Ship together."

Find the emotional truth of each moment—then understate it

Every UI moment has an emotional context: anticipation before a first action, relief after a long process, pride at a milestone. Compelling copy acknowledges that context without performing it. One sentence of quiet, accurate warmth is worth ten exclamation points.

• Don't: "🎉 Incredible! You've finished setting up your workspace! You're amazing!"

• Do: "All set. That was the hard part." (after a multi-step setup flow)

Let personality live in word choice, not punctuation or decoration

Exclamation points and emoji are shortcuts that broadcast effort without demonstrating it. A well-chosen verb, an unexpected but precise adjective, or a slight structural surprise does more for personality than any amount of decoration.

• Don't: "Your report is ready! 📊🎉"

• Do: "Your report is ready—and the numbers are interesting."

Earn enthusiasm—delight through restraint, not volume

Delight in interfaces most often comes from surprise—from warmth in a place users didn't expect it, from a moment of wit that doesn't overstay its welcome. When enthusiasm is the default register, nothing stands out. Save it for exactly the right moment.

• Don't: Every screen ends in an exclamation point; every success state has an emoji; every empty state has a joke. Users stop reading any of it.

• Do: Ninety percent of the product is clean and functional. One small, unexpected line—"You've sent 500 messages. Your team is listening."—earns a smile precisely because it's rare.

Voice and tone

Defining your voice

Voice is who you are. It's the consistent expression of your brand's personality across every word in the product.

Define voice as attributes, not adjectives

For each voice attribute, document what it means in practice and what it is NOT. A vague attribute like "friendly" is only useful when it's qualified.

• Don't: Voice attribute: "Friendly"

• Do: Voice attribute: "Warm—we treat users like capable adults, not customers to manage."

Write in second person—address users as "you"

Second person creates a direct, personal connection. Third person ("the user," "users") reads like a manual and creates unnecessary distance. Use "we" for the product or company when needed.

• Don't: "Users can export their data from the Settings page."

• Do: "You can export your data from Settings."

Use contractions—they signal human voice

Contractions (it's, you'll, we're, can't) make copy feel natural and approachable. Avoiding them makes writing feel stiff and formal. Only avoid contractions when you need to add emphasis: "You cannot undo the action."

• Don't: "You will need to verify your email address before you are able to continue."

• Do: "You'll need to verify your email before you can continue."

Use simple, everyday words over formal or technical ones

Prefer the word your users would say out loud. Formal synonyms add no meaning and create cognitive overhead. Exceptions: technical terms your audience expects and uses themselves.

• Don't: "Utilize" / "Facilitate" / "Leverage" / "Terminate"

• Do: "Use" / "Help" / "Use" / "End" or "Stop"

Keep sentences short—aim for 25 words or fewer

Short sentences are easier to scan, process, and act on. Long sentences in UI copy almost always contain an idea that can be cut or split. If a sentence needs a semicolon, consider splitting it in two.

• Don't: "To get started with collaboration, you'll first need to invite your team members by sending them an invitation email, which they can accept to gain access to your workspace."

• Do: "Invite your team to get started. They'll get an email with a link to join your workspace."

Tone variations

Voice is constant. Tone shifts with context—the same brand can sound calm in an error state and warm in a success state.

Calibrate tone to the emotional weight of the moment

High-stakes moments (data loss, billing errors, and account suspension) call for a calm, focused, solution-forward tone. Low-stakes moments (onboarding, first use, success states) allow for more warmth and personality.

• Don't: "Oops! Looks like something went sideways. 😬 Let's try that again!" (on a payment failure)

• Do: "Payment didn't go through. Check your card details and try again."

Avoid exclamation points as a default tone signal

Exclamation points feel genuine only in rare moments of real delight. When overused, they signal insincerity and create "notification fatigue." Reserve them for moments where excitement is actually warranted.

• Don't: "File uploaded!" / "Settings saved!" / "Welcome to your dashboard!"

• Do: "File uploaded" / "Settings saved" / "Welcome to your dashboard"

Never use humor in destructive or irreversible states

Humor in an error state, deletion confirmation, or security warning feels tone-deaf and erodes trust. Reserve playfulness for low-stakes, celebratory, or informational moments where users aren't anxious or at risk of losing something.

• Don't: "Whoops—looks like you've been locked out! 🔐" (after failed login attempts)

• Do: "Too many failed attempts. Your account is locked for 15 minutes."

Omit "please"—it adds no meaning and can feel patronizing

"Please" is a filler word in UI copy. It adds length, can feel condescending, and rarely changes how a message lands. Remove it unless you need to soften an unavoidable imposition.

• Don't: "Please enter your email address to continue."

• Do: "Enter your email to continue."

Brand personality

Personality is expressed through word choice, sentence rhythm, and what you choose to say—not through exclamation points or emoji.

Use active voice to signal confidence and directness

Active voice puts the subject first and the action second. It's more decisive, shorter, and more readable than passive voice. A confident brand uses active voice as the default—passive voice sounds evasive.

• Don't: "Your changes have been saved by the system."

• Do: "Changes saved."

Avoid condescending qualifiers

Words like "simply," "just," "easily," and "obviously" imply that a task is trivial—and make users feel bad when they find it difficult. Remove them: the instruction is clearer without them anyway.

• Don't: "Just click Settings to easily change your preferences."

• Do: "Go to Settings to change your preferences."

Write in present tense

Present tense is immediate and direct. Future tense creates unnecessary distance between the action and the outcome. In UI, things happen now—write as if they do.

• Don't: "Your file will be deleted when you click Confirm."

• Do: "Selecting Confirm deletes the file permanently."

Frame limitations positively—lead with what users can do

Negative framing creates friction and feels like a wall. When a user hits a limitation, tell them what is possible, then explain the constraint. This preserves momentum and respects their agency.

• Don't: "You can't invite more than 5 members with this plan."

• Do: "Your plan allows you to invite up to 5 members. Upgrade to invite more."

Common pitfalls

The writing habits that appear most often in interfaces—and consistently make copy worse.

Don't reference the UI in instructions

Telling users to "tap the button below" or "click on the blue icon in the top right" creates instructions that break when the UI changes, don't work across platforms, and clutter copy with unnecessary detail. Describe the action or destination, not the element.

• Don't: "Tap the blue button below to continue to the next step."

• Do: "Select Continue."

Don't use "click here" as link text

Link text should describe the destination or action, not the interaction. "Click here" is meaningless out of context, fails accessibility guidelines, and doesn't work for users who navigate by tab or screen reader.

• Don't: "To reset your password, click here."

• Do: "Reset your password."

Don't use ellipsis to create suspense or trail off

Ellipsis (…) has two legitimate uses in UI: loading states and truncated text. Using it to create conversational pauses ("Let's see…") or imply more information exists undermines credibility and reads as indecisive.

• Don't: "Looks like something went wrong… Try refreshing the page."

• Do: "Something went wrong. Try refreshing the page."

Don't use jargon or unexplained acronyms

Technical terms and acronyms exclude users who don't know them without adding value for users who do. Write for your least-technical user, and define any term that isn't universally understood in the context where it appears.

• Don't: "Configure your SMTP relay settings to enable transactional email delivery."

• Do: "Connect an email provider to start sending emails from your domain."

Be consistent with terminology—use the same term for the same thing

Switching between synonyms ("workspace," "project," "environment") for the same concept forces users to work out whether they're the same thing. Pick one term per concept and use it everywhere, even if it feels repetitive.

• Don't: "Create a new workspace" → "Your project is ready" → "Open your environment"

• Do: "Create a workspace" → "Your workspace is ready" → "Open your workspace"

Writing patterns

Buttons and CTAs

Button labels should describe the action specifically enough that users never need surrounding context to understand what will happen.

Use a verb + noun pair for most button labels

The verb describes what happens; the noun specifies what it happens to. This pattern is specific, scannable, and actionable. Single-word verbs ("Save," "Continue") are acceptable when the object is obvious from context.

• Don't: "Submit" / "Confirm" / "Proceed" / "OK"

• Do: "Save draft" / "Confirm payment" / "Create account" / "Delete project"

Use imperative mood—start with the action verb

Button labels should be commands, not descriptions. Use the imperative form of the verb ("Download," "Share," "Send") rather than a noun form.

• Don't: "File Download" / "Account Deletion" / "Password Reset"

• Do: "Download file" / "Delete account" / "Reset password"

Be explicit about destructive or irreversible actions

When an action cannot be undone, the label should make that clear. "Delete" alone is acceptable for recoverable actions. For permanent ones, add the consequence.

• Don't: "Delete" (for a permanent, unrecoverable action)

• Do: "Delete permanently" / "Cancel subscription" / "Remove all data"

Use the same label for the same action, everywhere

Consistency reduces cognitive load. If the action that saves a document is called "Save" in one place and "Apply" in another, users have to verify they're the same thing. Pick one label per action and apply it universally.

• Don't: "Save changes" → "Apply" → "Update" (for the same action across different screens)

• Do: "Save changes" used consistently across all screens where the action appears

Use "select" rather than "click"—be device-agnostic

Users interact with products on touchscreens, keyboards, and mice. "Select" and "choose" work for all input methods. "Click" implies a mouse; "tap" implies touch.

• Don't: "Click the checkbox to enable notifications."

• Do: "Select the checkbox to enable notifications."

Error messages

Error messages are the most important copy in any product. Users read them when something has already gone wrong—make every word count.

Always say what happened and what to do next

An error message that only describes the problem leaves users stuck. Every error needs two components: a clear statement of what went wrong, and a specific next step.

• Don't: "An error occurred."

• Do: "We couldn't save your changes. Check your connection and try again."

Never blame the user

Error messages should describe what happened—not who caused it. Avoid "you" as the subject of a failure statement.

• Don't: "You entered an invalid email address." / "You've exceeded your storage limit."

• Do: "Enter a valid email address (like name@example.com)." / "Storage limit reached. Delete files or upgrade your plan."

Be specific—don't bundle multiple errors into one vague message

Generic error messages ("Please fill in all required fields") force users to hunt for the problem. Identify the specific field, value, or condition that caused the error.

• Don't: "Please correct the errors in the form."

• Do: "Phone number must be 10 digits." / "Password must be at least 8 characters."

Use plain language—no error codes in user-facing messages

System codes ("Error 500," "Code: AUTH_TOKEN_EXPIRED") are meaningful to developers and useless to end users. If you must include a code for support purposes, put it in small secondary text below the human-readable message.

• Don't: "Error 403: Forbidden. Access to the requested resource is denied."

• Do: "You don't have permission to view this page. Contact your admin for access."

Don't over-apologize—focus on the fix

A brief acknowledgment is fine. Excessive apology delays the resolution, feels hollow, and wastes the user's time. Lead with the problem and solution.

• Don't: "We're really sorry, but it seems like there was a problem processing your request."

• Do: "Something went wrong on our end. Try again in a few minutes."

Empty states

An empty state is not a failure—it's a starting point. Explain why it's empty and give users a clear path forward.

Distinguish between first-time, zero-result, and filtered empty states

Each empty state type has a different cause and requires different copy. A first-time empty state should be encouraging; a no-results state should confirm the search and offer alternatives; a filtered empty state should name the active filter and offer to clear it.

• Don't: "No results found." (used for all three scenarios)

• Do: First use: "No files yet. Upload your first file to get started." / Search: "No results for 'invoice'—try a different search."

Always include an action—don't leave users at a dead end

Every empty state should tell users what they can do to move forward: create something, broaden a search, clear a filter, or contact support. A description alone isn't enough—pair it with a button or link.

• Don't: "Your inbox is empty."

• Do: "Your inbox is empty. [Compose a message]"

Be encouraging for first-time states, not just descriptive

A user seeing an empty state for the first time is in an exploratory mindset. This is an opportunity to set context, communicate value, and motivate the first action.

• Don't: "No projects. Create a project to begin."

• Do: "Your projects will live here. Create your first one to start organizing your work."

Onboarding copy

The goal of onboarding is to get users to their first moment of value as quickly as possible—with copy that orients, motivates, and then disappears.

Skip "Welcome to [Product]!"—get to the point

Welcome messages are filler. The user already knows they signed up; they don't need confirmation. Use the first line of onboarding to tell users what they'll be able to do, or to orient them to their first task.

• Don't: "Welcome to Acme! We're so excited to have you here. Let's get started!"

• Do: "Your workspace is ready. Let's set up your first project."

Set time expectations to reduce anxiety

Users hesitate to start a setup flow when they don't know how long it will take. A brief time estimate ("Takes about 2 minutes") lowers the perceived cost of starting and increases completion rates.

• Don't: "Complete these steps to set up your account."

• Do: "Get set up in about 2 minutes."

Use progressive disclosure—don't explain everything upfront

Show users what they need to know when they need to know it. Overloading the first screen with features, options, and tips creates anxiety and decision paralysis.

• Don't: A five-slide onboarding tour covering every feature before the user has done anything.

• Do: Contextual tips that appear inline when the user reaches a relevant feature for the first time.

Focus on outcomes, not features

Users care about what a product helps them do, not about how the product works. Describe the outcome they'll achieve, not the feature they'll use to achieve it.

• Don't: "Use our drag-and-drop kanban board with custom labels and automated workflows."

• Do: "Track your team's work so nothing falls through the cracks."

Notifications

Every notification interrupts the user. The bar for that interruption is high—the message must be timely, relevant, and actionable.

Lead with the most important information

Notification text is often truncated. The first few words must carry the full meaning. Don't bury the key detail at the end of a sentence—put it first, so users understand the message even if they only see a preview.

• Don't: "A change was made to your account—your billing plan has been updated to Pro."

• Do: "Billing plan updated to Pro."

Include an action when the notification requires one

If a notification is telling the user something requires their attention, give them a direct path to act on it. A notification without an action path creates anxiety.

• Don't: "Your payment failed." (no action)

• Do: "Payment failed. [Update billing info]"

Keep notification text to one or two sentences

Notifications are interruptions, not documents. Users should be able to understand the full message in a single glance. If the message requires more explanation, it belongs on a detail page—link to it instead.

• Don't: A four-sentence notification explaining the full context of why a backup failed and all the possible causes.

• Do: "Backup failed. Check your storage connection and try again."

Tooltips and help text

Help text should add information the label doesn't already convey. If the label is self-explanatory, the tooltip isn't needed.

Add information—don't restate the label

A tooltip that repeats the label word-for-word adds no value and wastes the user's time. Use help text to explain format requirements, unexpected behaviors, or contextual nuance that the label alone can't convey.

• Don't: Label: "Password" / Tooltip: "Enter your password"

• Do: Label: "Password" / Help text: "Must be at least 8 characters, with one number and one symbol."

Keep tooltips to one sentence

Tooltips are contextual and ephemeral—they appear on hover and disappear when the user moves on. Long tooltips are hard to read before they vanish. If the concept requires more than one sentence, link to a help article instead.

• Don't: A four-sentence tooltip explaining the full history and implications of a feature.

• Do: "Turns on two-factor authentication for all team members."

Don't put essential information in a tooltip

Tooltips are invisible until triggered. Any information the user needs to complete a task successfully—format requirements, character limits, and required fields—should appear inline, not behind a hover state.

• Don't: Putting "File must be under 5 MB" in a tooltip on an upload button.

• Do: "File must be under 5 MB" displayed as inline help text below the upload area.

Confirmation dialogs

Confirmation dialogs exist to prevent accidental, irreversible actions. The copy must communicate the consequence clearly enough that users can decide with confidence.

Write a headline that states the consequence, not a question

"Are you sure?" tells users nothing about what they're confirming. The headline should state what will happen if they proceed.

• Don't: "Are you sure?" / "Confirm action"

• Do: "Delete your project?" / "Remove Sarah from your workspace?"

Mirror the headline in the primary button label

The confirm button should echo the action stated in the headline. This pairing makes the consequence of clicking unmistakable and removes all ambiguity about which button does what.

• Don't: Headline: "Delete project?" → Buttons: "Yes" / "No"

• Do: Headline: "Delete your project?" → Buttons: "Delete project" / "Keep project"

Explain consequences of destructive actions in the body copy

For irreversible actions, the body of the dialog should spell out exactly what will be lost or changed—not just restate the headline.

• Don't: Body: "This action cannot be undone."

• Do: Body: "All files, members, and settings in your project will be permanently deleted. You can't undo that action."

Microcopy

Form labels

Labels are the primary navigation system for forms. They must be clear, specific, and always visible—never sacrificed for the sake of visual cleanliness.

Never use placeholder text as a substitute for a label

Placeholder text disappears as soon as the user starts typing. If the label is only in the placeholder, users lose context mid-form—especially when tabbing between fields or reviewing before submitting. Always show a persistent label above the input.

• Don't: An input with no label—the placeholder reads "Enter your company name."

• Do: A label "Company name" above the input; placeholder can show an example format.

Keep labels short—one to three words

Form labels aren't the place for instructions or context. If a field needs explanation, use help text below the input. The label itself should identify the field in as few words as possible.

• Don't: "Please enter your full legal first and last name as it appears on your ID"

• Do: "Full name" (with optional help text: "As it appears on your ID")

Mark required fields consistently—choose one system and apply it

Either mark required fields (asterisk + legend) or optional fields ("Optional" inline)—but not both. As a general rule, mark the minority: if most fields are required, mark only the optional ones.

• Don't: Some fields marked with *, some with "(required)", some with "(optional)"—no consistent system.

• Do: Optional fields consistently labeled "(optional)" in secondary text; all others assumed required.

Use sentence case—not title case or all caps

Sentence case (only the first word capitalized) reads more naturally and scans faster than title case. Reserve title case for proper nouns and branded product names only.

• Don't: "First Name" / "Email Address" / "DATE OF BIRTH"

• Do: "First name" / "Email address" / "Date of birth"

Placeholder text

Placeholder text is contextual and ephemeral. Use it to show format examples—not to replace labels or convey instructions.

Use placeholder text for examples, not instructions

Placeholder text is most useful when it shows the expected format of the input—a real-looking example that helps users understand what to type. Instructions belong in the label or help text, where they're always visible.

• Don't: "Enter your email address here"

• Do: "for example, name@company.com"

Use realistic sample data—not "Lorem ipsum" or "Type here"

Generic placeholder text ("Your name here," "Enter text") is no more helpful than having no placeholder at all. Use realistic-looking examples that show the type and format of content expected.

• Don't: "Enter name" / "Your company" / "Type here…"

• Do: "for example, Sarah Chen" / "for example, Acme Corp" / "for example, Design review notes"

Don't put information in placeholders that users need to complete the field

Placeholder text vanishes the moment a user clicks into the field. If the format requirement, character limit, or constraint is something users need to refer to while typing, it belongs in persistent help text—not a placeholder.

• Don't: Placeholder: "Passwords must be 8+ characters with a number and symbol" (disappears on focus)

• Do: Help text below the input: "8+ characters, at least one number and one symbol"

Success messages

Confirm what happened, be specific about what changed, and resist the urge to over-celebrate routine actions.

Confirm the specific action—don't just say "Success"

A generic "Success!" doesn't tell the user what succeeded. Name the action and, where useful, the outcome. This confirms the system did what the user intended and reduces the need to verify manually.

• Don't: "Success!" / "Done!" / "Completed."

• Do: "Password changed." / "Invitation sent to sarah@company.com." / "3 files uploaded."

Match celebration level to the significance of the action

Saving a form deserves a quiet confirmation toast. Completing a first project or reaching a milestone might warrant a more expressive success state. Over-celebrating routine tasks feels patronizing; under-celebrating milestones feels cold.

• Don't: "🎉 Amazing! You did it! Your settings have been saved!" (for a settings save)

• Do: "Settings saved." (toast) vs "Your first project is live!" (milestone screen)

Include a next step when the user's journey doesn't end here

A success message is a natural pause in the user's workflow. Use it to point toward what comes next—whether that's reviewing what was just created, inviting a collaborator, or returning to a main view.

• Don't: "Account created." (user is left wondering what to do)

• Do: "Account created. [Go to your dashboard]"

Loading states

Loading states tell users that something is happening and they should wait. The copy should manage expectations, reduce anxiety, and signal progress.

Describe what's loading—not just that loading is occurring

Generic loading text ("Loading…") tells users nothing. Wherever possible, describe what the system is doing. This makes wait times feel productive and reduces abandonment.

• Don't: "Loading…" / "Please wait…"

• Do: "Fetching your reports…" / "Analyzing your data…" / "Preparing your export…"

Ellipsis is acceptable in loading copy—but only there

The ellipsis (…) communicates ongoing process and is conventional in loading states. Reserve it for that purpose—don't use ellipsis as a stylistic device in other UI copy.

• Don't: "Looks like something went sideways… Give it another try."

• Do: "Syncing your files…" (in a progress state only)

Set time expectations for long operations

If a process takes more than a few seconds, tell users how long it will take. Even a rough estimate ("This takes about a minute") reduces abandonment significantly compared to an indeterminate spinner with no context.

• Don't: An indeterminate spinner with no text, for a process that takes 45 seconds.

• Do: "Generating your report… This usually takes about a minute."

Accessibility

Inclusive language

Inclusive copy respects the diversity of your users—their backgrounds, abilities, identities, and contexts. These choices determine who feels welcome in your product.

Use "they/them" for unspecified individuals

When referring to a person whose gender is unknown or unspecified, use the singular "they." It's grammatically correct, avoids assumptions, and is more readable than "he or she."

• Don't: "The admin can change his or her settings." / "When a user logs in, he sees…"

• Do: "The admin can change their settings." / "When a user logs in, they see…"

Use "allowlist" and "blocklist"—not "whitelist" and "blacklist"

The terms whitelist and blacklist carry racial connotations that can exclude and alienate users. Allowlist and blocklist are more precise (they describe the function directly) and are now the industry standard in technical documentation.

• Don't: "Add the domain to your whitelist." / "Blacklisted IP addresses are blocked."

• Do: "Add the domain to your allowlist." / "Blocked IP addresses can't access the API."

Avoid ableist language and sensory assumptions

Phrases that assume a specific sensory ability ("as you can see," "click the red button") exclude users who are blind or colorblind. Use neutral, ability-agnostic language that describes the action or outcome, not the physical experience.

• Don't: "As you can see in the diagram above…" / "Click the green checkmark."

• Do: "The diagram shows…" / "Select the checkmark labeled 'Confirm.'"

Avoid idioms and culturally specific references

Idioms ("knock it out of the park"), pop culture references, and humor rooted in a specific cultural context don't translate globally—and often don't translate at all for users who aren't native English speakers. Write for a worldwide audience.

• Don't: "You're killing it! 🎯" / "Hit the ground running with your new workspace."

• Do: "Great start." / "Your workspace is ready."

Don't convey meaning through color alone

Approximately 8% of men and 0.5% of women have some form of color blindness. If color is the only signal communicating a state (error, success, and warning), users who can't distinguish those colors will miss it. Always pair color with text, iconography, or pattern.

• Don't: A red border on an input field with no error message explaining what went wrong.

• Do: A red border + inline error message: "This field is required."

Alt text

Alt text makes images accessible to users who rely on screen readers—and improves discoverability. Write it for function, not appearance.

Describe function for functional images, content for informational ones

For a button icon, the alt text should say what the button does, not what the icon looks like. For an informational image like a chart or screenshot, describe what the image communicates.

• Don't: Icon button alt text: "magnifying glass icon"

• Do: Icon button alt text: "Search"

Don't start with "Image of…" or "Picture of…"

Screen readers announce that an element is an image automatically. Starting alt text with "Image of" is redundant and wastes the user's time. Start directly with the description.

• Don't: "Image of a bar chart showing monthly revenue from January to June."

• Do: "Bar chart showing monthly revenue from January to June, peaking in April at $240K."

Use empty alt text for decorative images

Images that are purely decorative (background patterns, decorative dividers, and stock photos that add no meaning) should have an empty alt attribute (alt=""). This tells screen readers to skip the element entirely, reducing noise.

• Don't: alt="abstract background decoration with flowing lines"

• Do: alt="" (empty, so the screen reader skips it)

For charts and graphs, describe the key insight—not just the type

Saying "bar chart of sales data" doesn't tell a screen reader user anything meaningful. Describe what the chart communicates—the trend, the standout value, or the comparison the chart is meant to convey.

• Don't: "Pie chart showing user breakdown by region."

• Do: "Pie chart showing user breakdown by region. North America leads at 54%, followed by Europe at 28%."

Screen reader copy

Screen reader users navigate interfaces by hearing a sequential list of elements. Copy that's written for visual scanning often fails completely in audio form.

Every interactive element needs a unique, descriptive accessible name

Icon-only buttons, unlabeled inputs, and elements with duplicate labels ("Edit," "Edit," "Edit" on a list of items) are incomprehensible when read aloud. Use aria-label or visually hidden text to give each element a distinct, descriptive name.

• Don't: Three "Edit" buttons on a table of rows—a screen reader user can't tell which is which.

• Do: aria-label="Edit project: Q4 Marketing Plan" / aria-label="Edit project: Website Redesign"

Confirm completed actions with status messages

When a user submits a form, sends a message, or completes an action, announce the outcome with a status message that screen readers can detect. A visual toast that appears and disappears may not be announced—use ARIA live regions for dynamic confirmations.

• Don't: A success toast that appears visually but is not communicated to the screen reader.

• Do: An ARIA live region that announces "Message sent" when the action completes.

Write link and button text that makes sense out of context

Screen reader users often navigate by pulling up a list of all links or buttons on a page. "Click here," "Learn more," and "Read this" are meaningless in that list. Every link and button should be understandable without the surrounding copy.

• Don't: "For pricing details, click here." / Multiple "Learn more" links on one page.

• Do: "View pricing" / "Learn more about two-factor authentication"

Style

General conventions

Use sentence case for all UI labels and headings

Sentence case (capitalize only the first word and proper nouns) is the standard for UI copy. It reads faster, feels more natural, and aligns with how people write in conversation.

• Don't: "Edit Your Profile Settings" / "Notification Preferences"

• Do: "Edit your profile settings" / "Notification preferences"

Use active voice—subject acts, rather than being acted upon

Active voice is shorter, more direct, and more natural. Passive voice obscures agency and creates wordier sentences. Default to active voice; use passive voice only when the actor is unknown or irrelevant.

• Don't: "Your account has been suspended by our team."

• Do: "We suspended your account."

Always use the serial (Oxford) comma

The serial comma—placed before "and" or "or" in a list of three or more items—prevents ambiguity. The cost is one character; the benefit is unambiguous meaning.

• Don't: "Export your contacts, projects and files." (ambiguous: are projects and files one thing?)

• Do: "Export your contacts, projects, and files."

Use numerals in UI—not spelled-out numbers

In interface copy, numerals are faster to read than spelled-out numbers and take less space. Reserve spelled-out numbers for long-form body copy.

• Don't: "You have seven unread messages." / "Upload up to five files."

• Do: "You have 7 unread messages." / "Upload up to 5 files."

Lead with what the user can do, not what they can't

Negative framing creates cognitive friction. When communicating a constraint, state the available option first.

• Don't: "You can't share files unless you upgrade your plan."

• Do: "File sharing is available on the Pro plan. Upgrade to share files with your team."

Capitalization

Consistent capitalization reduces visual noise and signals which terms are proper names versus common nouns.

Sentence case for everything—except proper nouns and branded names

Apply sentence case to all headings, labels, buttons, navigation items, and body copy. Capitalize only the first word and any proper nouns (names of people, products, companies, and specific branded features).

• Don't: "Manage Your Account Settings" / "Create A New Project" / "Upload Files"

• Do: "Manage your account settings" / "Create a new project" / "Upload files"

Don't capitalize common UI nouns

Words like "button," "menu," "page," "dialog," "dropdown," and "tab" are common nouns—don't capitalize them. Only capitalize the name of a specific UI element when referring to it by its labeled name (for example, "open the Settings menu").

• Don't: "Select the Button at the bottom of the Page."

• Do: "Select the button at the bottom of the page."

Never use all caps for emphasis

All caps reads as shouting, reduces readability (especially for users with dyslexia), and is inaccessible to some screen readers. Use bold or a different visual treatment for emphasis. All caps is acceptable only for abbreviations (API, URL, and HTML).

• Don't: "WARNING: THIS ACTION CANNOT BE UNDONE."

• Do: "Warning: This action cannot be undone."

Capitalize specific UI element names when referencing them by label

When instructing users to interact with a named UI element—a menu, tab, or page identified by its visible label—capitalize that label to help users identify it visually. Don't capitalize the noun type ("menu," "tab," "page").

• Don't: "Go to account settings." (ambiguous—is it a page called "Account settings" or a general description?)

• Do: "Go to Account settings." (the page label is "Account settings")

Punctuation

Punctuation in UI copy serves clarity—not decoration. Most punctuation marks have a specific, limited purpose in interface writing.

Always use the serial (Oxford) comma

The comma before "and" or "or" in a series of three or more items prevents misreading.

• Don't: "Your plan includes storage, team access and priority support."

• Do: "Your plan includes storage, team access, and priority support."

Use an em dash (—) for interruptions and parenthetical asides—with no spaces

The em dash is more emphatic than a comma and less formal than parentheses. Use no spaces on either side of the em dash, and use it sparingly—one or two per paragraph at most.

• Don't: "Your file - which was too large - couldn't be uploaded." (hyphens, not em dashes)

• Do: "Your file—which exceeded the 100 MB limit—couldn't be uploaded."

Use an en dash (–) for ranges—not a hyphen

The en dash indicates a range between two values (dates, numbers, and times). It's distinct from a hyphen (used in compound words) and an em dash (used for interruption). No spaces around the en dash in ranges.

• Don't: "Active Monday - Friday" / "Pages 10-20"

• Do: "Active Monday–Friday" / "Pages 10–20"

Omit periods after standalone labels; include them in full-sentence body copy

Single-sentence UI labels (button text, form labels, navigation items, short notifications) don't need a closing period. Full sentences in body copy, help text, and error messages do—especially when there are multiple sentences.

• Don't: Button: "Save changes." / Help text: "Must be at least 8 characters" (no period in multi-sentence help text)

• Do: Button: "Save changes" / Help text: "Must be at least 8 characters. Include a number and a symbol."

Never use apostrophes for plurals of abbreviations

The plural of an abbreviation is formed by adding a lowercase s, with no apostrophe. The apostrophe indicates possession or a contraction—not plurality.

• Don't: "Export all PDF's." / "Your API's are listed below."

• Do: "Export all PDFs." / "Your APIs are listed below."

Use ampersands (&) only in space-constrained UI—not in prose

The ampersand is acceptable in tight UI contexts like navigation labels, button pairs, and tab names where space is genuinely limited. In body copy, help text, and error messages, always write "and" in full.

• Don't: "We couldn't save your changes & the page will reload."

• Do: Narrow nav item: "Privacy & Security" / Body copy: "We couldn't save your changes. The page will reload."

Numbers and dates

Consistent number and date formatting makes interfaces easier to scan and reduces cognitive load—especially in data-heavy products.

In body copy: spell out zero through nine; use numerals for 10 and above

Spelled-out numbers read more naturally in sentences; numerals are easier to spot when scanning. Exception: always use numerals before units of measurement (3 MB, 5 hours).

• Don't: "You have 3 unread messages." (in a sentence—should be spelled out)

• Do: "You have three unread messages." (body copy) / "3 unread" (UI label)

In UI elements: always use numerals

In counts, badges, labels, and short UI copy, numerals are faster to read and take less space. Use numerals in all UI contexts, regardless of the number's value.

• Don't: "Seven files selected" / "Upload up to five files"

• Do: "7 files selected" / "Upload up to 5 files"

Write dates as Month D, YYYY—no ordinals

Use the full month name (or standard abbreviation) followed by the day and year. Don't use ordinal suffixes (1st, 2nd, 3rd) in dates—they add visual noise without improving clarity.

• Don't: "March 3rd, 2026" / "3/3/26" (ambiguous across locales)

• Do: "March 3, 2026" / "Mar 3, 2026" (abbreviated) / "3 March 2026" (international audiences)

Write time in 12-hour format with AM/PM, or adapt to user locale

For English-language products, use 12-hour time with AM or PM. Include a space between the time and the AM/PM marker. For international audiences, consider 24-hour format or adapting to the user's locale setting.

• Don't: "2:30PM" (no space) / "14:30" (24-hour without locale context)

• Do: "2:30 PM" / "2:30 AM"

Use an en dash for ranges—no spaces around it

Ranges of numbers, dates, or times use an en dash (–), not a hyphen (-) or em dash (—). No spaces on either side. If the sentence already uses "from," pair it with "to" rather than a dash.

• Don't: "Valid from Jan 1 - Dec 31" / "From Monday–Friday"

• Do: "Valid Jan 1–Dec 31" / "Monday–Friday" / "From Monday to Friday"

Use symbols for currency and percentages in UI

Currency symbols and the percent sign are universally understood and take less space than their spelled-out equivalents. Use the symbol directly adjacent to the number in labels and UI copy; spell out "percent" only in formal body copy.

• Don't: "This plan costs 29 dollars per month." / "You've used 75 percent of your storage."

• Do: "$29/month" / "75% of storage used"

Abbreviations

Abbreviations save space but cost comprehension when readers don't know them. Use them strategically—and never assume familiarity.

Spell out on first use, with the abbreviation in parentheses

When introducing a term that will be abbreviated, spell it out fully on first use, followed by the abbreviation in parentheses. After that, use the abbreviation alone. Exception: abbreviations so common they need no introduction (URL, ID, PDF).

• Don't: "Use the CLI to manage your SLAs." (no introduction)

• Do: "Use the command-line interface (CLI) to manage your service-level agreements (SLAs)."

Avoid Latin abbreviations—use plain English equivalents

Latin abbreviations like e.g. (for example), i.e. (that is), and etc. (and so on) are unfamiliar to many users and invisible to screen readers. Replace them with their English equivalents.

• Don't: "Supported formats (e.g., PDF, PNG)" / "This setting, i.e., auto-save, is on by default."

• Do: "Supported formats (for example, PDF or PNG)" / "This setting—auto-save—is on by default."

Pluralize abbreviations with a lowercase s—no apostrophe

Adding an apostrophe before the s implies possession, not plurality. The plural of an abbreviation is the abbreviation plus a lowercase s.

• Don't: "Your API's" / "Export PDF's" / "Two CEO's approved the plan."

• Do: "Your APIs" / "Export PDFs" / "Two CEOs approved the plan."

Abbreviate units of measurement when they follow a numeral

Standard units of measurement (MB, GB, ms, hrs, and km) are acceptable abbreviations in UI when they follow a numeral. Include a space between the numeral and the unit. Spell out the unit in body copy when no numeral precedes it.

• Don't: "500megabytes used" / "Upload takes 250 milliseconds" / "10GB limit"

• Do: "500 MB used" / "Upload takes 250 ms" / "10 GB limit"

Don't begin a sentence with an abbreviation

Starting a sentence with an abbreviation—even a well-known one—can create a jarring read. Either restructure the sentence so the abbreviation falls mid-sentence, or spell out the term at the start.

• Don't: "PDFs can be uploaded in the Documents section." / "APIs must be authenticated."

• Do: "Upload PDFs in the Documents section." / "All APIs must be authenticated."