Voice and tone
content specs/content/voice-and-tone.kmd
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.
Quando esta spec se aplica
Triggers primários
- Write or review user-facing copy in a Koder product
Todos os triggers
- Author UI copy for a Koder surface
- Review AI-generated UI text for tone alignment
- Translate strings to a new locale and need register guidance
Corpo da especificação
Spec — Voice and tone
Status: v0.1.0 — Draft. Mandatory cross-cutting spec. Bootstraps the new
specs/content/top-level group with first entry; companion specs grammar-and-mechanics.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 |
|---|---|---|
| Clear | "Save changes" | "Persist your mutation to the data store" |
| Human | "We couldn't connect to your account." | "ERR_AUTH_001: connection refused." |
| Decisive | "Use the new editor" | "We recommend that you try the new editor" |
| Deferential 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 | |
|---|---|---|---|---|---|
| Posture | Confirming | Empathetic | Welcoming | Inviting | Disclosing |
| Pronoun | "you" | "you" / never "the user" | "you" + Koder name | "you" | "the assistant" / "this answer" |
| Verbs | past-tense ("Saved") | active, never blaming | imperative ("Choose your team") | possibility ("You can…") | conditional ("This may…") |
| Length | ≤ 6 words | ≤ 12 words + remedy | medium, friendly | medium, vivid | medium, qualified |
| Examples | "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 third-person 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
grammar-and-mechanics.kmdR3.) - ❌ 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: second-person "você" not "tu"; warm but not casual; never gender-presumptive when avoidable (per inclusive-language conventions).
- Per
policies/language.kmdchat is pt-BR; products are en-US 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-and-mechanics.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 en-US / pt-BR baselines (separate per-locale ticket if pursued).
- Brand-marketing voice (Koder editorial brand voice for blog / social — handled by
meta/brand/koder-design).
Referências
specs/content/grammar-and-mechanics.kmdspecs/content/plain-language.kmdspecs/patterns/ai-feature-visual-language.kmdpolicies/language.kmd