DEV Community

Cover image for Product UI Tone & Clarity Guidelines
Tanya Donska
Tanya Donska

Posted on

Product UI Tone & Clarity Guidelines

Purpose
Set a clear, repeatable standard for interface language that builds trust and speeds decisions. These guidelines replace vague, overly polite copy with factual, outcome‑oriented language.

Scope
Applies to all in‑product text: labels, buttons, messages, empty states, error and waiting states, forms, settings, and destructive actions. Covers web and mobile. Marketing site copy is out of scope unless it appears inside the product shell.

Guiding Principles

1.  Clarity over friendliness – Kindness is welcome; vagueness is not.
2.  Facts first – State what happened or will happen, then add context.
3.  Name the object – Use precise nouns (workspace, invoice, report), not this/it.
4.  One action, one escape – Present a primary next step and a safe cancel/close.
5.  Truthful time and risk – No optimistic time claims or euphemisms for destructive actions.
6.  Consistency – Use the same terms for the same things everywhere.
Enter fullscreen mode Exit fullscreen mode

Language Standards

Tone
Neutral‑confident by default. Warm for success/guidance. Firm for money, permissions, security, outages, and deletion.

Voice
• Active voice, present tense.
• Second person sparingly (you/your) when it reduces ambiguity.
• Sentence length target ≤ 14 words.

Format
• Dates: 12 June 2025.
• Times: 24‑hour clock (e.g., 09:00–18:00).
• Numerals: use digits for 2+; words for one where natural.
• Use sentence case for UI text unless a component demands otherwise.

Banned / Discouraged Hedges
might, maybe, looks like, a bit, usually, just, probably, hopefully, just a sec, almost there, feel free, something’s not quite right.

Preferred Constructions
• We couldn’t save… (what failed)
• Still processing (10–20s). You can… (truthful wait)
• Delete workspace now? This removes… (explicit risk)
• Connect data → See your cost breakdown (outcome‑first CTA)

Pattern Library

Error

Rule: Say what failed; why (if known); what to do next.
Template:

. . or .

Example: Export failed. The file is too large. Try a smaller range or email support.

Destructive Action

Rule: Name the action, consequence, and undo policy. Provide clear primary and cancel.
Template:

now? . . |

Example: Delete workspace now? This removes all members. You can restore within 7 days. Delete | Cancel.

Waiting State

Rule: State status, truthful timeframe, and what the user can do.
Template:

in progress (). .

Example: Preparing your report (10–20s). You can close this tab; we’ll notify you.

Empty State

Rule: Explain purpose, why it matters, one next action.
Template:

. . .

Example: Cohorts compare behaviour over time to find growth drivers. Create your first cohort.

CTA (Buttons & Links)

Rule: Express outcomes, not tasks. Avoid cheerleading.
Formula: Do X → Get Y.
Examples: Connect Stripe → See MRR · Generate report → View results.

Anti‑Patterns (do not ship)

• Hedged errors: “Oops! Something might’ve gone wrong.”
Enter fullscreen mode Exit fullscreen mode

Use: We couldn’t save your changes. Try again or reload.
• Time lies: “Just a sec…” shown for > 5s.
Use: Training model (3–5 min). We’ll email you when it’s ready.
• Motivational CTAs: “Let’s go!” for destructive actions.
Use: Delete account.
• Vague warnings: “You’ll lose some data.”
Use: Cancelling now removes access to historical reports.
• Unnamed objects: “Click here to continue when you’re ready.”
Use: Continue – your settings save on the next step.

Naming & Navigation

• Each top‑level nav item must be explainable in ≤ 2 sentences.
• Prefer user language over internal terminology.
• Align in‑product section names with the website’s value proposition where appropriate.
Enter fullscreen mode Exit fullscreen mode

Review & Governance

Tone Guardrail (one‑pager)
• List banned hedges and danger words.
• Time claims policy (ranges, thresholds for spinners vs. progress bars).
• Destructive actions wording standards (risk + undo window).

Copy PR
Every UI change with text includes:
• Before and After copy.
• Rationale linked to these guidelines.
• Owner sign‑off (Product) and, where needed, Legal/Compliance.

Ownership Table
Screen/component → Job‑to‑be‑done → Copy owner → Last updated.

Accessibility & Inclusion
• Avoid idioms and cultural references.
• Write for screen readers: meaningful labels, announce state changes.
• Keep reading level clear; prefer common words over jargon.
• Ensure error messages can be perceived and recovered from without colour alone.

Measurement

Track for two weeks after notable copy changes:
• Task success: completion rate/time on top flows.
• Error recovery: % of users who retry and succeed.
• Support load: tickets per 1,000 users on affected surfaces.
• Conversion: CTA CTR; paywall completion.
• Activation: % reaching first value within 24 hours.

Success criteria: directional improvement on ≥ 3 metrics, or a strong lift on one priority metric.

Change Control & Versioning
• Version these guidelines quarterly or when product scope shifts.
• Archive deprecated patterns; replace examples across the design system.

Quick Checklist (pin this in Figma)
• Facts before feelings
• Named objects, not this/it
• One action, one escape
• True time, true risk
• Decision‑adjacent proof when confidence matters
• Firm tone for money/permissions/deletion/outages
• Copy PR attached and owner signed off

Top comments (0)