Verdigris Design System

Convention

Codifies the antithesis-H1 typography pattern shipped across /integrations/* and /industries/* during SOV R8. Sourced from Apple HIG headline conventions, AP Stylebook headline rules, and the Wikipedia "Signs of AI writing" canon. See rules/visual-rules.yml > typography.h1_punctuation.

H1 Punctuation

The H1 is the page’s load-bearing typographic surface. Verdigris H1s often carry a two-part antithesis (“The meter said the load was flat. The waveform said it was not.”). The punctuation in that headline must not undermine the argument. This guide codifies what’s allowed.

Rule

  1. No em-dash (—) in any H1. Em-dashes in headlines are a 2024+ AI-generated-text tell. See Wikipedia, Signs of AI writing § Overuse of em dashes. Use a line break, period, or colon instead.

  2. No terminal period unless deliberate. Default to no terminal punctuation. Apple’s “Hello.” headlines (Macintosh 1984, iPhone, Apple Watch) demonstrate the period as a deliberate emphasis device — used on standalone one-word or two-word brand greetings, never on multi-clause sentences. AP Stylebook conventions and most newsroom style guides drop the period from multi-word headlines because headlines are display objects, not sentences. Permitted only when:
    • the entire H1 is one or two words and reads as a statement of arrival (“Hello.”, “Available.”, “Shipping.”), AND
    • the page has explicit design intent documented in the PR description.
  3. Antithesis H1s parse via line break, not punctuation. The canonical default is line break with no terminal punctuation. Mid-period and visual contrast are fallbacks for specific structural constraints; colon is for setup-and-turn (a distinct grammar from antithesis). In priority order:
    • Line break — canonical default. Antithesis clauses stack on separate lines, no punctuation between them. e.g. "The meter said the load was flat\nThe waveform said it was not". Apple, Stripe, Linear, Anthropic, GitHub, and Vercel all ship antithesis H1s as stacked lines, no punctuation. Use this unless a structural constraint prevents it. The renderer must support \n as a visible line break (e.g. whitespace-pre-line on the <h1> className) so that line breaks declared in YAML titles survive to render.
    • Visual contrast — enhancement layered on top of line-break. Weight or accent color on the second clause to amplify the turn. Not a standalone alternative to line break; use with the line break, not instead of it.
    • Colon — for setup-and-turn grammar (a distinct pattern from antithesis): “The signal is the answer: not the alarm”. Use when the second clause completes or qualifies the first, not when it contrasts.
    • Period mid-headline — fallback only. Permitted when the hero slot is structurally fixed-width and cannot accommodate two lines (e.g. dense card grid, search result row). Mark with explicit design-intent note in the PR. Avoid as default; the line break is research-aligned and the period is not.
  4. Em-dash inside the body of the page is acceptable in technical contexts (e.g. compound modifiers) but discouraged. See brand_rules.yml for body-copy thresholds. This rule applies only to the H1 surface.

Why

Headlines are read scanning, not parsing. A terminal period asks the eye to stop without instruction; an em-dash asks it to glide without rhythm. Neither serves a page that opens with an antithesis. The Apple H1 lineage (Mac 1984, iPhone 2007, Apple Watch 2014) earned the period as punctuation by using it in single-word display surfaces where the period is the statement. We don’t have that license on multi-clause SoV pages.

Compliant

H1 Why it works
The meter said the load was flat\nThe waveform said it was not (stacked lines, no punctuation between them) Canonical antithesis pattern. Line break carries the contrast. No mid-period, no terminal period. Apple/Stripe/Linear/Anthropic precedent.
Real signal in every kilowatt No punctuation. Headline as noun phrase.
Hello. One-word display surface, period as deliberate emphasis. Apple-style.
The signal is the answer: not the alarm Colon between setup and turn (not antithesis), no terminal punctuation.
The meter said the load was flat. The waveform said it was not. (rendered on a single line; fixed-width slot only) Fallback only. Mid-period is rule-compliant when the slot cannot accommodate two lines. Document the structural constraint in the PR.

Non-compliant

H1 Why it fails
The meter said the load was flat — the waveform said it was not. Em-dash between clauses. AI-tell. Use a line break or period instead.
Real signal in every kilowatt. Terminal period on multi-word noun phrase. Not Apple-style; reads as accidental, not deliberate.
Integrate with Schneider Electric EcoStruxure. Terminal period on imperative-with-product-name. Default to no terminal punctuation; the period adds no semantic content.
Detect — predict — prevent. Em-dashes as separators plus terminal period. Double violation.
Three pillars. One waveform. Every circuit. (rendered on a single line by default, no structural constraint) Mid-period antithesis used as default instead of line break. Rule-compliant but research-suboptimal; reach for the canonical line-break pattern instead.

Where this applies

Surface Scope
/integrations/* SoV pages Required. Enforced by rules/visual-rules.yml > typography.h1_punctuation.
/industries/* Required.
/platform/*, /hardware/* Required.
/resources/blog/* Recommended. Editorial nuance applies; one-word “Hello.-style” brand-greeting H1s may use a period.
Whitepaper covers (PDF) See categories/whitepapers/cover.md for cover-specific spec. The cover headline tier follows the same no-terminal-punctuation default.

Sources

  1. Apple Human Interface Guidelines — Writing. Apple’s headline tradition treats terminal periods as a deliberate emphasis device on one- or two-word display headlines. The pattern was established with the original Macintosh (“Hello.”) and re-used for iPhone, Apple Watch, and Vision Pro launches.
  2. Associated Press Stylebook — Headlines. AP headline convention drops the period from multi-word headlines; headlines are display objects, not complete sentences requiring full terminal punctuation.
  3. Wikipedia — Signs of AI writing (style category, “Overuse of em dashes,” section 4.4). Em-dash overuse is identified as a primary stylistic tell of 2024+ generative writing. Cited as one of the formatting markers that distinguishes machine-generated from typical human Wikipedia contributions.

See also