writing-for-interfaces

SKILL.md

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:

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.

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.

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.

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.

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:

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?

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.

Apply the core principles (purpose, anticipation, context, empathy — detailed below).

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 and emotional situation.

Match density to available attention. Mid-task text should be ultra-brief. Setup flows
can afford more.

Timing matters. Show information when it's relevant, not before. Place instructions
where the person is looking.

Write for the device. Describe gestures correctly ("tap" not "click" on touch). Phones
demand brevity; shared screens (TVs) need large, scannable text.

4. Empathy

Write for everyone who might use this product — different abilities, languages, cultures,
technical fluency, and emotional states.

Use plain, direct language. Avoid jargon, idioms, and culturally specific references.

Design for accessibility from the start. Labels, descriptions, and alt text aren't
afterthoughts — they're the entire experience for some people. See patterns reference for
detailed guidance.

Use inclusive, neutral language. Avoid unnecessary references to gender, age, or
ability.

Consider localisation. Write short copy, not compressed long copy. Account for text
expansion and RTL languages.

Writing craft

Practical editing moves that tighten copy. Apply after confirming voice and tone are right.

Remove filler words

Interface text has no minimum word count. Every word must earn its place. But before cutting
a word, check whether it's doing voice work. A word that's "filler" by general craft rules
may be load-bearing for the voice — "yet" in "Nothing here yet" carries warmth and calm,
and removing it makes the empty state blunter. The test: remove the word; if neither
meaning nor intentional tone changes, cut it.

Adverbs/adjectives: "Simply enter your license plate" → "Enter your license plate."
Words like "simply," "quickly," "easily," "just," "successfully" often promise something
you can't guarantee. Keep words that genuinely clarify ("Feed your pets automatically").

Interjections: "Oops!", "Uh oh!" in errors trivialise the problem. Cut them.

Pleasantries: "Sorry" and "please" sound insincere in automated messages. Use only
when they genuinely add warmth.

Punctuation:

Exclamation marks: rare. Reserve for genuinely celebratory moments.

Dashes (en/em): avoid in interface copy. They interrupt scanning. Break into
separate lines or sentences instead.

Ellipsis: only for processes in progress ("Loading..."), not trailing thoughts.

Avoid repetition

Combine overlapping ideas into one clear statement. Each element on screen should add new
information. When headline and body say the same thing in different words, collapse them.

"We're running late. Your delivery driver won't make it on time. They'll be there in 10
minutes." → "Delivery delayed 10 minutes. Check the app for your driver's location."

Be specific, not vague

Name the thing: "Can't open 'Quarterly Report.pdf'" not "Can't open this file."

Name the action: "Cancel Subscription" / "Keep Subscription" not "Yes" / "No."

Give real information: "Your card ending in 4242 was declined" not "There was a payment
error."

Keep a word list

Decide what you call things and stick to it. If it's "alias" on one screen, don't use
"username" on another. A word list is a simple table: Use / Don't use /
Definition. Button labels are especially good entries — if "Next" advances through a
flow, use "Next" everywhere.

Pronouns and perspective

"Favorites" conveys the same message as "Your Favorites." Avoid "we" — it obscures what
actually happened ("We're having trouble..." → "Unable to load content").

Sweat the details

Correct spelling, grammar, and punctuation build trust. Adopt capitalisation rules aligned
with the voice (title case = formal, sentence case = casual) and apply consistently. Write
for the space available — if copy needs to be short, write a short sentence, don't compress
a long one.

Write for dynamic content

Templated strings ("${count} items selected") are interface copy too. Write them so every
possible output reads naturally:

Handle zero, one, and many. "No results," "1 result," "24 results" — not a single
template that produces "0 results found."

Read it with real values. Substitute short and long names, small and large numbers.
"Welcome back, Christopher-Montgomery!" might break layout; "3 seconds ago" and "2 days
ago" should both read naturally.

Keep templates simple. If a string needs complex branching to read well, the design
may be asking too much of a single element.

Build language patterns

Define patterns for common moments — how flows begin ("Get Started"), advance ("Next" or
"Continue" — pick one), and end ("Done"). Use them consistently.

The simplest test

Read your writing out loud. If it sounds like how you'd explain something to a friend —
clear, natural, no filler — it's probably good. If it sounds like a robot, a legal
document, or an essay, keep refining.

Patterns reference

For detailed guidance on alerts, errors, empty states, onboarding, notifications,
accessibility labels, destructive actions, buttons, and instructional copy — see
references/patterns.md.