Generic copy makes a well-styled page look generated. Specific copy makes a plain page look designed. Write copy before styling; keep it in src/content/*.ts so the HTML and the Markdown mirror stay in sync.
1. Headlines
Rules
- ≤ 10 words for H1 (fits 2–3 lines at 390px). H2 ≤ 12 words.
- Say what it does or what changes, for whom. A reader who sees only the H1 can explain the product.
- Concrete nouns and verbs. At least one of: a number, a named object (branch, invoice, standup), a named outcome (in 14 seconds, without a dashboard).
- No colon-splits ("X: The Y for Z") and no question headlines unless the page answers a real search question.
- Sentence case. End H1 with a period if it's a full sentence (Linear, Granola style); pick one convention for the site.
Formulas that work (measured on the teardown sites)
| Formula | Example |
|---|---|
| Outcome + time/number | "Deploy previews for every branch in 14 seconds." |
| Object + where it lives | "Feature flags that live in your repo." |
| Plain category claim (confident brands) | "The AI notepad for back-to-back meetings." (Granola) |
| Before → after | "Standups in 4 minutes, written by the tickets." |
| Two-tone: claim + explanation | "Built for review. Every change gets a link, a diff and a rollback." (Linear/Stripe pattern) |
| Poster statement (agency/portfolio) | "Brands that look like nobody else." (only with a portfolio that proves it) |
Before → after
| Generic | Specific |
|---|---|
| Revolutionize your workflow with AI | Turns a 40-minute incident review into a 3-paragraph summary |
| The future of payments | Accept cards, wallets and bank debits in 46 countries |
| Build faster, ship smarter | Every pull request gets its own database in under a second |
| Your all-in-one platform | Docs, tickets and on-call in one keyboard-first app |
| Designed for developers | Install with one command; configure with one YAML file |
2. Subheads and body
- Hero sub: 1–2 sentences, ≤ 2 lines at desktop (
max-w-[44ch]), adds the how or the proof the H1 didn't. - Section intro: one sentence. If you need three, the section has two jobs.
- Answer first. The first sentence of every section and FAQ answer states the answer; detail follows. This is also what AI search engines quote (
seo/references/content-for-citation.md). - One idea per paragraph, 1–3 sentences, active voice, second person ("you") or plain description; no "we believe".
- Numbers: digits, units, context and date. "Median build 14 s (Aug 2026, 1.2M builds)". Non-breaking space between number and unit in JSX:
14 s. - Name things the audience already knows (Postgres, Slack, GitHub) instead of abstract categories ("your tools").
- Cut adverbs and intensifiers: really, truly, seamlessly, effortlessly, incredibly.
3. Banned phrases (rewrite on sight)
unlock · supercharge · revolutionize · elevate · empower · seamless(ly) · effortless(ly) · cutting-edge · next-generation · game-changing · world-class · best-in-class · robust · leverage · synergy · the future of · all-in-one platform · take X to the next level · designed with you in mind · built for scale (without a number) · trusted by thousands (without names) · lightning-fast · blazing fast · magic / magical (unless it's a literal trick) · "Welcome to" as a headline · "Get started today" as a heading · emoji in headings or buttons
4. CTAs
- Verb + object, specific: "Start deploying", "Install the CLI", "Book a 20-min demo", "Read the quickstart". Not "Get started", "Learn more", "Submit".
- One primary CTA label per page, repeated exactly in the hero, header (short form ok) and closing band.
- Secondary action is a text link or ghost button, never a second filled button of equal weight.
- Say what happens: "Download for Mac (38 MB)", "Start free — no card".
- Developer products: a copyable command is often the best secondary CTA (
npx acme init).
5. Proof and the placeholder protocol
Only publish what exists. For every proof element, record where it came from.
| Proof | Needs | If missing |
|---|---|---|
| Customer logos | written permission, SVG from the customer's brand page | omit the strip |
| Quote | exact words, name, role, company, permission | omit, or TODO(content) box during dev |
| Metric | measurement method, date, source you can link | omit, or state it as a promise ("builds cached by default") |
| Rating / review count | real platform (G2, App Store) with link | omit (never in JSON-LD either) |
| Awards / press | link to the listing or article | omit |
| Screenshot | real product, staging data allowed, no fake data that implies customers | a clearly labeled mock of real UI |
| Team photos | real photos with consent | initials/avatars or omit |
Development placeholders are visible dashed boxes reading TODO(content): (markup in website §3). Never grey logo blocks, stock avatars, "John Doe", "Lorem ipsum", "10K+ users", "4.9★".
6. Structure that reads well to people and machines
- One
per page matching the page title's topic; section headings in order (h2 → h3). - Question-style H2s only where users ask questions (FAQ, docs, pricing). Answer in the first sentence below.
- Comparison or spec facts → a real
, not cards or images of text.
- Every key fact visible in HTML text (not only in images, tabs that require JS, or canvas).
- The first paragraph of the home page states what it is, for whom, and the main differentiator in ≤ 2 sentences (used for meta description and llms.txt summary in
src/site.config.ts).7. Microcopy and typography in text
…not...; curly quotes “ ” ‘ ’; en dash for ranges (9–5, 2024–2026); em dash sparingly;×for dimensions.- Keyboard shortcuts in
; platform symbol (⌘ vs Ctrl) resolved after mount. - Dates: absolute ("16 Sep 2026") on changelogs and posts; relative only in app UI.
- Buttons and nav: sentence case, 1–3 words. Labels (
label-mono): 1–4 words, uppercase via the utility only. - Error and empty states say what happened and what to do next ("No deploys yet. Push a branch to create one.").
- Legal/footer text
text-xs text-fg-subtle, but never below 12px.
8. Tone by direction
Direction Voice precision dry, exact, numbers, short sentences, developer nouns terminal imperative, lowercase commands, $prompts, zero marketing adjectives, real outputeditorial complete sentences, a point of view, longer paragraphs, italic decks swiss declarative statements, numbered sections, few words, big claims backed by a list warm friendly second person, plain words, reassurance with specifics ("works offline") instrument labels over sentences, units everywhere, status words (normal, degraded)