Content guidelines in a design system
Learn

Content guidelines in a design system

Author Avatar
Written by
Aug 21, 2026

Most design systems don't have content guidelines. The system covers buttons, inputs, modals, spacing, colors, and tokens, but the words inside those components are nobody's responsibility. The result is the kind of product where every team writes its own error messages, every button label sounds slightly different, and the system's "consistent visual language" coexists with a wildly inconsistent voice.

Content is the most visible part of a product. Users read the words long before they notice the alignment of the underlying components. The inconsistencies in voice and copy show up faster, and they're harder to defend, than any visual inconsistency the rest of the design system is built to prevent.

This article is about treating content as a first-class part of the design system rather than as an afterthought. It covers what content guidelines actually contain, where they sit in the documentation, how to write them so they shift behavior rather than gather dust, and how to start from nothing.

What content guidelines are

A content guideline is documentation for the words inside your product. It's the rule that says "use 'sign in,' not 'log in.'" It's the example showing the difference between an empty state that helps the user and one that just announces a page is empty. And it's the principle that explains why your tone shifts between an error message and a marketing banner.

Content guidelines sit alongside the visual layer of a design system. The same principle (one source of truth, consistent across the product, documented in a place teams reach for) applies. The difference is that content guidelines govern what gets written, not what gets drawn.

A few things content guidelines aren't.

They aren't a brand voice document. A brand voice document describes how the company speaks at the marketing level: in ads, on the homepage, in social copy. Content guidelines for a design system are narrower. They focus on the product surfaces: button labels, error messages, empty states, tooltips, system feedback.

They aren't an editorial style guide for long-form content. Articles, blog posts, and documentation pages need their own style rules, but those rules don't have to live in the design system. Design system content guidelines are about the high-volume, low-word-count copy that flows through your product hundreds of times a day.

They aren't a stand-in for a content designer. A content designer can make decisions content guidelines can't anticipate. Guidelines reduce the volume of decisions a content designer has to make from scratch. They don't replace the judgment.

The scope of a content section

A content section in design system documentation usually covers five layers.

Voice and tone come first: what the product sounds like across contexts. Voice is constant. Tone shifts depending on whether the user is reading a confirmation, an error, a celebration, or a routine system message.

Grammar and punctuation cover the conventions for sentence case vs title case, oxford commas, contractions, capitalization of system terms, and how to format numbers and dates.

Inclusive language gives specific guidance on terms to use and avoid: gender-neutral pronouns, ability-first language, and the words your product chooses around identity, money, family, and other sensitive areas.

UI copy patterns cover the high-volume copy that flows through products: button labels, error messages, empty states, tooltips, success confirmations, microcopy. Each pattern gets a short rule and a few examples.

Terminology is the canonical names for things in your product. If your product calls an organization a "workspace" or a customer a "client," the content section is where those terms get locked in.

A content section that covers those five layers does most of the work. Sections that go further (long-form editorial style, marketing voice, regulatory disclaimers) are usually better off in a separate brand or editorial guide that links back to the content section.

Writing for the high-volume contexts

The copy patterns that appear most often in a product are the ones where consistency matters most, and the ones most teams have the least guidance on.

Button labels

Use action verbs, not nouns. "Save" beats "Save changes" in most contexts. "Sign in" is one decision; "Log in" is another; pick one and stop the rest of the team from quietly using both. Three to four words is the soft ceiling. If the label needs more, the action probably needs to be reconsidered.

Error messages

Tell the user what went wrong, why, and what to do next. "Something went wrong" is not an error message; it's an apology. "We couldn't save your changes because the network dropped. Try again" is closer to useful. Avoid blaming the user. Avoid technical detail the user can't act on. And avoid sounding like a server log; error messages are read by humans.

Empty states

An empty state is an opportunity, not a failure. Empty states should explain what would normally appear here, why it's empty right now, and what the user can do about it. A blank inbox shouldn't just say "No messages." It should say "No messages yet. Invite a teammate to start a conversation."

Tooltips

Tooltips should explain a control, not duplicate it. If your button is labeled "Export," the tooltip shouldn't say "Click to export." It should say what export does, when to use it, or what the user gets afterward. Tooltips that restate the obvious are a sign the control's label needs more work.

Success messages

Confirm the action and stop. "Saved." "Sent." "Done." The temptation to celebrate ("Awesome! You're all set!") wears thin after the third repetition. Match the tone to the weight of the action.

Microcopy

The very small pieces of text. Placeholder text, help text, character counters, confirmation prompts. Microcopy benefits from being read out loud: the version that sounds like a person speaking is almost always better than the version that reads like a software string.

Each of these patterns should have a rule and at least two examples in the content section: a recommended version and a version that breaks the rule. Worked examples shift behavior. Principles alone tend to gather dust.

Voice and tone: the distinction that gets confused

Voice is who you are. Tone is how you're talking right now.

A product can have a single voice (friendly, direct, practical) and use different tones in different contexts: encouraging in onboarding, apologetic in an error, neutral in routine feedback. Most content guidelines that fail describe voice exhaustively and ignore tone entirely. The result is a single tone applied everywhere, which makes celebrations feel hollow and errors feel flippant.

The most useful framing comes from Mailchimp's voice and tone guide, which gives an explicit voice description and then walks through tone variations for the contexts the product uses most often. The tone-by-context approach turns content guidelines into a working tool rather than a values statement.

Document your voice in a paragraph or two with three to five short example phrases. Then document tone variations for the specific contexts in your product where the tone needs to shift: error messages, celebration messages, system status, marketing banners, support copy.

Inclusive language

Inclusive language belongs in content guidelines, but it has to be specific to do any work.

A statement like "we use inclusive language" is a values statement, not a guideline. The version that shifts behavior names the cases. Use "they" as a singular pronoun by default. Use "team" instead of "guys." Use "primary/replica" instead of older database terminology. Specify how the product talks about disability, gender, currency, geography, and age. Where the language has changed industry-wide in the last few years, name the change and the reason.

The content section should also document the cases where the team has made a deliberate choice: a term that some teams use but yours doesn't, a phrasing your product avoids for a specific reason. Guidelines that explain the why hold up when a new contributor pushes back.

How content guidelines relate to component documentation

Content guidelines and component documentation overlap in a specific place: the copy that lives inside a component.

A button page documents the button. The content guidelines document the rules for what gets written on the button. The two have to agree, and they have to cross-reference each other clearly.

The pattern that works is to keep general rules in the content section and specific rules on the component page. The content section says "button labels use action verbs in sentence case, three to four words maximum." The component page says "use a primary button for the main action; the label follows the button label rules in the content section," and links across.

The same pattern applies to error messages (component documentation for inline validation links to the content section's error message rules), empty states (a data table component page links to the empty state rules), and tooltips. Cross-linking makes both sections shorter and harder to drift out of sync. When the rule lives in two places, it'll change in one and not the other.

There's also the question of whether component-level copy gets hardcoded or kept editable. Dan Donald argues in a thoughtful piece on content and design systems that hardcoded copy is a locked-in content decision that can't be revisited easily. For high-volume copy that shouldn't vary, hardcoding is fine. For copy the content team needs to revise without engineering involvement, treat it like content, not like part of the component.

How to start with nothing

If your design system has no content guidelines, the work isn't to write the perfect document. It's to start where the inconsistencies are most visible and expand from there.

A useful first step is an audit. Take screenshots of every button label, error message, and empty state in your product. Lay them out side by side. The patterns that look obviously inconsistent (three different verbs for "delete," a "Cancel" and a "cancel" within the same flow, error messages that range from a sentence fragment to a paragraph) are the first things to standardize.

Next, write a one-page content section covering five things: a paragraph on voice, a short list of button label rules, a short list of error message rules, a short list of empty state rules, and a glossary of canonical product terms. Five short sections beat one exhaustive content guide that takes six months to write.

After that, expand based on the patterns that come up. When a question gets asked twice ("how do we phrase confirmations that don't need a celebration?"), turn the answer into a rule and add it to the content section. The section grows by addressing real questions, not by trying to anticipate every possible decision.

The companion blog post Top 5 design systems with content design guidelines is a useful reference for what mature content sections look like in the wild.

Where to go next

Content guidelines work best when they're cross-linked into the rest of the documentation. The articles closest to this one in the guide:

Article 03 (How to document a design system component) covers the structure of a component page, including where component-specific copy rules live and how to link them back to the content section.

Article 04 (The key sections of a design system) covers where the content section sits alongside foundations, components, and patterns.

Article 13 (Keeping your design system documentation up to date) covers maintenance. Content guidelines drift faster than most other documentation because the team's voice evolves, and the article covers how to catch the drift before it becomes visible in the product.

Author Avatar
Try zeroheight
The design systems platform that keeps teams and agents in sync
Start for free
Share this post