Writing

These rules are for the words inside the product: labels, titles, messages, empty states and errors. How Raft sounds, and why, is in Voice and tone; which word to use for each thing is in Terminology. Writing the documentation follows the writing guide instead.

Principles

• Short and direct. Say the fact or the action, in as few words as it takes. Keep the voice of the website, with a little humor where nothing is at stake.
• Agents are teammates. Name them, and use the verbs you would use for a person; see Writing about agents.
• One action says one thing. The button, the dialog it opens and the button that confirms it use the same words.

Casing

• Use Title Case for anything clickable: Create Task, Mark All Read, Convert to Task.
• In Title Case, keep these short words lowercase: a, an, the, to, in, on, of, for, as, and, or.
• Use sentence case for titles, group headings, descriptions and empty states. A dialog or sheet title that repeats the label of the button that opened it keeps that label's Title Case: Create Channel; see Actions and their dialogs.
• Write product nouns in lowercase inside a sentence: "Move to another computer", "Leave this server". They take capitals only as part of a clickable label or a name: Add Computer, Raft Computer.
• Never use all caps. Typeface and casing rules are in Typography.

Voice

• Keep humor to onboarding and success messages. Write errors and empty states plainly, so people can act on them; see Voice and tone.
• Address the person as "you". Name an agent by its name, in the third person: "Bugen claimed #25", "Martin needs your OK".
• Use teammate verbs for agents (claim, hand off, review, ship, remember), never bot, process, execute or AI-powered. The full rules are in Writing about agents.
• Spell task statuses Todo, In Progress, In Review, Done and Closed.
• Use display names, not handles.
• Write Chinese interfaces the same way: short sentences and few adjectives, with numbers, IDs and times still in Space Mono.

Actions and their dialogs

• Make a button's label the title of the dialog or sheet it opens: Register App opens Register App, Create Channel opens Create Channel. What people click is what opens: a dialog with other words looks like the wrong one opened.
• Title an edit with Edit and the item's name: Edit Release Bot.
• Make the confirm button repeat the verb and name the result: Make Public, not Public; Delete Agent.
• Make the cancel button say what stays: Keep Box, Keep Working.

Errors and empty states

• Say what happened, then what to do next: "Runtime detection failed. Restart Raft Computer and try again."
• Name the thing that failed, not the system that failed: "Could not save changes", not "Request failed".
• Write an empty state as the fact, in sentence case: "No tasks yet", "No tasks match these filters". Add one line or one button for the next step when there is one.
• Say what is happening while something is busy: "Uploading · 64%", "Loading messages". Never "Processing…" or a bare "Loading…".
• Where each kind of problem is shown (inline, banner, toast or notification center) is in Feedback.

Do and don't

Related

• Voice and tone: how Raft sounds in each moment.
• Terminology: the product's words and the ones to avoid.
• Typography: Space Grotesk and Space Mono.
• Forms: labels, help text and validation messages.
• Feedback: how errors are worded and where they go.