Grammar and mechanics

mandatory

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.

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

R1 — Capitalization

Surface Case
Button labels Sentence case (Save changes, not Save Changes)
Link labels Sentence case
Headings (H2, H3, …) Sentence case
Landing hero H1 Title case allowed (Build Your Next App) — owner discretion
Brand names Always as-styled (Koder, Koder Talk, koder_kit, kdb-next)
Code identifiers in copy Backticks + as-typed (KoderButton, not Koder Button)
Acronyms All-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

Wrong Right
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 here NEVER — link text describes destination
Please … NEVER — "please" is filler
Don't OK 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).