{
  "$name": "Conversational Product Voice",
  "$description": "A source-neutral reference for the friendly, plain-spoken register most consumer and SMB SaaS products aim for. The prose here is original; the underlying conventions are common professional practice, documented across public writing standards such as plainlanguage.gov and the GOV.UK style guide (see sources).",
  "url": "https://www.plainlanguage.gov/guidelines/",
  "voice": {
    "identity": "The product writes the way a good support engineer talks on a screen-share: fluent in the product, economical with the reader's time, and specific about what to do next. Copy earns trust by being accurate and brief, not by having a personality.",
    "attributes": [
      { "name": "Direct", "description": "Say the thing. Lead with the point, keep sentences short, and cut every word that exists only to sound professional." },
      { "name": "Warm without performing", "description": "Friendliness comes from being helpful and unhurried, not from exclamation marks. One genuine sentence beats three enthusiastic ones." },
      { "name": "Concrete", "description": "Name the object, the amount, the date, the next step. Vague copy reads as either evasive or unfinished." },
      { "name": "Respectful of attention", "description": "Assume the reader is mid-task. Front-load meaning, keep lines scannable, and never make someone read a paragraph to find the button." },
      { "name": "Calm under failure", "description": "Failure copy is load-bearing: the reader is already spending patience, so every word must either explain or unblock. The register flattens to short declarative sentences with zero decoration." }
    ]
  },
  "tone_shifts": {
    "first-run": "Momentum over completeness. One concrete win beats a feature tour; save the depth for when the person goes looking for it.",
    "routine-confirmations": "Nearly invisible. A confirmation exists so the reader can stop thinking about the task — make it specific, then let them go.",
    "failures": "Flat and factual. The reader's patience is already spent; spend none of it on personality.",
    "money": "The reader is scanning for two facts — how much, and when. Put those first, make them exact, and keep every flourish out of the sentence that contains a number.",
    "waiting-and-progress": "Honest about time. Name what is happening and roughly how long it takes; a vague spinner erodes more trust than a slow but labeled process."
  },
  "vocabulary": {
    "use": [
      "use, not utilize or leverage",
      "help, not facilitate",
      "buy, not purchase",
      "try, not attempt",
      "end, not terminate",
      "need, not require",
      "about, not approximately",
      "more, not additional"
    ],
    "avoid": [
      "synergy / leverage (as a verb) / utilize",
      "seamless / frictionless",
      "revolutionary / game-changing / best-in-class",
      "empower / unlock / unleash",
      "robust / cutting-edge",
      "delight (as a verb aimed at the user)",
      "simply / just (minimizers that read as condescension when the task isn't simple)"
    ],
    "never": [
      "Manufactured urgency — fake scarcity, countdowns, guilt-toned dismiss links",
      "Copy that pins an error on the reader",
      "Organization-chart jargon: team names, internal tool names, schema fields",
      "Placeholder text in anything shipped"
    ]
  },
  "grammar": {
    "person": "The reader is 'you'; the company is 'we'. The phrase 'the user' belongs in specs, not on screens.",
    "voice": "Active voice with a named actor. 'You're out of storage' — not 'The storage limit has been reached.'",
    "capitalization": "Sentence case everywhere — headings, page titles, buttons. Capitals are reserved for proper nouns and product names.",
    "numbers": "Single-digit counts appear as words; from 10 upward, numerals. Money, percentages, measurements, and clock times are numerals at any size.",
    "abbreviations": "Give the full form the first time a term appears, then the short form. Acronyms carry no internal periods.",
    "dates-and-times": "Name the month and attach a time zone — 'March 4, 2026 at 2:00 pm ET'. An all-numeric date is read differently on each side of the Atlantic.",
    "contractions": "Written-out forms sound robotic; it's, you're, and we'll are how people talk. The one exception is legal text, where precision outranks warmth."
  },
  "content-patterns": {
    "buttons": {
      "rules": [
        "The label alone should predict what happens next — a reader who saw only the buttons should still navigate correctly",
        "Verb plus object ('Export report'), sentence case, short enough to scan"
      ],
      "good": ["Export report", "Invite teammate", "Change plan", "Add payment method"],
      "bad": ["OK", "Yes", "Learn more"]
    },
    "destructive-confirmations": {
      "structure": "Name the thing being destroyed and the consequence, require a verb that matches the action, and never pre-select the destructive choice.",
      "example-good": "Delete the Q3 report? This can't be undone. [Cancel] [Delete report]",
      "example-bad": "Are you sure? [Yes] [No]"
    },
    "errors": {
      "structure": "Two jobs, in order: translate the failure into the reader's terms, then hand them their next move. Mention the cause only when it changes what they should do; internals stay internal.",
      "example-good": "We couldn't save your changes — your session expired. Sign in again and your draft will still be here.",
      "example-bad": "Error 401: Unauthorized."
    },
    "success": {
      "structure": "Specific enough that the reader can close the tab with confidence. Add a follow-up only when the workflow genuinely continues.",
      "example-good": "Your report is scheduled for Monday at 9:00 am ET. We'll email you when it's ready.",
      "example-bad": "Success!"
    },
    "empty-states": {
      "structure": "An empty screen is an onboarding surface: explain its purpose, preview the content activity will bring, end on a single action.",
      "example-good": "Nothing exported yet. Reports you export will be listed here. Export your first report.",
      "example-bad": "There is nothing to display."
    }
  },
  "inclusive-language": {
    "rules": [
      "Use 'they/them' when a person's gender is unknown.",
      "Describe what a feature does, not who it is for — 'compatible with screen readers' rather than ability-based shorthand.",
      "Swap disability metaphors for the literal meaning: 'gap' for 'blind spot', 'out of touch' for 'tone-deaf'.",
      "Where an idiom assumes one culture, state its meaning plainly.",
      "Make no assumptions about family structure, employment type, or physical ability."
    ]
  },
  "sources": [
    "https://www.plainlanguage.gov/guidelines/",
    "https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style",
    "https://learn.microsoft.com/en-us/style-guide/welcome/"
  ]
}