# Writing

> Not written to be read. Written to be acted on.

People don't come to your product to read. They come to look up a record, find the right tool, or complete admin tasks. The words along the way exist to move that task forward, not to decorate. Every extra word slows people down, so weigh each one.

Interface text is the product's microcopy: words and phrases tied directly to a user's actions. Button labels, tooltips, help text, and error messages. Everything a user reads while working.

That job separates interface text from our other writing. Informational content explains how the product works; marketing promotes it; interface text gets the task done with as little reading as possible. So we write in a straightforward, conversational tone, and put clarity and usability ahead of expressive language.

For specific guidance, go deeper with [Grammar and mechanics](/standards/grammar-mechanics), [Voice and tone](/standards/voice-tone), and [Components and text patterns](/standards/text-patterns).

<!-- dx-sync:uitext-sequence — steps 1-5 map 1:1 to the copy skill's draft-phase sequence; sections 6-11 are the skill's collapsed "Check" step (human-reviewed, not parity-checked) -->
## 1. Clarify the context, then draft

Interface text exists to help a user complete a task. Before writing, clarify three things: the user, their goal, and what the product needs the text to do. For an error message, the user's goal is to understand what went wrong; the product's goal is to help them recover quickly.

Then write your first draft. Write what you want to say to the user; you polish it later.

Example:

`You have entered an incorrect postal code.`

## 2. Edit to be purposeful

Every word on the screen should serve the user's goal and the product's. Edit the first draft to ensure it meets all goals.

When there is more than one goal to convey in your writing, order them effectively:

- **Begin with your most important goal.** The first idea is scanned first and is the
  second most memorable goal (primacy effect). This should signal to the users that
  they have found the idea they are seeking.
- **Follow up with any other goals, in order of importance.** Arrange them logically
  and coherently so that users can easily follow along.
- **End with the goal that informs the next step.** The last idea is the most
  memorable (recency effect) and impacts the user's action.

Before:

`You have entered an incorrect postal code.`

Help users recover:

`You have entered an incorrect postal code. Please enter a valid postal code e.g. 123456.`

## 3. Edit to be concise

Users come to the interface to complete a task. They scan for the smallest amount of text that helps them understand and act. Write concisely so they can process information quickly and continue their work.

- **Copy should lead with its purpose.** Start with what it does for the user and
  when to use it before explaining how. A user should understand why something
  exists from the start. Front load essential information, such as the user's
  goal, benefit, or action to take ([CNT-7](/standards/catalog/cnt-7)).
- **Use short sentences or phrases.** Keep sentences to 25 words or fewer
  ([CNT-3](/standards/catalog/cnt-3)).
- **Try different arrangements.** Rewrite the same message in a few ways and keep the
  clearest concise option.
- **Remove low value words.** Do this only when clarity and readability stay intact
  ([CNT-6](/standards/catalog/cnt-6)):
  - Empty openers (for example, `There is`, `There are`, `It is`, `This is`, and `In order to`)
  - Filler words (for example, `such`, `just`, `that`, `really`, `very`, and `please`)
  - Articles and conjunctions (for example, `a`, `the`, and `and`)
- **Check for low value words introduced by AI.** Look for buzzwords, filler phrases,
  negative parallelism, copula avoidance, and forced triads
  ([SLP-9](/standards/catalog/slp-9)).

Before:

`You have entered an incorrect postal code. Please enter a valid postal code e.g. 123456.`

Remove words with low informational value:

`Incorrect postal code. Enter valid postal code e.g. 123456.`

## 4. Edit to be conversational

Conciseness can leave copy sounding abrupt or robotic. Interface text is a conversation between the product and the user. Messages, instructions, descriptions, and errors should sound like the product is speaking. Labels, buttons, dropdown options, and inputs should sound like the user is responding.

- **Read it aloud.** It should sound like a natural conversation.
- **Speak directly to the user.** Use second person ("you", "your", "you're") and active voice ([CNT-3](/standards/catalog/cnt-3), voice and person).
- **Replace a passive "to be" verb with a plainer action verb** ([CNT-8](/standards/catalog/cnt-8)). "is a requirement" becomes "you are required to", then "you must". When you bury the action in a noun, you usually drag a "to be" verb (is, are, was, were, will be) along with it. Watch for these endings:

| Look for | For example | Use the verb |
| --- | --- | --- |
| -al | denial | deny |
| -ance | maintenance | maintain, keep |
| -ence | concurrence | concur, agree |
| -ment | assignment | assign |
| -sion | transmission | transmit, send |
| -tion | recommendation | recommend |
| -ure | failure | fail |

Before:

`Enter a valid postal code e.g. 123456.`

Make it conversational:

`That doesn't look like the right postal code. Please enter a valid postal code e.g. 123456.`

## 5. Edit to be clear

Clarity takes precedence over everything. Clear writing helps users process info more quickly. It removes uncertainty and builds trust. After one read, a user should know two things: what it means, and what the next step is.

- **Convey information in a logical progression.** Provide critical context,
  explanations, and connecting transitions to guide the reader through the ideas
  without significant leaps in understanding.
- **Use one idea per sentence.** Keep each sentence focused
  ([CNT-9](/standards/catalog/cnt-9)).
- **Use simple present tense where possible.** Simple present is easier to
  understand, more direct, uses fewer words, and is easier to scan. For example, "Application submitted"
  instead of "Application has been submitted." ([CNT-9](/standards/catalog/cnt-9))
- **Avoid double negatives.** For example, "I want to receive reminders" instead of
  "I *do not* want to *opt out* of reminders." ([CNT-9](/standards/catalog/cnt-9))
- **Avoid noun stacks.** Several nouns in a row make meaning harder to scan. Use
  verbs for actions, or adjectives to describe the main noun. For example, write
  "Review support cases" instead of "Support case review."
  ([CNT-9](/standards/catalog/cnt-9))
- **Avoid idioms and cultural references.** "The builder never reviews its own
  work", not "the builder never marks its own homework". Plain function words
  work for non-native readers and translate without losing meaning.
- **Use short and simple words** ([CNT-9](/standards/catalog/cnt-9)):

| Instead of | Write | Instead of | Write |
| --- | --- | --- | --- |
| attempt | try | required | need |
| inquire | ask | prior to | before |
| initiate | begin | subsequent | next |
| terminate | end | utilise | use |
| obtain | get | purchase | buy |

- **Do a quick exposure test.** Show someone the screen for five seconds and ask the two
  questions above. This tests people's understanding when they scan-read. It
  mimics users' real-life habits and identifies any memorable parts of the text.

Before:

`That doesn't look like the right postal code. Please enter a valid postal code e.g. 123456.`

Making it clear:

`Enter a valid 6-digit postal code, for example 123456.`

The copy is edited. The remaining passes are checks. Run them before the text ships.

<!-- /dx-sync:uitext-sequence -->
## 6. Check consistency

One term per thing, everywhere. Switching terms makes people pause and wonder if the words mean different things.

- **Check for internal consistency.** Review the interface for term drift, where the same
  action, object, or state is named two ways anywhere it appears, from nav and buttons to
  filters, messages, and help text ([CNT-10](/standards/catalog/cnt-10)).
- **Check for external consistency.** Use familiar terms people already see across
  other products. Established terms are easier to recognise and navigate. For example,
  use "Search", not "Find", for a search field
  ([CNT-11](/standards/catalog/cnt-11)).

## 7. Check readability

Readable text is easy to scan and understand at a glance.

- **Use sentence case.** Capitalise the first word and proper nouns or branded terms
  only. Sentence case has proven easier for users to read and comprehend, sounds more
  friendly, and helps differentiate the proper nouns and branded terms that need
  capitalisation ([CNT-12](/standards/catalog/cnt-12)).
- **Write short sentences ([CNT-3](/standards/catalog/cnt-3)), one idea each
  ([CNT-9](/standards/catalog/cnt-9)).**
- **Keep line length comfortable.** Avoid lines that are too long or too short. Ideally,
  40 to 60 characters per line ([TYP-6](/standards/catalog/typ-6)).
- **Use plain language.** Choose common words, and give every acronym or technical term a
  reachable definition. Expand it inline, or put it one tooltip, help link, or glossary
  entry away ([CNT-9](/standards/catalog/cnt-9)). Prefer clear function over clever
  phrasing, and keep feature and page names plain too
  ([CNT-2](/standards/catalog/cnt-2)).

## 8. Check legibility

Legibility is visual. It helps people see and recognise text clearly. If the text is hard to see, fix the visual treatment before changing the words.

- **Left-align text.** Left-aligned text is easier to read in left-to-right languages, such as English.
  Use centred text only for short text, such as pull quotes. Avoid it for long text.
- **Use a minimum font size of 14px for body text.** A font size smaller than 14px may
  be required for small text and captions, but use them sparingly
  ([TYP-2](/standards/catalog/typ-2)).
- **Ensure adequate contrast between text and background**
  ([A11Y-1](/standards/catalog/a11y-1)).

## 9. Check accessibility

Accessible text works for people with motor, vision, or hearing impairments, and reads better for everyone else too.

- **Write chronologically, not spatially or visually.** Screen readers parse top to
  bottom, so avoid position words (for example, "above" and "below") and colour
  references (for example, "the blue button").
- **Place important text before the control.** For example, above buttons or beside
  field labels. Text placed after a button is announced after it, too late to inform
  the decision.
- **Write meaningful text for links and other CTAs.** Avoid ambiguous links
  (for example, `Click here` and `Read more`), as they create uncertainty. Screen reader
  users need context when navigating links and CTAs
  ([CNT-5](/standards/catalog/cnt-5), [A11Y-7](/standards/catalog/a11y-7)).
- **Describe the action, not the behaviour.** Use device-agnostic words that describe
  the action, whatever the interface (for example, `choose`, `select`, and `view`).
  Avoid behavioural actions (for example, `click`, `tap`, `press`, and `see`)
  ([CNT-5](/standards/catalog/cnt-5)).
- **Provide enough time to read and use the content.** Some content, like toasts and
  tooltips, is only shown briefly, so make sure it stays visible long enough for
  people to read before it disappears.
- **Write informative and unique page titles.** For pages with a multi-step process,
  include the current step in the page title ([A11Y-9](/standards/catalog/a11y-9)).

## 10. Check for grammar and spelling

Editing for conciseness may eliminate words with low informational value, such as empty openers ('There is') and unnecessary articles ('a,' 'the,' 'and'). This tradeoff is fine.

For interface text, users focus on completing tasks efficiently, so clarity and scannability outrank strict grammar. The final text must still be clear and easy to read, so proofread it before use.

Spelling errors break trust faster than style slips, so check it. Use British English spelling: organise, colour, centre ([CNT-13](/standards/catalog/cnt-13)).

## 11. Check voice and tone

All text in your product should follow the shared voice and tone. Your product should sound clear, thoughtful, and approachable. Tone should adapt to the moment, so you can respond with empathy.

See [Voice and tone](/standards/voice-tone) for more details ([CNT-14](/standards/catalog/cnt-14)).

## Related

### Agent skill

- `/dx-harness:dx-design-copy`: Reviews and proposes user-facing text: naming, error anatomy, and tone, with the anti-AI-writing rules applied.

[All skills](/harness/skills)

### In the catalogue

- [CNT-1](/standards/catalog/cnt-1) (L1): Error messages state what happened and what to do next; no raw error codes as the primary message
- [CNT-2](/standards/catalog/cnt-2) (L1): Feature and page names use plain language; no invented portmanteaus, no internal codenames in UI
- [CNT-3](/standards/catalog/cnt-3) (L2): Copy uses second person and active voice, and keeps sentences to 25 words or fewer
- [CNT-4](/standards/catalog/cnt-4) (L2): Content that models a real-world artifact is faithful to it (scope, terminology, structure) or explicitly labelled illustrative
- [CNT-5](/standards/catalog/cnt-5) (L2): UI action words name the action, not the input device — "choose", "select", "view", never "click", "tap", "swipe", or "press"
- [CNT-6](/standards/catalog/cnt-6) (L2): Copy carries no low-informational-value words — no empty openers, filler words, or droppable articles and conjunctions, unless removing them hurts clarity
- [CNT-7](/standards/catalog/cnt-7) (L2): Descriptive copy leads with its purpose — what it does for the user and when to reach for it — before the mechanism
- [CNT-8](/standards/catalog/cnt-8) (L2): Copy replaces nominalised verbs and "to be" constructions with plain action verbs
- [CNT-9](/standards/catalog/cnt-9) (L2): Copy is clear — one idea per sentence, simple present tense, no double negatives, no noun stacks, short words, acronyms and technical terms have a reachable definition
- [CNT-10](/standards/catalog/cnt-10) (L1): One term per thing within a product — the same action, object, or state keeps a single name everywhere it appears in the interface
- [CNT-11](/standards/catalog/cnt-11) (L2): UI terms match the established word users already meet across other products — "Search" not "Find", "Settings" not "Preferences"
- [CNT-12](/standards/catalog/cnt-12) (L2): Copy uses sentence case — capitalise the first word and proper or branded nouns only
- [CNT-13](/standards/catalog/cnt-13) (L2): Copy is free of spelling and proofreading errors and uses British English spelling
- [CNT-14](/standards/catalog/cnt-14) (L2): Copy embodies the DX voice (Clear, Thoughtful, Approachable) and its tone fits the surface context
- [SLP-9](/standards/catalog/slp-9) (L2): Copy carries no AI-writing tells — marketing buzzwords, em-dash chains, filler, or redundant label/helper pairs
- [IDN-3](/standards/catalog/idn-3) (L2): Copy on a product's surface carries that product's calibrated tone register — same voice character, calibrated weight, never a switched voice system