01
Routine
Be compact. Labels and actions should feel almost invisible.
Guideline 04Operational
Content design
Voice, interface language, formatting, localization, and accessible naming rules for product content.
- Owner
- Product Design and Content
- Last reviewed
- August 2026
- Review cadence
- Twice yearly and with locale expansion
- Source of truth
- DESIGN-SYSTEM.md content guidelines
Required outcomes
01
People understand the next action without interpreting system jargon.
02
Errors explain the problem, consequence, and recovery.
03
Layouts survive translation, bidirectional text, and user-generated content.
01
Voice and tone
The voice is direct, calm, specific, and human. Tone adjusts to consequence without changing personality.
Voice dimensions
| Prefer | Avoid | Example |
|---|---|---|
| Specific | Vague | “Export failed because the file is read-only.” |
| Direct | Ceremonial | “Save changes” instead of “Proceed with saving.” |
| Calm | Alarmist | “Connection lost. Your draft is saved locally.” |
| Human | Cute or robotic | “We could not verify that address.” |
Tone by moment
02
Learning
Explain the concept and next step without front-loading every exception.
03
Blocked
State what happened, whether work is safe, and the most useful recovery.
04
High risk
Slow the interaction down. Name the affected object, consequence, and permanence.
02
Interface copy
Labels describe objects. Actions begin with verbs. Supporting text earns its space.
Copy patterns
| Element | Pattern | Example |
|---|---|---|
| Button | Verb + object when context is not obvious | Create project |
| Field label | Stable noun phrase | Billing address |
| Helper text | Format, consequence, or reason | Used only for account recovery. |
| Validation | Problem + correction | Enter an email address in name@example.com format. |
| Dialog title | Decision or consequence | Delete “Quarterly plan”? |
| Empty state | Situation + value + next action | No saved views yet. Save this filter to reuse it. |
| Success | Completed result | Project created |
Copy acceptance
Every string
- Uses sentence case.
- Avoids unnecessary punctuation.
- Does not repeat adjacent headings or labels.
- Makes sense when read by a screen reader out of visual context.
Errors
- Names the failed object or action.
- Avoids blame.
- Preserves useful technical detail behind disclosure.
- Offers a recovery when one exists.
03
Numbers, dates, names, and truncation
Locale-aware formatting is part of the content contract, not post-production cleanup.
Formatting rules
| Content | Display rule | Implementation |
|---|---|---|
| Dates | Use unambiguous localized forms. Include year when context can cross years. | Intl.DateTimeFormat |
| Times | Use the user locale and show the time zone when participants differ. | Intl.DateTimeFormat with timeZoneName |
| Numbers | Respect grouping and decimal conventions. Keep raw precision only where meaningful. | Intl.NumberFormat |
| Currency | Always bind amount to ISO currency. Never infer from symbol alone. | Intl.NumberFormat with currency |
| Names | Store and display as entered. Do not require first/last assumptions. | One full-name field unless domain needs parts |
| File size | Use consistent decimal or binary units within a product. | Shared formatter |
| Truncation | Preserve distinguishing start and end where useful. Reveal the full value. | CSS ellipsis plus accessible full text |
04
Localization and bidirectionality
Components expand, mirror, and reflow without asking translators to fit English-shaped boxes.
Localization stress cases
Translation
- Test 30 to 50 percent text expansion.
- Do not concatenate sentence fragments.
- Keep variables contextually named for translators.
- Use plural rules rather than count-based string branches.
RTL
- Use logical start and end properties.
- Mirror directional icons, not universal symbols.
- Keep numbers, code, and media direction intentional.
- Verify focus and reading order independently of visual mirroring.
User content
- Support mixed scripts and bidirectional isolation.
- Define wrapping for long unbroken strings.
- Do not communicate status through capitalization.
- Keep accessible names in the user language.