Voice and tone
Persistent voice across all Koder surfaces (4 traits) + tone matrix varying by context (success / error / first-run / marketing / AI-generated). Sets the baseline that grammar-and-mechanics.kmd and plain-language.kmd then refine. Modeled after LeafyGreen, Mailchimp, Pajamas, USWDS.
Spec — Voice and tone
*tatus* v0.1.0 — Draft. Mandatory cross-cutting spec. Bootstraps the new
specs/content/top-level group with first entry; companion specs grammarandmechanics.kmd + plain-language.kmd follow in the same dir.
R1 — Voice (4 persistent traits)
These traits apply to EVERY Koder surface, regardless of context:
| Trait | Do | Don't |
|---|---|---|
| *lear* | "Save changes" | "Persist your mutation to the data store" |
| *uman* | "We couldn't connect to your account." | "ERRAUTH001: connection refused." |
| *ecisive* | "Use the new editor" | "We recommend that you try the new editor" |
| *eferential to user time* | "Done. Your file is ready." | "We have successfully completed the action you requested and your file is now ready for use." |
R2 — Tone matrix
Tone shifts with context. Pick the column matching the surface:
| success | error | first-run | marketing | AI-generated | |
|---|---|---|---|---|---|
| *osture* | Confirming | Empathetic | Welcoming | Inviting | Disclosing |
| *ronoun* | "you" | "you" / never "the user" | "you" + Koder name | "you" | "the assistant" / "this answer" |
| *erbs* | past-tense ("Saved") | active, never blaming | imperative ("Choose your team") | possibility ("You can…") | conditional ("This may…") |
| *ength* | ≤ 6 words | ≤ 12 words + remedy | medium, friendly | medium, vivid | medium, qualified |
| *xamples* | "Saved" | "We couldn't reach Koder ID. Try again, or check your network." | "Welcome to Koder Talk. Create your first channel." | "Koder Hub: install any Koder app in one command." | "AI summary. May omit details — verify before sharing." |
R3 — Constraints (apply across all tones)
- ❌ No humor in errors. Failures aren't funny.
- ❌ Never blame the user. ("You entered an invalid email" → "That doesn't look like an email — try
name@example.com.") - ✅ Second
person ("you"). Never "the user" except in admin / policy contexts where the thirdperson is structural. - ✅ Active voice by default. Passive voice only when the actor is the system and naming it adds noise.
- ❌ Exclamation marks rare — only in true success / welcome. Never 2+ in a row.
- ❌ Em
dash beats parenthetical asides — easier scanning. (See `grammarand-mechanics.kmd` R3.) - ❌ No fake urgency ("Last chance", "Today only", "Don't miss out") — see
feature-paywall.kmdR5.
R4 — Translation guidance
- Translators MAY adapt the trait expression to locale norms but MUST preserve the tone (e.g., decisive in Japanese leans formal-imperative, not casual).
- pt
BR specifically: secondperson "você" not "tu"; warm but not casual; never genderpresumptive when avoidable (per inclusivelanguage conventions). - Per
policies/language.kmdchat is ptBR; products are enUS baseline + per-locale translations.
R5 — AI-generated copy
When AI composes UI text (Thumbprint pattern, see #078 follow-up):
- AI MUST be prompted with this spec + grammar
andmechanics.kmd + plain-language.kmd as system prompt. - AI output MUST be reviewed by a human before shipping — see
specs/patterns/ai-feature-visual-language.kmdR5 disclosure.
Não-escopo
- Per
locale style guides beyond the enUS / ptBR baselines (separate perlocale ticket if pursued). - Brand
marketing voice (Koder editorial brand voice for blog / social — handled by `metabrandkoderdesign`).