# Voice and content

The shared writing voice for every product surface — UI copy, empty states, errors, docs, marketing.
Carried forward from v1 (the one part that worked) and binding on all products. App repos reference
this file; they do not fork it. App-specific strings live with the app, written to these rules.

## The voice

**Calm, second person, low drama, explicit about consequences.** It reads like a careful colleague
explaining what a button will do before you press it.

- **Person.** Second person for the user ("your fleet", "you can undo this"). Never first person
  plural. The product refers to itself in the third person or not at all.
- **Casing.** Sentence case everywhere: page titles, headings, buttons, empty states. Product nouns
  keep their own capitalisation (Homebrew, macOS, DMARC, Microsoft Graph).
- **Sentence shape.** One idea per sentence. Full stops. No exclamation marks, no rhetorical
  questions. Panel headings are two or three words; the line underneath says what the panel is for.
- **Say what is safe.** Any destructive or irreversible action gets an unprompted sentence about
  what will *not* happen: "This removes the device record. Nothing is uninstalled from the Mac."
  Not optional.
- **Errors** are plain-language and actionable, never raw API text: "The sync could not be started.
  Try again." Name the fix when one exists.
- **Empty states** say what happened and what to do next in one breath: "No devices match your
  filters." / "Nothing is running right now."
- **Buttons** are verb-first and short: *Run brew update*, *Export CSV*, *Force check-in*, *Try
  again*. Cancel is always *Cancel*.
- **Numbers and units** are literal and unrounded: "231 / 248 · 93.1%", "~2m 14s remaining".
  Relative time in lists (4m ago, 3d 04h), absolute time in detail views. `tabular-nums` in UI.
- **Status labels** are one word in mono caps with a shape: ■ OK, ◆ WARN, ● FAIL — always with a
  contextual note when the status is not OK ("FileVault off", "Agent stale").
- **No emoji. Anywhere.** Icons (Phosphor) carry that job.
- **Docs voice** front-loads a one-line definition then facts; comfortable with technical nouns;
  no marketing adjectives. Nothing is "powerful", "seamless" or "beautiful".

## Glossary

The shared vocabulary. Agents and copy use these terms exactly; do not invent synonyms per app.

| Term | Meaning | Never |
| --- | --- | --- |
| device | an enrolled machine | "endpoint", "node", "computer" |
| operation | a queued or running action against devices | "job", "task" |
| check-in | an agent's report to the control plane | "heartbeat", "sync" (sync = data refresh in UI) |
| outdated | a package with a newer version available | "stale" (stale = an agent that stopped checking in) |
| compliance | policy conformance state of a device | "health" |
| policy | a rule set applied to devices | "profile" (reserved for OS configuration profiles) |
| quarantine | isolating a device from operations | "block", "ban" |
| fleet | all enrolled devices in an org | "estate", "inventory" (inventory = package listing) |

Add rows as products need them — one canonical term per concept, with the rejected synonyms listed
so agents stop "improving" them.