Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
45 lines
1.9 KiB
Markdown
45 lines
1.9 KiB
Markdown
# UI Copywriting — Derived Rules
|
||
|
||
> Derives from `domains/uiux/first-principles.md` P3 (Clarity), P1 (User Primacy), P5 (Forgiveness).
|
||
|
||
## Write for the User (P1 User Primacy)
|
||
|
||
- The reader is a user, not a developer. "Sign in" not "Authenticate."
|
||
- The reader is busy. Short sentences. Active voice. Verbs first.
|
||
- The reader is anxious. Reassure. "Your changes are saved." Not "State persisted."
|
||
|
||
## Clarity (P3)
|
||
|
||
- One idea per sentence. One action per button.
|
||
- Labels are nouns: "Email", "Password". Actions are verbs: "Sign in", "Save".
|
||
- Errors are specific: "Email is invalid" not "Something went wrong."
|
||
- Empty states are instructive: "No projects yet. Create one." Not "No data."
|
||
|
||
## Forgiveness (P5)
|
||
|
||
- Destructive actions warn: "This will delete 42 items. This cannot be undone."
|
||
- Confirmations name the consequence, not just the action. "Delete user" → "Delete Jane Doe and 12 associated items?"
|
||
- Undo is offered when possible. "Deleted. Undo." beats "Are you sure?" when undo is cheap.
|
||
|
||
## Tone (P3, P1)
|
||
|
||
- Helpful, not clever. Cleverness ages. Helpfulness does not.
|
||
- Apologetic when the system is at fault. "We couldn't save that. Try again." Not "Error."
|
||
- Neutral, not excited. "Saved." Not "Awesome! Saved!! 🎉" (unless the brand is intentionally playful).
|
||
|
||
## Microcopy (P3 Clarity, P9 Simplicity)
|
||
|
||
- Buttons: 1–3 words. "Sign in", "Create account", "Send invite".
|
||
- Tooltips: 1 sentence. Explain what the field does, not what the label says.
|
||
- Empty states: 1 sentence of explanation + 1 action. "No team members yet. Invite your first."
|
||
- Loading: present tense. "Saving..." not "Saved" (until it is).
|
||
|
||
## What Violates UI Copywriting
|
||
|
||
| Violation | Principle |
|
||
|-----------|-----------|
|
||
| "Error code 500" to a user | P3, P1 |
|
||
| "Are you sure?" with no consequence | P5 (no information) |
|
||
| "Submit" on a delete button | P3 (wrong verb) |
|
||
| 50-word tooltip | P9 Simplicity |
|
||
| "Awesome!" on a routine save | P1 (not for the user) | |