writing-for-interfaces

What this skill does

# Writing for Interfaces

Good interface writing is invisible. When words work seamlessly with design, people don't
notice them.

Writing should be part of the design process from the start, not something filled in at the
end. When words are considered alongside layout, interaction, and visual design, the result
feels seamless. When they're an afterthought, product experiences feel stitched together.

Every piece of text in an interface is a small act of communication: it should respect the
person's time, meet them where they are, and help them move forward.

---

## When triggered

### Step 1: Establish voice and personality

Voice is the foundation. All copy decisions — what to say, how to say it, what to leave
out — flow from a clear understanding of who this product is, who it's for, and how it
should sound. Without a defined voice, copy becomes inconsistent and the product loses coherency.

**Search for an existing voice definition.** Check for:

- A `CLAUDE.md`, `AGENTS.md`, or similar project config that defines voice and/or tone
- A style guide, design system documentation, or brand guidelines
- A word list or terminology reference

**If a voice definition exists**, use it as the lens for all copy work. If the copy you're
working on drifts from it, flag the inconsistency.

**If no voice definition exists**, infer the current voice from existing copy. Look for
patterns: formal or casual? Technical or plain? Warm or matter-of-fact? If the copy is
inconsistent or insufficient to infer from, help the user establish a voice before writing.

#### Establishing voice through conversation

Walk the user through these questions:

1. **What does the product do and who is it for?** A banking app for professionals and a
   savings app for kids serve similar purposes but should sound completely different. The
   audience determines vocabulary, complexity, and register.

2. **Why do people use it, and where?** Someone using a health app during a crisis needs
   calm clarity. Someone browsing a game at home can handle playfulness. The context of use
   — physical environment, emotional state, competing attention — shapes how much text
   people can absorb and what tone is appropriate.

3. **Imagine the product as a person. What 3–4 personality traits make them unique?**
   Brainstorm freely, group similar words into themes, discard table-stakes traits ("not
   confusing"), and keep the ones that genuinely differentiate the product's personality.

4. **Look for productive tensions.** The best voice definitions have qualities that push
   against each other. "Friendly" and "concise" create a useful tension — these become the
   dials you turn when adjusting tone for different situations.

5. **Capture it.** Suggest the user persist the voice definition somewhere durable
   (`AGENTS.md`, `CLAUDE.md` or style guide document) so it persists across sessions. A word list pairs well with this and should be stored in the same file.

### Step 2: Evaluate the request

Identify what kind of copy work is needed:

- **New copy**: Writing from scratch for a screen, flow, or component.
- **Review**: Evaluating existing copy for clarity, consistency, and tone.
- **Rewrite**: Improving specific text that isn't working.
- **Terminology**: Building or maintaining a word list.

Then identify which interface patterns are involved
and consult `references/patterns.md` for the relevant sections.

### Step 3: Apply voice, then principles

For every piece of copy, work in this order:

1. **Does it sound like the voice?** Read it against the 3–4 qualities. If you read it
   aloud, would you recognise it as coming from this product?
2. **Which qualities need dialing up or down for this situation?** Think of each voice
   quality as a dial. A celebratory moment turns up warmth; an error turns up clarity and
   dials back friendliness.
3. **Apply the core principles** (purpose, anticipation, context, empathy — detailed below).
4. **Apply the craft rules** (remove filler, avoid repetition, be specific — detailed below).

The ordering is deliberate and encodes a precedence chain: **clarity > voice > craft
rules.** Clarity always wins — if voice gets in the way of someone understanding what to
do, strip it back. Voice comes next — it shapes how things sound, and a craft rule should
never cut a word or restructure a phrase in a way that undermines the established voice.
Craft rules are voice-filtered heuristics, not absolutes. Always cross-check craft edits
against the voice before committing them.

### Step 4: Deliver changes

Work through the copy element by element — title, body, buttons, labels — showing the
original, then the rewrite, with a brief rationale tied to voice and principles. Prioritise
changes that confuse or block users before polish. When reviewing across a flow, flag
terminology inconsistencies and suggest word list entries at the end.

---

## Voice and tone

### Voice vs. tone

**Voice** is the consistent personality of the product — the 3–4 qualities that define how
it always sounds. These don't change.

**Tone** is how the voice adapts to the situation. Think of each voice quality as a dial you
can turn up or down depending on the moment:

- Celebrating a milestone? Turn up warmth, dial back brevity.
- Reporting an error? Turn up clarity and helpfulness, dial back friendliness.
- Onboarding a new user? Balance helpfulness with warmth.
- Confirming a destructive action? Turn up directness, keep calm and concise.

### Applying tone in practice

For each situation, decide which voice qualities need emphasis and which should recede.

**Example**: For an error where someone can't connect to the network, clarity and
helpfulness go way up. Simplicity stays moderate because they need the most important
details. Friendliness dials back because getting them unstuck matters more than sounding
warm.

### Where personality belongs

Personality shines in moments where there's room for it — welcome screens, milestones,
empty states. In error messages, destructive actions, and critical flows, dial voice back
and let clarity lead. The precedence chain from Step 3 applies: clarity first, always.

---

## Core principles

Purpose, Anticipation, Context, Empathy — a framework for what to write, how to write it,
and when. Apply through the lens of your voice.

### 1. Purpose

Before writing, answer: **what is the single most important thing the person needs to know
right now?**

- **Use information hierarchy.** Headlines and buttons carry the primary message; supporting
  text fills in detail. If someone reads only headers and buttons, they should understand
  the situation.
- **Cut what doesn't serve this moment.** Move it elsewhere or remove it. When a screen
  tries to do too much, return to its purpose and strip away everything else.
- **Tell people the purpose.** When introducing a feature, tell them why it exists and why
  it matters to them.

### 2. Anticipation

Think of the interface as a conversation. In any good conversation there's a natural back
and forth — listening, responding, anticipating what the other person needs to hear next.

- After telling someone about a problem, tell them how to fix it. "Can't connect to
  Wi-Fi" → "Can't connect to Wi-Fi. Check your connection and try again."
- After asking someone to do something, make it obvious how to do it. "Verify your
  identity" → "Verify your identity" with a clear button or link to start the process.
- After someone completes something, acknowledge it and point forward. "Password changed"
  → "Password changed. You can now sign in with your new password."
- **Lead with the "why".** Put the benefit or reason before the instruction: "To [benefit],
  [instruction]." Front-loading motivation makes the instruction feel like a reasonable ask
  instead of a demand.

### 3. Context

People use products in wildly different circumstances. The usage context shapes the writing.

- **Think outside the app.** Consider the physical