Change log

Quorum Voice & Tone Guide

Change log

The Promise

Clarity is kindness. Every word in every surface a user reads either helps them or wastes their time. We pick the one that helps.

This guide applies to every user-facing word in Quorum: microcopy, UI labels, error messages, empty states, onboarding, in-app prompts, marketing, landing page, email sequences, release notes, help content, the public accessibility statement. It also applies to James's personal writing (portfolio, case study, bio, public posts).

Scope: customer-facing vs internal planning docs

Customer-facing content — where every rule in this guide applies:

• Product UI: microcopy, labels, errors, empty states, onboarding, in-app prompts
• Marketing surfaces: landing page, email sequences, release notes, help content, public accessibility statement
• James's personal byline writing: portfolio, case study, bio, public posts

Internal planning docs — where em dashes are allowed but the rest of the blacklist still applies:

• PRD, epics, architecture docs, UX specifications
• Research reports (competitive, methodology, technical)
• Alignment reports, change proposals, handoff briefs
• Story files and design notes. These are internal even though they contain quoted user-facing strings. Fix em dashes inside backticks or quoted copy per the customer-facing rule, but em dashes in surrounding prose (task descriptions, dev notes, section headers) stay.

Why the em-dash carve-out. Em dashes are banned in customer-facing content because external research confirms they're a statistically strong AI-generated-text signal. Users reading our copy shouldn't feel like they're reading LLM output. In internal planning docs the audience is the team, not users; em dashes do legitimate work as prose rhythm, and banning them there adds friction without adding trust signal.

Why the rest of the blacklist stays everywhere. Hard-no words ("paradigm," "holistic," "utilize," etc.), blacklisted phrases ("it's important to note," "let's dive into," etc.), and structural patterns (synonym-swapping, five-paragraph-on-short-copy, rhetorical triples, manufactured conflict) are bad writing in any context. They also drift into customer-facing copy via copy-paste from planning docs. Keeping the whole corpus clean costs nothing and prevents leakage.

Practical guide for voice passes on story files and design notes:

• Em dashes inside backticks or quoted user-facing strings → always fix
• Em dashes in surrounding prose (task descriptions, dev notes, headers, file-list annotations) → always keep
• Hard-no words, phrases, structures → fix everywhere (they leak customer-facing via copy-paste)

Who reads this

Primary: Maya (solo founder / indie builder). Reading level target grade 9 or below, per NFR-A4.

Secondary: Sam / Jordan / Chris (enterprise product trio). PM, design lead, eng lead. Same reading level. Denser content acceptable when audience expertise warrants it, never as an excuse for jargon.

Admin, implementer, recovery personas inherit the same rules.

Five voice pillars

Voice is what Quorum sounds like everywhere. Tone flexes by context (next section).

1. Direct, not performative

Short sentences. Active voice. Zero hype adjectives. Confidence shows in specifics, not volume.

2. Specific over abstract

Name the thing. Name the person. Numbers when you have them. Abstract nouns are where clarity goes to die.

3. Collaborative, not subordinate

The user is the conductor. Copy treats them as the decision-maker, not a user-to-be-guided. We do not beg, apologize, or over-instruct.

4. Opinionated about craft

Quorum has a point of view on how software gets made. That belongs in the copy. Neutral tools do not differentiate.

5. Accessibility as a voice commitment

Plain language. Grade 9. Alt text always present and descriptive. Error messages tell users what to do, not what went wrong. Consistent labels across screens. These are voice decisions, not compliance checkboxes.

Tone shifts

Voice stays constant. Tone flexes with context:

House style

Hard rules (never)

1. No em dashes in customer-facing content. Use colons, parentheses, or rewrite. Confirmed as a real AI-tell by external research, not folk wisdom. Internal planning docs are exempt per the Scope section above; em dashes inside backticked or quoted user-facing strings inside internal docs are still fixed.
2. No blacklisted words (next section).
3. No blacklisted phrases (next section).
4. No synonym-swapping. If the word is "vote," use "vote" every time. Do not substitute "poll," "survey," "ballot" to vary language. Synonym-swapping is one of the strongest AI-tells.
5. No "It's not X, it's Y" back-to-back. One use is fine. Two in the same piece is AI rhythm.
6. No five-paragraph essay template on short copy. A 100-word blurb does not need intro / body / conclusion.
7. No manufactured conflict. "Here's what nobody's saying" / "The truth no one tells you" framing is AI sleight-of-hand.
8. No signposting between paragraphs. "Let's dive into..." / "Now let's explore..." / "In this section..." all get cut.
9. No exclamation points as enthusiasm padding. Reserve for genuine urgency or rare celebration. "Welcome to Quorum!" becomes "Welcome to Quorum."
10. No "Kindly" as a politeness booster. Reads as formal-to-the-point-of-wrong.

Soft rules (use with care)

Words that have legitimate meaning and are allowed when accurate. Banned when used as filler.

When in doubt on a soft-rule word, rewrite. Something simpler almost always works.

Transitional words

Max one per document: Moreover, Furthermore, Consequently, Additionally, Indeed.

Better options in most cases: Also, And, So, or no transition at all. Short sentences adjacent to each other rarely need connective tissue.

Default style

• Active voice default. Passive only when the actor is genuinely unknown or irrelevant.
• Vary sentence length deliberately. Short, long, short. Hyper-symmetric paragraphs where every sentence is roughly the same length is an AI tell.
• Fragments allowed where they land.
• Contractions on. You're, we'll, it's, don't.
• Oxford commas on. Unless James says otherwise on a specific piece.
• Sentence case for UI labels and button text. Not title case.
• Numerals for 10 and above; words for under 10. In UI, consistency wins over the rule.
• No double spaces after periods.

Blacklist

Words — hard-no anywhere in Quorum copy

Delve, tapestry, multifaceted, holistic, paramount, resonate (metaphorical), utilize, leverage (as a verb), leveraging, harness (power of), revolutionize, game-changer, paradigm, synergy, ecosystem (metaphorical), journey (metaphorical), unveil, elevate (metaphorical).

Phrases — hard-no anywhere in Quorum copy

• "It's important to note"
• "It's worth noting"
• "At its core"
• "At the end of the day"
• "Ultimately,..." (at sentence or paragraph start)
• "In conclusion,..."
• "In summary,..."
• "Let's face it,"
• "The bottom line is,"
• "In today's fast-paced / evolving / dynamic world"
• "In today's landscape"
• "Here's the key takeaway"
• "The most important thing is"
• "Navigate the complexities of"
• "Embark on a journey"
• "Harness the power of"
• "Let's dive into"
• "Let's explore"
• "Take your [X] to the next level"
• "The power of X"
• "Transform your workflow"

Structures — hard-no

• Five-paragraph template on short copy. Structure follows content length, not the reverse.
• Three-part rhetorical list flourishes. "Faster, smarter, better" style triples read as marketing.
• Manufactured conflict. "Here's what nobody's saying" / "The truth no one tells you."
• Back-to-back "It's not X, it's Y" patterns.
• Signposting between paragraphs. Let structure do the orienting.

Common moments

The specific copy patterns that come up constantly. Use these as the default. Deviate only when the context demands it.

Error messages

Formula: What happened. What to do next.

• ✅ "Your card was declined. Try another, or update your details in Settings."
• ✅ "Password needs 8+ characters."
• ✅ "Something broke on our end. We're looking at it."
• ❌ "An error occurred."
• ❌ "Oops! Something went wrong."
• ❌ "Please contact support."

Empty states

Formula: What this space is for. How to fill it.

• ✅ "No polls yet. Create one to get started."
• ✅ "No members yet. Invite your first teammate."
• ❌ "Nothing here."
• ❌ "This section is empty."

Button labels

Formula: Verb that matches the action.

• ✅ Send invitation / Create poll / Confirm delete / Save changes
• ❌ OK / Submit / Continue / Proceed

Destructive confirmation

Formula: What this deletes. What to type.

• ✅ "Deleting this workspace erases 12 polls, 3 members, and 847 votes. Type DELETE to confirm."
• ❌ "Are you sure? This action cannot be undone."

Onboarding first line

Formula: Warm without being saccharine. Orient the next action.

• ✅ "Welcome. Let's set up your first workspace."
• ❌ "Welcome to Quorum! We're excited to have you on this journey!"

Success states

Formula: Celebrate the user's action, not the product's excellence.

• ✅ "Poll sent to 12 voters."
• ✅ "Workspace created. You can invite members now."
• ❌ "Success! Your poll has been successfully sent!"
• ❌ "Awesome work!"

Loading states

Formula: What is running. How long.

• ✅ "Analyzing responses. 10 seconds."
• ✅ "Saving…" (when genuinely brief)
• ❌ "Please wait while we process your request."

Validation errors

Formula: Specific and non-blaming. Tell the user what will work.

• ✅ "Password needs 8+ characters and one number."
• ✅ "Email already in use. Sign in instead?"
• ❌ "Invalid input."
• ❌ "You must provide a valid email."

Agent collaboration

Internal rules for the team writing for Quorum. Users never see this section.

• Kinsley drafts microcopy in design context. Quentin reviews for voice and accessibility. Kinsley's design intent sets the meaning; Quentin's editorial sets the phrasing. Both can flex.
• Paige owns internal technical documentation (PRDs, architecture, internal guides). Quentin reviews only the user-facing pieces Paige produces (release notes, help content, public accessibility statement).
• Sophia owns launch and pitch narrative. When launch content ships inside the product (landing page, first-run flow), Sophia drafts the arc and Quentin polishes the words.
• John writes the PRD. Quentin reviews user-facing persona descriptions, feature names, and anything PRD-side that becomes public-facing.
• Damien writes backend error payloads. Quentin reviews the human-readable pieces for voice and accessibility.
• Jaymes implements strings. The in-context pass catches drift between design-time copy and built-time copy.
• Amelia receives copy through story specs. If copy changes post-handoff, Quentin flags via sprint-status.

Review rituals (the three touchpoints)

1. Voice pass — after Kinsley's UX handoff, before dev starts. Quentin reviews draft copy for voice, reading level, and accessibility. Async. Not blocking.
2. In-context pass — during implementation, on staging. 15 minutes. Catches drift between design and code. Async. Flags issues; team decides whether to fix or defer.
3. Release skim — before prod deploy. 15 to 30 minutes across everything shipping. Checks voice hold across new screens, catches last-minute weirdness, confirms a11y quick-checks. Soft gate.

Not blocking except the release skim, which flags but does not veto.

What this guide does not cover (yet)

• Multilingual voice. Quorum is English-only through v1. When localization starts, this guide gets a translation protocol section.
• Voice in AI-agent-generated content surfaced to users (e.g., Quorum's own agents producing recommendations for a user). Needs a separate pass once Epic 7 territory is in flight.
• SEO and public content strategy. Covered lightly here but deserves its own doc when marketing ramps.
• Poll template library content (Epic 11 Story 11.1). Will be authored against this guide; templates ship WCAG-AA compliant by default.

Living doc

This guide updates as decisions accumulate. Every release skim that catches voice drift updates this file. New soft-rule calls get added. Blacklist grows as patterns surface.

If you disagree with a call: tell me. If I make a bad call: tell me. If a rule gets in the way: tell me. The guide serves the product, not the other way around.