# Copy

> Microcopy is the brand's signature. The voice you trust is built in the moments you don't expect copy — a button label, a tooltip, an error, a loading state.

## Principles

1. **Direct, warm, brief, unpretentious** — Two sentences usually finish the thought. One if you can land it. Confident without being arrogant. Conversational without being casual.

2. **Headlines claim, subheads clarify** — The headline takes territory. The subhead gives one specific clarifying detail. The body delivers. Microcopy comforts. Each layer has a distinct job; making each layer do the others' jobs is the most common voice failure.

3. **Numbers beat adjectives** — "75ms latency" beats "blazingly fast." "1.5% cashback" beats "industry-leading rewards." "Ship in 1 to 3 days" beats "ship fast." A specific number is worth ten adjectives.

4. **Errors name the cause AND the fix** — Never "form contains errors" or "invalid input." Always specific: name the field, name the problem, name the fix. Every error includes a clear recovery path.

5. **Empty states explain the path forward** — "Connect your first source to start" beats "No data yet." The empty state is the start of a relationship, not a failure to load.

6. **Calm celebration** — Success states say what happened ("50 points added"), not how the user should feel ("Congratulations! You earned 50 points!"). The system stays calm even when the user is celebrating.

7. **Active voice across all surfaces** — "Agents handle the call" beats "The call is handled by agents." Direct subject-verb-object. Passive constructions read as bureaucratic.

8. **Second person, sparingly** — "You ship, you plan, you decide" works in body copy. Headlines often describe the system in third person and let the reader find themselves in it.

9. **No marketing clichés** — "Elevate," "Seamless," "Unleash," "Next-Gen," "Empower," "Revolutionize," "Game-changer," "Delve," "Leverage" (as a verb), "Robust" (applied to anything) — banned. Use concrete verbs that describe what the product actually does.

10. **No exclamation points outside delight micro-moments** — Even then, sparingly. Exclamation marks in marketing copy read as small-startup energy. The brand is confident; it does not shout.

11. **Sentence case everywhere** — Title Case On Every Word reads as enterprise software circa 2014. Sentence case is the modern default for headlines, subheads, buttons, and nav.

12. **The product is the hero, not the company** — Marketing copy talks about what the user will do, not how brilliant the team is. Company narrative lives on the about page; the homepage talks about the work.

## Do / Don't

| Do | Don't |
|---|---|
| "Stop reading documents. Start making decisions." | "We help you make better decisions faster!" |
| "50 points added." | "Congratulations! You earned 50 points!" |
| "Phone number needs a country code." | "Invalid input." |
| "Connect your first source to start." | "No data yet." |
| "Book a demo" | "Learn more" |
| "Couldn't reach the server. Try again, or check status." | "Something went wrong." |
| "Building foundational [X] to do [ambitious thing]" | "Revolutionizing the future of [industry]" |
| "98% of the top 100 cloud companies" | "Trusted by leaders worldwide" |
| "Ship in 1 to 3 days" | "Ship fast" |
| "Make anything possible — in one tool." | "Unleash your team's potential!" |
| Use sentence case for headlines | Use Title Case For Every Word |
| Quantify in headlines ("21x faster," "60% reduction") | Use vague modifiers ("amazing," "powerful") |
| Use specific named outcomes | Use abstract benefit statements |
| Address the reader as "you" in body | Use "users" or "the platform" as abstractions |
| Use first-person plural ("we built") sparingly in context | Lead every headline with "We help you..." |
| Use feature names as proper nouns (Agents, Spaces, Boosts) | Use generic descriptors ("Powerful Workflows") |
| Use em dashes (—) and en dashes (–) correctly | Use double-hyphens (--) |
| Use curly quotes ("") | Use straight quotes ('') |
| Use specifics over superlatives | Use superlatives over specifics |

## Examples

### Pattern: Headline construction
**Use when**: Hero, section openers, page titles.
**Anti-pattern**: Feature-listing headlines like "AI-Powered Next-Gen Platform For Modern Teams."
**How**: Imperative verb + concrete outcome. Examples:
- "Stop reading documents. Start making decisions."
- "Run an entire company with agents."
- "Replace manual work with automated workflows."
- "Make anything possible — in one tool."
- "Build sites that ship."

The verb does heavy lifting. The noun grounds it. Verbs lead headlines: "Make," "Build," "Ship," "Meet," "Turn," "Bring," "Get," "Run," "Replace," "Stop."

### Pattern: Headline + deflating qualifier
**Use when**: Premium creative-tool category, ambitious products.
**Anti-pattern**: Big claim with no constraint ("Unlimited possibilities!") that reads as overpromise.
**How**: Big claim + small honest constraint. "Make anything possible — in one tool." "Build better sites, faster." "Ship in 1 to 3 days." The constraint is what makes the claim believable.

### Pattern: Two-sentence headline (Stop X. Start Y.)
**Use when**: There's a clear behavioral shift the product enables.
**Anti-pattern**: Overusing the pattern; once per page maximum.
**How**: One sentence names the friction. One sentence names the resolution. "Old approach is broken. New approach is here." Cadence over completeness.

### Pattern: Subhead that quantifies
**Use when**: Below every hero or section headline.
**Anti-pattern**: Subhead that restates the headline in different words.
**How**: The subhead names a measurable outcome. "21x faster." "60% reduction in unqualified calls." "From days to minutes." "Across 22 languages." Numbers do more persuasion than adjectives. The subhead is short — often one sentence; two if the second is the proof.

### Pattern: CTA microcopy
**Use when**: Every button on every page.
**Anti-pattern**: "Get Started," "Learn More," "Click Here," "Submit."
**How**: Specific verb + concrete next step. "Book a demo," "Start free," "See the platform," "Run a query," "Open account," "Send invite," "See how it works." The button completes the user's sentence. The CTA verb matches the product verb — if the product deploys, the CTA is "Deploy." If it queries, "Run a query."

### Pattern: Error message specificity
**Use when**: Form validation, async failures, edge cases.
**Anti-pattern**: "Form contains errors," "Invalid input," "Something went wrong," "Oops!"
**How**: Name the field. Name the problem. Name the fix. Examples:
- "Email needs an @ sign. Try again."
- "Phone number must include the country code. Add +1 or your country prefix."
- "Password needs at least 8 characters and one number."
- "Couldn't reach the server. Try again, or check [status link]."
- "Date can't be in the past. Pick today or later."

Validation runs on `blur`, not on every keystroke. Errors appear inline below the affected field. Multiple errors get a summary at the top with anchor links.

### Pattern: Empty state copy
**Use when**: Lists, tables, dashboards before content exists.
**Anti-pattern**: "No data yet" or a blank screen.
**How**: Name the surface, name the path forward, name the next action. Examples:
- "Connect your first integration to start"
- "No notes yet — start your first meeting"
- "Nothing here yet. Start with a template, or build from scratch."
- "No appointments. Book one and we'll show it here."

Premium products assume the user is smart and just needs the next move named.

### Pattern: Loading state voice
**Use when**: Async operations longer than 300ms.
**Anti-pattern**: "Loading…" with no personality, or "Hold on a sec, we're working on it!" with too much.
**How**: Brief, calm, present. Examples:
- "One sec…"
- "Almost there"
- "Putting this together"
- "Saving"

The brand inhabits the waiting moments. Loading shouldn't read as an apology.

### Pattern: Success state calm
**Use when**: Confirmations, completed actions, state changes.
**Anti-pattern**: "Congratulations! You have successfully earned 50 points!"
**How**: Operational, not emotional. Examples:
- "50 points added."
- "Profile saved."
- "Account ready."
- "Phone verified."
- "Notes saved."
- "Invite sent."

Short, declarative, no enthusiasm. The system stays calm even when the user is celebrating.

### Pattern: Customer testimonial framing
**Use when**: Quotes from customers in marketing surfaces.
**Anti-pattern**: "Great product, love it!" with no name and no specifics.
**How**: Lead with the result, not the praise:
- "We cut review time by 40%"
- "Cut our triage time in half"
- "From 380ms to 90ms on p99"

Quote a single sentence under 15 words. Attribute with name, title, and company (no "Software Engineer" without a company). No marketing-speak ("a game-changer," "best-in-class"). The quote is the customer's voice; resist polishing it into marketing copy.

### Pattern: Feature naming
**Use when**: Naming product capabilities.
**Anti-pattern**: "Powerful Workflows," "Smart Agents," "Intelligent Automation."
**How**: Nouns or noun-phrases, not adjective-stacks. Examples:
- "Workflows"
- "Agents"
- "Spaces"
- "Boosts"
- "Connectors"
- "Hidden Profile"

Single-word feature names get capitalization rules and become brand assets. Naming a thing makes it real; describing a thing makes it brochure.

### Pattern: Tone for AI features
**Use when**: Describing AI-assisted capabilities.
**Anti-pattern**: "Our AI writes your emails for you!" — positions AI as replacement, erodes user agency.
**How**: Augmentation framing. Use "drafts," "suggests," "tries," "helps," "joins" — not "writes," "creates," "knows." The user remains the subject of the sentence; the AI is the tool joining the user's existing work. Examples:
- "Takes your raw notes and makes them better"
- "Drafts the follow-up; you ship it"
- "Helps you follow up with the people you met today"
- "Tries the obvious paths; you choose what to keep"

### Pattern: Eyebrow labels
**Use when**: Section openers needing taxonomic context without numbered chapters.
**Anti-pattern**: "SECTION 01," "QUESTION 05," "OUR PROCESS 02" — banned forever.
**How**: Short, uppercase or sentence-case label at 10 to 13px, tracking +0.06em to +0.10em, in muted neutral or paired accent. Names the conceptual category:
- "PLATFORM"
- "VOICE AGENT"
- "USE CASE"
- "RESEARCH"
- "SAFETY"
- "WHAT'S NEW"

Sometimes preceded by a 6 to 8px colored dot. Replaces decorative section dividers.

### Pattern: Voice consistency across surfaces
**Use when**: Building marketing site, in-product copy, error messages, docs.
**Anti-pattern**: Marketing copy reads polished; in-product copy reads like an engineer's stub; error messages read like 1995 console output.
**How**: The same voice that writes a tooltip writes the homepage. Marketing copy, in-product empty states, error messages, blog posts, docs — all sound like they were written by the same person. The brand voice scales down, not up: same voice at the hero and at the tooltip.

### Pattern: Toast accessibility
**Use when**: Toast notifications for system feedback.
**Anti-pattern**: Toast appears visually only; screen reader users miss it entirely.
**How**: Use `aria-live="polite"` for non-urgent toasts (most cases). Use `aria-live="assertive"` or `role="alert"` for urgent errors only. Auto-dismiss in 3 to 5 seconds. Never steal focus. Provide a visible dismiss control for users who need more time. Toast copy stays brief: "Profile saved." "Invite sent." "Connection paused."

### Pattern: Confirmation dialog
**Use when**: Destructive actions, irreversible operations.
**Anti-pattern**: "Are you sure?" with no context, or no confirmation at all on permanent delete.
**How**:
- Name the action and what it affects: "Delete 12 invoices? This can't be undone."
- Provide both confirm and cancel as visible buttons
- Destructive action uses the danger color
- Cancel is the default (escape key, click outside)
- Optional: secondary "Undo" toast for 5 to 10 seconds after the action

### Pattern: Punctuation discipline
**Use when**: Every line of copy.
**Anti-pattern**: Straight quotes, double-hyphens, missing em-dashes, exclamation mark inflation.
**How**:
- Curly quotes: ""
- Em-dash (—): for pauses and asides (no spaces)
- En-dash (–): for ranges ("3–5 minutes")
- Hyphen (-): for compound words
- Period at end of two-word headlines acceptable as cadence move ("Make it.")
- Commas freely in conversational subheads
- Semicolons essentially absent in marketing copy
- Question marks only when genuinely asking ("Why so slow?")
- No exclamation points in marketing copy — except user-voice testimonials

## Tokens / values

### Voice register
- Direct, warm, brief, unpretentious
- Confident without arrogant
- Conversational without casual
- Calm under pressure (errors, empty states, edge cases)
- Specific over aspirational
- Plain language over jargon (jargon only when audience has earned it)
- Honest about what the product does (no "transform your business" abstractions)
- The product is the hero, not the company

### Sentence length
- Headlines: under 9 words
- Subheads: 1 to 2 sentences
- Body paragraphs: 2 to 3 sentences
- Microcopy: 1 to 5 words
- Customer quotes: under 15 words
- Error messages: 1 sentence naming cause + fix
- Empty states: 1 to 2 sentences naming surface + next action
- Success states: 2 to 4 words

### CTA verb library
- Open account
- Start free
- Get started
- Book a demo
- See the platform
- Run a query
- Try a sample
- Send invite
- Save note
- See how
- See the demo
- Talk to sales
- Talk to us
- Watch demo
- See the dashboard
- Try a sample partner

Banned CTA verbs:
- Submit
- Click here
- Learn more (only acceptable as the weakest secondary fallback)
- Sign up here
- More info

### Headline patterns (proven)
- Imperative + outcome: "Make X happen."
- Stop X, Start Y: "Stop reading documents. Start making decisions."
- Replace X with Y: "Replace manual work with automated workflows."
- Run an entire X with Y: "Run an entire company with agents."
- Built for X: "Built for finance teams."
- The X for Y: "The product development system for modern teams."

### Subhead patterns
- Quantified: "21x faster," "60% reduction," "Ship in 1 to 3 days"
- Specified audience: "Built for finance," "For sales teams"
- Specified primitive: "Postgres in seconds," "Containers across N regions"
- Direct clarification: a single sentence naming the unique angle

### Empty state patterns
- "Connect your first [thing] to start"
- "No [things] yet — start your first [action]"
- "Nothing here yet. [Path 1], or [Path 2]."
- "[Reason]. Try [recovery action]."

### Error message patterns
- "[Field] [missing problem]. [Specific fix]."
- "Couldn't [action]. [Recovery path]."
- "Try again, or [alternative]."

### Success state patterns
- "[Object] [past-tense verb]." ("Notes saved.")
- "[Count] [things] [verb]." ("50 points added.")
- "[State change]." ("Account ready.")

### Loading state patterns
- "One sec…"
- "Almost there"
- "Saving"
- "[Verb]-ing" (Loading, Saving, Sending)

### Banned phrases
- "Form contains errors"
- "Invalid input"
- "Something went wrong"
- "Oops!"
- "Please try again later"
- "We are experiencing technical difficulties"
- "Thank you for your patience"

### Banned marketing clichés
- Elevate
- Seamless
- Unleash
- Next-Gen
- Empower
- Revolutionize
- Transform (when used as marketing hype)
- Game-changer
- Best-in-class
- World-class
- Industry-leading
- Cutting-edge
- State-of-the-art
- Robust (applied to features)
- Powerful (as a descriptor)
- Smart (as a feature qualifier)
- Intelligent (as a feature qualifier)
- Delve (as a verb)
- Leverage (as a verb)
- Disruptive
- Innovative
- Game-changing
- Mission-critical
- Best-of-breed
- Synergize
- Holistic (when used as buzzword)
- Pivot (as marketing verb)

### Banned filler names
- John Doe
- Jane Smith
- Sarah Chan
- Jack Su
- Acme
- Acme Corp
- Nexus
- SmartFlow
- Vertex
- Apex
- Test User
- example@example.com
- Lorem Ipsum
- Your text here

Use creative, realistic-sounding names that fit the product's market.

### Banned filler numbers
- 99.99%
- 50%
- 100%
- 1234567
- Round numbers used as stats

Use organic, messy data: 47.2%, +1 (312) 847-1928, $8,247.30.

### Banned punctuation patterns
- Exclamation points in marketing copy
- ALL CAPS for emphasis in body
- Straight quotes
- Double-hyphens
- Three-dot ellipses written as three periods (use the ellipsis character …)
- Semicolons in marketing prose
- Question marks as faux-rhetorical setup
- Brand exclamation marks in error pages ("Oops!")

### Punctuation conventions
- Em-dash (—): pauses, asides (no spaces around)
- En-dash (–): numeric ranges
- Hyphen (-): compound words
- Curly quotes: ""
- Apostrophes: ' (not ')
- Period at end of short cadence headlines: acceptable
- Commas freely in conversation
- Three-dot ellipsis: …

### Voice scaling
- Marketing surface voice = in-product voice = error message voice
- Marketing voice does NOT get more formal at top of funnel
- Marketing voice does NOT get more casual at the bottom
- Voice stays consistent at hero scale and tooltip scale

### Microcopy conventions
- Microcopy carries personality, not jokes
- Microcopy is operational, not emotional
- Status labels: short, warm, human
- Button labels: complete the user's sentence
- Tooltips: brief, factual, no marketing
- Helper text: specific guidance, not generic encouragement

### Specificity rules
- Specifics over superlatives ("3 clicks" beats "easy")
- Specifics over hyperbole ("ship in 1-3 days" beats "ship fast")
- Specifics over abstraction ("Postgres" beats "data")
- Pair every claim with proof in the next sentence
- Quantifiers are claims (only use ones you can back)

### Headline / subhead jobs
- Eyebrow: names the section's role
- Headline: claims territory
- Subhead: clarifies with one specific detail
- Body: delivers proof
- Microcopy: comforts

Resist the temptation to make each layer do the others' jobs.

## Checklist (severity-tagged)

- [ ] All errors name the cause AND the fix (severity: Critical)
- [ ] No "form contains errors," "invalid input," "something went wrong" copy (severity: Critical)
- [ ] All empty states name the surface and the next action (severity: High)
- [ ] All success messages stay calm and brief (severity: High)
- [ ] Sentence case used for headlines (severity: Medium)
- [ ] No Title Case On Every Word (severity: Medium)
- [ ] No exclamation points in marketing copy (severity: High)
- [ ] No marketing clichés (Elevate, Seamless, Unleash, Next-Gen, Empower, Revolutionize) (severity: High)
- [ ] No filler names (John Doe, Acme Corp, Lorem Ipsum) (severity: High)
- [ ] No filler numbers (99.99%, 50%, round stats) (severity: High)
- [ ] CTAs are specific verbs, not "Get Started" reflexively (severity: High)
- [ ] No "Learn More" as primary CTA (severity: High)
- [ ] Active voice across all surfaces (severity: Medium)
- [ ] Numbers quantify in headlines and subheads (severity: High)
- [ ] No vague modifiers ("amazing," "powerful," "blazingly fast") (severity: High)
- [ ] Customer quotes attributed with name, title, company (severity: Medium)
- [ ] Customer quotes lead with the result, not praise (severity: Medium)
- [ ] AI feature copy uses augmentation framing ("drafts," "suggests," "helps") (severity: Medium)
- [ ] No replacement framing ("our AI writes for you") (severity: Medium)
- [ ] Validation runs on `blur`, not on every keystroke (severity: High)
- [ ] Toast uses `aria-live="polite"`, does not steal focus (severity: High)
- [ ] Toast auto-dismisses in 3 to 5 seconds (severity: Medium)
- [ ] Confirmation dialog before destructive actions, with both confirm and cancel visible (severity: Critical)
- [ ] Curly quotes used; no straight quotes (severity: Cosmetic)
- [ ] Em-dashes used correctly; no double-hyphens (severity: Cosmetic)
- [ ] Voice consistent across marketing, in-product, error, docs (severity: High)
- [ ] Feature names are nouns / noun-phrases, not adjective-stacks (severity: Medium)
- [ ] No "SECTION 01," "QUESTION 05" meta-labels (severity: High)
- [ ] Eyebrow labels in 10 to 13px tracked uppercase or sentence case (severity: Cosmetic)
- [ ] No emojis in any production copy (severity: Critical)
- [ ] No autoplay sound or video with sound (severity: Critical)
- [ ] No "we believe," "we're committed to," "our mission" corporate hedges in marketing copy (severity: Medium)
- [ ] Plain language; jargon only when audience has earned it (severity: Medium)
- [ ] Subheads clarify, never echo, the headline (severity: High)

## Related

- See **accessibility.md** for `aria-live`, `role="alert"`, focus management on errors.
- See **components.md** for button label, form label, modal copy contracts.
- See **typography.md** for the scale that carries the words.
- See **color.md** for semantic state colors that pair with error and success copy.
- See **motion.md** for toast entry / exit timing and skeleton loading patterns.
- See **interaction.md** for tactile feedback that accompanies microcopy.
- See **dashboards.md** for stat callout typography and tabular numeral discipline.
