Voice & content

Matter's voice is terse, declarative, developer-voiced — designed to read like a manual page, not a marketing site. The rules below are the contract every Matter surface follows: marketing pages, dashboard copy, error messages, OpenAPI descriptions, MDX docs, commit messages, agent prompts.

The voice page covers the deeper grammar. This page is the per-rule sweep, with examples paired do/don't.

The four foundational rules

These four rules carry the brand identity and override every other guideline when in conflict.

1. Never compare to other products.

No "Matter's analog of X." No "deliberate deviation from Y." No "mirrors Z's grammar." No "if you've used X, the shape will be familiar." No "borrowed from W's cookbook." Describe what Matter does plainly and self-contained.

Factual references to standards (WAI-ARIA roles, RFC 7807, OAuth 2.1, MCP) are fine. Framing Matter's design as a comparison to a named competitor product is not.

This rule applies in:

• Marketing copy
• Docs
• OpenAPI description fields
• README files
• Brand taglines
• SEO keywords
• Commit messages
• MDX page descriptions
• Agent system prompts

2. Active voice, second person.

The reader is the subject of every sentence. "You'll reach for Pill" not "Pill is reached for." "Send a POST to create an entity" not "Entities are created via POST."

3. Declarative, not promotional.

State what's true. Don't sell.

The dashboard, the API, and the marketing site all share this rule. No marketing-speak escapes into the product.

4. Sentence case, with two-word Title Case button labels.

Headings, page titles, eyebrows: sentence case.

Create your company.
Why Matter exists.
Pricing.

Two-word button labels and sidebar items: Title Case.

Get Started
Sign In
Read Docs

Multi-word headings or labels longer than two words: sentence case.

"Try Matter today" (button)            ← sentence case (3+ words)
"Get Started" (button)                  ← Title Case (2 words)
"Now shipping: programmable equity"     ← sentence case (heading)

Punctuation

Ellipsis: …, not ...

The single-character ellipsis is canonical. Three periods read as awkward whitespace and lose the typographic identity.

Loading…
Save changes…

The drift gate (planned, tranche 6) will fail CI on three-dot literals outside code fences.

Quotes: curly, not straight

"don't" not "don't". "first quarter" not "first quarter".

In source code, straight quotes are fine (const x = "value"). In prose, headlines, marketing copy, and product copy: curly.

Non-breaking space in measurements

10 MB, not 10 MB. The non-breaking space keeps the number and unit on the same line.

<!-- Right -->
<span>10&nbsp;MB</span>
<span>4&nbsp;weeks</span>
<span>5&nbsp;mins</span>

<!-- Wrong -->
<span>10 MB</span>

Apply to: file sizes, durations, distances, percentages adjacent to labels.

Loading states: ends with …

Loading…
Saving…
Fetching results…

Never:

Loading
Loading...
Loading.

Numerals vs. words

Use numerals for counts, dates, and quantities:

8 deployments     not "eight deployments"
3 days ago        not "three days ago"
Q3 2026           not "Third quarter twenty-twenty-six"

Exceptions: at the start of a sentence ("Three filings are pending."), and idiomatic phrases ("a few" / "several").

Buttons and links

Specific labels, not generic

Button text describes the action that happens. "Continue" is meaningless; "Save API Key" tells the user exactly what they're committing to.

Title Case for two-word buttons; sentence case for longer

"Get Started"          ← two words, Title Case
"Read Docs"            ← two words, Title Case
"Try Matter today"     ← three+ words, sentence case

Anchor text describes the destination

Read the API reference          ← describes destination
Click here for the API reference ← generic; fails screen-reader sweep

The screen-reader sweep (WIG navigation rule) flags "click here" anchors as low-information. Always describe what the destination is.

Error messages

Three-part structure:

1. What went wrong — one short sentence, plain language.
2. Why — when known, optional.
3. What to do next — a fix or a next step.

Couldn't save the grant. The strike price exceeds the latest 409A
valuation. Adjust the strike below $0.42, or upload a fresh 409A.

Not:

Error: invalid strike price.

Errors should never be just a code. Even API errors that surface rfc7807 problem details carry a detail field with the fix.

OpenAPI descriptions

Every operation in apps/docs/api-reference/openapi.yaml has a description. The rules:

• Active voice. "Create a new entity" not "An entity will be created."
• Second person where helpful ("You'll receive a webhook when the filing completes.").
• No comparisons to other APIs.
• Examples in code fences; not inline.
• Field-level explainers go in x-matter-explainer, not in description. The description stays one-line.

The OpenAPI authoring guide covers the deeper conventions.

MDX page descriptions

Every page's frontmatter description: is the OG / social-card preview. The rules:

• One to two sentences. No marketing voice.
• Lead with what the page does.
• Don't repeat the title.
• Compose tokens / components / patterns by name when relevant ("Six canonical breakpoints — xs / sm / md / lg / xl / 2xl…").

# Good
description: "Six canonical breakpoints — xs / sm / md / lg / xl / 2xl.
              Mobile-first min-width semantics. Use container queries where
              possible; reach for these only when the page-level layout
              itself needs to change."

# Bad
description: "Learn about breakpoints and how to make your site responsive
              with our cutting-edge responsive system."

Commit messages

Conventional Commits (feat:, fix:, refactor:, etc.) plus the same voice rules:

feat(components): Pill — add green tone for verified states

The verified status surface needs a tone distinct from indigo (in-progress)
and amber (warning). The green tone composes the matter-green family.

Not:

feat: Added a new color for Pill so users can see verified status

Page titles

The MDX title: frontmatter is the HTML <title> (with Matter prefix). Keep it short, sentence case, no marketing voice.

Brand names, code, identifiers

The renderer auto-wraps <code> in translate="no". Author MDX with backticks:

The entity `ent_a1b2c3` was registered Tuesday.

Renders with the identifier intact across every locale.

Brand names ("Matter", "Stripe Atlas" — when factually referencing) should be wrapped in <span translate="no">…</span> for non-code contexts.

Anti-patterns

Automated gates

The planned gates land in tranche 6 of the audit plan. Until then, voice + content review happens at PR time.

Reference

• Voice (long-form) — the deeper grammar and lifecycle vocabulary.
• Authoring rules — the page-level authoring conventions.
• Web Interface Guidelines / content — Matter mirrors the WIG content rules.
• CLAUDE.md voice section — the project's canonical voice rules.