The console has rules for what copy to cut, but no guide for writing the copy that stays #169

New Issue

2026-10-06T08:51:17Z

cgalo5758 commented

2026-10-06 08:51:17 +00:00

The question

The design system says when a sentence should not exist and which words it must not use: the copy rule and its filler-copy lint, one canonical name per concept, no em dashes. Nothing says how to write a sentence that does exist: whose voice it uses, how an error says what went wrong and what to do next, how a confirmation, an empty state or a button label is phrased.

Failure messages show the gap. About 150 start with "Failed to …", about ten with "We couldn't …" and a few with "Could not …"; the FedWiki sites list now says "Couldn't …"; and some send the reader to the server logs. No other kind of sentence has been counted yet, so it is not known whether failures are the only inconsistent kind or just the first one noticed. What does the console's copy guide say?

What depends on the answer

Every sentence a person reads. Every review of new copy, which today checks only what must not be said. And the lints, which can only enforce what is written down.

Options known so far

A copy guide in the design system with a section per kind of sentence (errors, successes, confirmations, empty states, labels, headings), adapted from a published guide such as GOV.UK's or Polaris's, which the design system already cites, plus an audit of the existing copy against it.
One published guide adopted whole, with only the console's exceptions recorded.
Rules added one kind at a time, starting with failure messages.

Decided when

The design system has a copy guide covering each kind of sentence, the existing copy has been checked against it, and the rules a machine can check are in the lint.

## The question The design system says when a sentence should not exist and which words it must not use: the copy rule and its `filler-copy` lint, one canonical name per concept, no em dashes. Nothing says how to write a sentence that does exist: whose voice it uses, how an error says what went wrong and what to do next, how a confirmation, an empty state or a button label is phrased. Failure messages show the gap. About 150 start with "Failed to …", about ten with "We couldn't …" and a few with "Could not …"; the FedWiki sites list now says "Couldn't …"; and some send the reader to the server logs. No other kind of sentence has been counted yet, so it is not known whether failures are the only inconsistent kind or just the first one noticed. What does the console's copy guide say? ## What depends on the answer Every sentence a person reads. Every review of new copy, which today checks only what must not be said. And the lints, which can only enforce what is written down. ## Options known so far - A copy guide in the design system with a section per kind of sentence (errors, successes, confirmations, empty states, labels, headings), adapted from a published guide such as GOV.UK's or Polaris's, which the design system already cites, plus an audit of the existing copy against it. - One published guide adopted whole, with only the console's exceptions recorded. - Rules added one kind at a time, starting with failure messages. ## Decided when The design system has a copy guide covering each kind of sentence, the existing copy has been checked against it, and the rules a machine can check are in the lint.

cgalo5758 added the

kind

design

area/operator-ui area/member-ui labels 2026-10-06 08:51:17 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wiki-cafe/member-console#169