writing-for-interfaces

Files (3)

• SKILL.md
• patterns.md · references/
• sources.md · references/

SKILL.md (first lines)

# 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

From ducko-im/ducko, MIT.

More from ducko-im/ducko