Grammar and mechanics

content specs/content/grammar-and-mechanics.kmd

Ratified mechanical rules: capitalization, punctuation, numbers, brand-name handling, abbreviations, Oxford comma. Removes the per-PR "should this title-case or sentence-case?" debate. Modeled after LeafyGreen, Polaris, Carbon mechanics specs.

When this spec applies

Primary triggers

All triggers

Spec — Grammar and mechanics

Status: v0.1.0 — Draft. Mandatory; CI lint hook (separate tooling ticket) may eventually enforce a subset against i18n JSON.

R1 — Capitalization

SurfaceCase
Button labelsSentence case (Save changes, not Save Changes)
Link labelsSentence case
Headings (H2, H3, …)Sentence case
Landing hero H1Title case allowed (Build Your Next App) — owner discretion
Brand namesAlways as-styled (Koder, Koder Talk, koder_kit, kdb-next)
Code identifiers in copyBackticks + as-typed (KoderButton, not Koder Button)
AcronymsAll-caps until they become standalone words (API, URL, OAuth not OAUTH)

R2 — Punctuation

  • Periods in buttons / cards / single-sentence body: NO. (Save not Save.)
  • Periods in 2+ sentence body: YES on each sentence.
  • Em-dash (—) preferred to en-dash (–) for parentheticals. NO spaces around em-dash. (Koder Talk — the chat app — is free.)
  • No semicolons in UI copy. Split into two sentences instead.
  • Apostrophes: curly (') in user-facing strings, straight (') in code. (i18n JSON values: curly. Code identifiers: straight.)
  • Quotation marks: curly ("…") in user-facing prose.
  • Ellipsis: single Unicode … (not ...) and ONLY when truly trailing off; never as "loading" placeholder (use skeleton).

R3 — Oxford comma

YES — always include the final comma in lists of three or more:

Configure your network, storage, and identity. ✅ Configure your network, storage and identity. ❌

R4 — Numbers

  • 1–9: spell out (One file selected).
  • 10+: digits (10 files selected).
  • Decimal point / thousand separator: locale-aware (en-US: 1,234.56; pt-BR: 1.234,56).
  • Time: 24-hour by locale default with 12-hour fallback per specs/i18n/contract.kmd.
  • Dates: locale-formatted by default; ISO YYYY-MM-DD accepted in technical surfaces.

R5 — Brand names

  • NEVER possessive (Koder Hub's catalog → the Koder Hub catalog).
  • NEVER plural (Koder Talks → Koder Talk channels).
  • Brand precedes generic (Koder Talk channel, not the channel Koder Talk).
  • Always title-cased as originally branded (koder_kit not Koder_Kit, kdb-next not KDB-NEXT).

R6 — Abbreviations

  • First use: spell out + abbreviation in parens (Multi-factor authentication (MFA)).
  • Subsequent uses: abbreviation alone.
  • In onboarding / first-run: never abbreviate jargon, even on first use.
  • Latin abbreviations FORBIDDEN in UI: use "for example" not "e.g.", "that is" not "i.e.", "and so on" not "etc."

R7 — Common pitfalls

WrongRight
Login (button)Log in (verb) / Login (noun is OK as label "Login page")
Setup (button)Set up (verb) / Setup (noun)
Email (verb)OK (lowercased, no hyphen)
Sign-in (verb)Sign in (verb)
Sign in (button when label is the noun)OK — context-dependent
Click hereNEVER — link text describes destination
Please …NEVER — "please" is filler
Don'tOK in friendly contexts; spell out Do not in legal / serious-warning copy

R8 — i18n

These rules govern English source strings. Translators adapt per-locale mechanics (e.g., Japanese has no Oxford comma; pt-BR uses period as thousand separator). Per specs/i18n/contract.kmd.

Não-escopo

  • Per-language style guides beyond baseline (per-locale spec if pursued).
  • Editorial style for marketing blog posts (owner-curated, see meta/brand/koder-design).
  • Code-style for code samples inside docs (separate spec).

References