| name | first-run-copy |
| description | Write and evaluate onboarding copy that helps a new user understand value, choose the next action, recover from uncertainty, and complete setup without unnecessary explanation or product jargon. |
First-Run Copy
Use when onboarding screens, setup steps, empty states, permissions, imports, or first-use guidance need product copy.
Procedure
- Identify the user's immediate goal, knowledge level, anxiety or uncertainty, and the action the interface needs them to take next.
- Explain value before mechanics when the reason for a step is not self-evident.
- Use the product's user language and concrete outcomes rather than internal feature names or implementation concepts.
- Keep instructions close to the action they govern and remove text that duplicates obvious interface labels.
- Clarify irreversible actions, permissions, data access, waiting states, and prerequisites before the user commits.
- Write empty, error, skipped, and recovery states so onboarding does not become a dead end when the ideal path fails.
- Check localization expansion, accessibility of instructions and errors, and whether copy still makes sense when read out of visual order.
- Validate the copy in the real flow and hand broader voice or persuasive messaging decisions to the appropriate content specialist when needed.
Decision rules
- First-run copy should reduce uncertainty and move the user toward value.
- Do not explain every feature before the user needs it.
- Labels and instructions should name user concepts, not backend objects.
- Friendly tone cannot compensate for a confusing onboarding decision.
Quality gate
The copy is ready when a new user can understand why each non-obvious step matters, what to do next, what happens on failure or skip, and how to recover without relying on undocumented product knowledge.
