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.

Spec — Grammar and mechanics

*tatus* 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 asstyled (Koder, Koder Talk, koder_kit, `kdbnext`)
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

  • *eriods in buttons / cards / single-sentence body* NO. (Save not Save.)
  • *eriods in 2+ sentence body* YES on each sentence.
  • *mdash (—)*preferred to endash (–) for parentheticals. NO spaces around em-dash. (Koder Talk — the chat app — is free.)
  • *o semicolons in UI copy.*Split into two sentences instead.
  • *postrophes* curly (') in user-facing strings, straight (') in code. (i18n JSON values: curly. Code identifiers: straight.)
  • *uotation marks* curly ("…") in user-facing prose.
  • *llipsis* 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: localeaware (enUS: 1,234.56; pt-BR: 1.234,56).
  • Time: 24hour by locale default with 12hour fallback per specs/i18n/contract.kmd.
  • Dates: localeformatted by default; ISO `YYYYMM-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 titlecased as originally branded (koder_kit not Koder_Kit, `kdbnext 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

  • Perlanguage style guides beyond baseline (perlocale 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).

Source: ../home/koder/dev/koder/meta/docs/stack/specs/content/grammar-and-mechanics.kmd