Writing For Interfaces

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 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.

Writing for Interfaces Skill

Install

npx skills add andrewgleave/skills --skill writing-for-interfaces --global

Example Prompt

/writing-for-interfaces Review and evaluate all UI copy for clarity, purpose, and consistency.

Skill Structure

This repository follows the Agent Skills open standard. Each skill is self-contained with its own logic, workflow, and reference materials.

writing-for-interfaces/
├── SKILL.md              — Core instructions, principles, and voice/tone guidance
├── references/
│   └── patterns.md       — Detailed guidance for common interface patterns
└── README.md

How it Works

When activated, the agent applies a voice-first workflow:

1. Establish voice: Search for an existing voice definition in project files (CLAUDE.md / AGENTS.md, style guides, design docs). If none exists or the existing copy is inconsistent, walk the user through defining one — what the product does, who it's for, where it's used, and what personality traits define it. An established and consistent voice is the foundation for all copy decisions. 2. Evaluate the request: Determine whether the task is new copy, a review, a rewrite, or terminology work and identify which interface patterns apply. 3. Apply voice and principles: Check that copy sounds like the defined voice. Dial tone qualities up or down for the situation and then apply the core principles. 4. Evaluate: Consult the patterns reference for situation-specific guidance on structure, tone, and common pitfalls. 5. Apply changes: Rewrite existing copy inline or draft from scratch. Show original → rewrite with a brief rationale tied to voice and principles. Prioritise changes that confuse or block users before polish. 6. Update terminology reference: Flag terminology drift and suggest word list entries to keep voice and phrasing consistent across the interface. The user should be able to review the changes and approve or reject them.

Sources

Many principles are distilled from Apple's interface writing guidance and generalised for product interfaces more broadly:

• **Human Interface Guidelines** — Writing
• **Human Interface Guidelines** — Alerts
• **Human Interface Guidelines** — Accessibility
• **WWDC 2019** — Writing Great Accessibility Labels
• **WWDC 2022** — Writing for Interfaces
• **WWDC 2024** — Adding Personality to Your App Through UX Writing
• **WWDC 2025** — Make a Big Impact with Small Writing Changes
• **Apple Style Guide**

Interface copy patterns

Detailed guidance for common interface writing situations. Each pattern should be applied through the lens of your product's voice and tone — the voice stays consistent, the tone adapts to the situation.

These patterns cover common cases, not every interface element. For anything not listed here, apply the core principles and voice framework from the main skill document.

Table of contents

1. Alerts and dialogs 2. Error messages 3. Destructive actions 4. Empty states 5. Onboarding and setup flows 6. Notifications 7. Accessibility labels 8. Buttons and actions 9. Instructional and inline copy 10. Settings and preferences

---

Alerts and dialogs

Alerts interrupt what someone is doing. Every alert must justify that cost by delivering information the person genuinely needs right now.

When to use an alert

• To confirm a significant or irreversible action.
• To request access to sensitive data (location, contacts, camera).
• To report an error that blocks progress.
• To notify of an event or situation requiring immediate attention.

When NOT to use an alert

• For non-essential information (use inline messaging or banners).
• For lengthy content or complex choices (use a dedicated screen).
• For problems you could have prevented (validate input inline).
• For technical diagnostics the person can't act on.
• For common, undoable actions — even destructive ones. People who delete an email intend

to discard it and can undo the action; they don't need an alert every time.

• At app launch. If something's wrong at startup (like no network), show cached or

placeholder data with a nonintrusive label describing the problem.

Structure

A good alert answers: What happened? Why? What now?

• Title: The main point in one short sentence. If someone reads only the title and

buttons, they should understand the situation. Sentence-style caps for complete sentences; title-style caps for fragments.

• Body (optional): 1–2 sentences of additional context. Only include if it adds

information the title doesn't cover. Don't use the body to explain what the buttons do — if the title and buttons are clear, the body isn't needed.

• Actions: Specific verb labels (see Buttons and actions).

Tone guidance

Alerts are interruptions in moments that range from routine to critical. Dial up clarity and directness. Dial back personality — this isn't the place for the voice to shine, it's the place for the voice to stay calm and get out of the way.

Checklist

• Could this be communicated without an interruption?
• Can someone understand it from title and buttons alone?
• Are button labels specific actions, not generic confirmations?
• Is the body actually adding information?

Before:

Title: "App cannot open this file"

Body: "You may need to download the latest update."

Buttons: Yes / No

After:

Title: "Can't Open 'Report.pdf'"

Body: "Update the app to open this file format."

Buttons: Update / Cancel

---

Error messages

Errors are moments of friction. Your job is to get the person unstuck as fast as possible.

Principles

1. Say what happened in plain language. Name the specific thing: "Can't connect to Wi-Fi" not "Network error." 2. Explain why if it helps — skip if the cause is obvious or irrelevant. 3. Tell them what to do next. Every error should have a clear path forward. Display errors close to the problem.

What to avoid

• Technical jargon and error codes the person can't act on.
• Blaming the person ("invalid input"). Instruct instead: "Use only letters for your name."
• Interjections ("Oops!", "Uh oh!") — they trivialise the problem.
• Vague non-information: "Something went wrong. Please try again."
• "Please" and "sorry" as reflexive padding.
• Robotic messages with no helpful information, like "Invalid name."

Tone guidance

Errors can be frustrating. Dial up clarity and helpfulness. Dial back friendliness — calm, direct language respects the person's situation more than forced warmth. If language alone can't address an error that's likely to affect many people, use that as a signal to rethink the interaction.

Before:

"Oops! You can't do that. Error code 1234567. Please try again."

Buttons: Okay / Cancel

After:

Title: "Billing Problem"

Body: "To continue your subscription, add a new payment method."

Buttons: Add Payment Method / Not Now

---

Destructive actions

When an action can't be undone, the writing must be proportionally careful.

Principles

• Name the specific thing being destroyed: "Delete 'Vacation Photos' album?" not

"Delete this item?"

• Make consequences explicit: "You'll lose all 847 photos in this album."
• Label buttons with the actual action: "Delete Album" / "Keep Album" — not "Confirm"

/ "Cancel." (See Buttons and actions.)

• Avoid double-negative confusion. "Cancel Cancellation" is a dark pattern. Write:

"Cancel Platinum Subscription?" with buttons "Cancel Subscription" / "Keep Subscription."

• Use the destructive style (e.g. red button) for actions the person didn't deliberately

initiate. When they chose the action (like Empty Trash), the confirmation doesn't need it.

• Always include a Cancel button as a clear, safe way out.

Tone guidance

Dial up directness and specificity. Keep the voice calm and neutral. This is not a moment for personality — it's a moment for clarity.

---

Empty states

An empty state is a screen with no content yet — an opportunity to teach, guide, or occasionally delight, but always with purpose.

Principles

• Tell the person what will appear here and how to make it happen: "No Saved Episodes.

Save episodes you want to listen to later, and they'll show up here."

• Match tone to context. Completed to-do list: celebratory. Empty search result:

helpful, not whimsical.

• Avoid idioms or humour that might not translate.
• Include a clear action if possible: a button to create, add, or search.
• Empty states are temporary — don't put crucial information here.

Tone guidance

Empty states are one of the best places for personality to shine through — especially welcome screens and completed states. But make sure the content is useful and fits the context. Education first, delight second.

---

Onboarding and setup flows

Onboarding is your chance to welcome someone, explain the product's value, and help them get started without wasting their time.

Principles

• Define the purpose of the whole flow and each screen.
• Lead with the why. Tell people why you need what you're asking for.
• Be honest about data and permissions: explain how data will be used.
• Welcome with warmth, but don't waste time. One sentence capturing the product's value

beats three paragraphs.

• Use consistent button labels. "Next" on every screen, "Get Started" at the beginning,

"Done" at the end.

• Each screen should say one thing. Multiple ideas → multiple screens.

Tone guidance

Onboarding is a warm moment. Dial up friendliness and helpfulness — the voice can shine here more than almost anywhere else. But never sacrifice clarity for personality — people need to understand what they're setting up.

---

Notifications

Notifications reach people when they're doing something else.

Principles

• Lead with the key information, not the instruction. "Your package arrives in 10

minutes" beats "Open the app to check delivery status."

• Be specific: "8 minutes to Home — take Audubon Ave, traffic is light" gives real

value. "Check your commute!" does not.

• Respect attention. If it's not time-sensitive or actionable, it probably shouldn't be

a notification.

• One idea per notification. Link to a screen for more detail.
• Choose the right delivery method. Alert for critical interruptions, banner for

informational, inline for contextual.

Tone guidance

Notifications should feel like a helpful tap on the shoulder, not a demand for attention. Keep the voice present but restrained. Match tone to urgency: a delayed delivery is matter-of-fact; a milestone can be warmer.

---

Accessibility labels

For screen reader users, accessibility labels _are_ the interface. Every interactive element and every meaningful visual needs a thoughtful text label.

Principles

• Always add labels. An unlabeled button reads as "button" — unusable. A person gives

an app about 30 seconds; if they can't access the functionality, they delete it.

• Be succinct, but disambiguate when needed. "Add" is usually enough; use "Add to cart"

when there are multiple "Add" buttons. Skip redundant context — in a music player, "Play" is sufficient.

• Don't include the element type. Screen readers announce "button," "link," etc.

"Add button" produces "Add button, button."

• Describe intent, not appearance. An image label should convey meaning: "Person

meditating with relaxed arms and forefingers touching" — not "circular image, blue background."

• Update labels when state changes. Play → Pause, etc.
• Label loading states. A spinner should announce "Loading."
• Match richness to content. Most labels should be succinct. But when the content

itself is expressive — stickers, emoji, illustrations — a richer description serves the person better. A sticker of Cookie Monster might be labelled "Me happy face eat small cookie, om nom nom" because that captures the spirit of what a sighted person sees. The goal is an equivalent experience, not just a minimal one.

• Use inclusive language. "Person" rather than assumed gender.
• Web: Applies to aria-label, aria-describedby, and alt attributes.

---

Buttons and actions

Buttons are the most-read text in any interface. People scan headers and buttons to understand a screen — they may never read the body.

Principles

• Use specific verbs: "Save Changes," "Send Message," "Download Report" — not "OK,"

"Submit," or generic "Done."

• Match the label to surrounding text. If the body says "pair your device," the button

should say "Start Pairing."

• Paired choices must be clear independently: "Keep Subscription" / "Cancel

Subscription" — not "Confirm" / "Cancel."

• Destructive actions: visually distinct (e.g. red), labelled with what they destroy.
• Avoid "OK" unless purely informational. "OK" is ambiguous — does it mean "do it" or

"I understand"?

• Prefer verbs over "Yes" / "No." The button labels alone should convey the choice.
• Be consistent. Add button labels to your word list.

---

Instructional and inline copy

Field hints, tooltips, inline guidance, step descriptions, settings labels.

Principles

• Lead with the benefit: "To keep your streak, solve today's crossword."
• Be direct. No "simply," no "quickly."
• Place instructions where the person is looking.
• One instruction at a time.
• For text fields: label clearly, use hint text for format examples

("name@example.com"). Show errors next to the field.

---

Settings and preferences

Settings are utilitarian — people visit to find something specific and get out.

Principles

• Name settings plainly.
• Add a short description if the label isn't enough. Describe what the setting does when

on — people infer the opposite.

• Provide direct links to navigate to a setting rather than describing its location.

Sources

This skill draws on:

• Apple HIG: Writing
• Apple HIG: Alerts
• WWDC22: Writing for Interfaces

— the PACE framework (Purpose, Anticipation, Context, Empathy)

• WWDC24: Add Personality to Your App Through UX Writing

— voice/tone exercises, the dial metaphor

• WWDC25: Make a Big Impact with Small Writing Changes

— filler words, repetition, lead with the why, word lists

• WWDC19: Writing Great Accessibility Labels

— context-driven labelling, verbosity as a deliberate choice

• Apple Style Guide