Voice

Rule

Write exact, literate, unhurried, technically precise English. Use the domain's real nouns: Task, Agent, Event, lease, artifact, capability. State the specific true thing first. Sentence case is standard. Buttons begin with a verb and name the object.

Do not use theatrical apologies, exclamation marks, cute empty states, filler, anthropomorphism, or a sentence that merely repeats its heading. Do not imply execution or availability the system does not have.

Errors mirror the API contract in this order:

1. What happened, naming the object.
2. The stable machine code, rendered as selectable mono text.
3. Whether the operation is retryable.
4. The next legal action, as text and as an action when possible.

Token contract

Authored explanation uses typography.body-md. Interface labels and actions use typography.label-md or typography.ui-md. Machine codes use typography.data-md. Errors use colors.on-error-container on colors.error-container, never colour alone.

Correct example

Illegal status transition. Task tsk_01JAV is in progress; done is not reachable from there. invalid_transition, not retryable. Legal next states: in review, blocked, cancelled.

The message names the record, exposes a stable code, prevents an unsafe retry, and gives the next legal states.

Rejected example

Something went wrong. Try again.

The message hides the object, machine code, retryability, and legal action. Retrying may repeat an invalid or destructive operation.

Reasoning

Element-by-element rules live in copy and voice. The error contract comes from the Agent Experience specification.