# site-ng writing style

Conventions for user-facing text on arpartsfinder.com (site-ng).
Applies to template content, flash messages, email bodies, page
copy. Internal code comments and design docs can follow their own
rhythm.

## Punctuation

### No em-dashes or en-dashes

Avoid `—` (em-dash, U+2014) and `–` (en-dash, U+2013) in user-facing
text. Em-dashes have become a strong "this was written by an LLM"
tell; even when grammatically correct they read as non-human.

Replace each occurrence with the closest natural English equivalent,
chosen per context. **Do not mechanically substitute `—` → `,` or
`—` → `:`.** The replacement should read naturally as the writer's
own sentence, not a still-dashed sentence with a different character.

Common substitutions:

| When the dash is used for... | Reach for instead |
|---|---|
| A parenthetical aside (`X — Y — Z`) | A pair of commas, parentheses, or a new sentence |
| Emphasis or explanation (`X — Y`) | A colon, a comma, or a new sentence |
| Range (`2 — 3`) | `2 to 3` (or just hyphen `2-3`) |
| Pause or interruption | A period, a comma, or a parenthesis |

When in doubt, default to a period and a new sentence. Short
sentences read crisper than long ones held together by dashes.

### What's still fine

- Hyphens in compound modifiers (`in-stock`, `out-of-stock`, `AR-15`)
- Hyphens in URLs, slugs, model numbers, etc.
- Mathematical minus signs (`−` in price deltas like `↓ $4.50`)

## Voice

- Direct, not corporate. "Sign in" not "Login".
- "We" for actions arpartsfinder.com takes; "You" for the visitor.
- Lowercase nouns that aren't proper (AR-15, ARPartsFinder, jump.cgi
  ARE proper; "browse", "build", "save", "draft" are not).
- "Build" (the user's kit) is the canonical term, not "kit", "list",
  or "cart". "Draft build" for in-browser working state; "saved build"
  for persistent /b/<code> rows. See memory: builds-vs-drafts-model.

## Terminology consistency

Cross-references for canonical phrasing:

- "AR-15 & AR-10" (we cover both platforms)
- "in stock" (two words, no hyphen) for the noun phrase
- "in-stock" (hyphenated) when used as a modifier
- "out of stock" / "out-of-stock" (same rule)
- "jump.cgi" lowercase, as a proper name
- "Build #N" capitalized (it IS the name of the build)
- "My Builds" capitalized (it's the section name in the nav)

## Brand spelling

The brand is **`ARPartsFinder`** — one word, three internal caps. Never
split into three words ("AR Parts Finder"), never two ("AR PartsFinder"),
never lowercased mid-stem ("Arpartsfinder", "arpartsfinder.com" is the
domain only).

Applies to: `<title>` tags, page copy, flash messages, email bodies,
alt text, anywhere a human reads it. The domain `arpartsfinder.com` is
the exception (domains are lowercase by convention).

If a piece of copy doesn't match these, fix the copy, not the
convention.

## JavaScript placement

**Default home for new JS is `ngsite/static/js/base.js`.** It's loaded
on every page (referenced once in `base.html` via
`<script src="{{ static_v('js/base.js') }}" defer></script>`), browser-
cached after the first visit, and the `defer` plus document-level
event delegation means it survives htmx OOB swaps without rebinding.
Any handler that could conceivably apply across pages goes there.

**Page-specific JS file** (`static/js/browse.js`, future
`static/js/build.js`, etc.) only when the JS touches DOM that only
exists on that page — e.g. `browse.js`'s retailer popover logic
references checkboxes and chips that don't render on `/build` or
`/changelog`.

**Inline `<script>` in a template** only for one of these:

1. **Pre-paint critical code** that must run before any content renders
   to avoid FOUC. Currently exactly two cases in `base.html`:
   - Dark-mode + cards-vs-table preference (lines 25-43) — sets the
     `dark` / `view-table` classes on `<html>` before paint.
   - `tailwind.config = { darkMode: 'class' }` (lines 45-47) — must
     run after the Tailwind CDN script defines `window.tailwind`,
     before any element with a `dark:` variant renders.
2. **JS that uses Jinja `{{ }}` interpolation** to inject server data.
   Even then, prefer rendering the data into a `data-*` attribute on
   a DOM element and reading it from the cached external JS file.
   Inline interpolated JS is a fallback when the data shape genuinely
   can't be passed via attrs.

**Cache busting** is wired via the `static_v` Jinja helper (defined in
`ngsite/__init__.py`). Every reference to a static JS or CSS asset
should go through it:

```html
<script src="{{ static_v('js/base.js') }}" defer></script>
```

The helper appends `?v=<mtime>` so file changes invalidate the cached
copy in visitors' browsers automatically — no hard refresh required
when shipping a JS change.

**When extracting an existing inline block:**
1. Read the `<script>` body for Jinja interpolation. If clean
   (no `{{ }}` / `{% %}`), extraction is a pure move.
2. Decide between `base.js` (site-wide) and a page-specific file based
   on whether other pages would want the same handler.
3. Replace the inline `<script>...</script>` block with a single
   `<script src="{{ static_v('js/<name>.js') }}" defer></script>`.
4. Verify on dev: page returns HTTP 200, the file serves with
   `Content-Type: application/javascript`, behavior is unchanged.

**Reference commits** for the pattern in practice:
- `f809038` — extracted `/browse` JS to `static/js/browse.js` +
  introduced the `static_v` cache-buster helper.
- `47d2145` — extracted `base.html` site-wide IIFE to
  `static/js/base.js`.

## Pre-commit smoke test

Before any commit that touches site-ng view code, query code, or
templates, run:

```bash
bash site-ng/scripts/smoke.sh
```

It curls ~14 representative URLs (home, /faq, /changelog, /browse
with type / include / exclude filters, all four /instock/<slug>,
/build, /my-builds, /login) against the dev server and asserts each
returns 2xx or 3xx. Anything else is flagged red and the script exits
non-zero. Catches regressions like shared-state shape changes (e.g.,
adding a new key to a filter dict but missing the inert dict
elsewhere) before they ship.

Chain it into your commit flow so the commit only runs if smoke passes:

```bash
bash site-ng/scripts/smoke.sh && git commit -F /tmp/msg.txt && git push
```

The script is fast (~3 seconds against dev), so the cost is trivial
compared to the cost of pushing a broken site at end-of-day and not
noticing until the next morning. Extend the PATHS array as new code
paths land — rule of thumb is one URL per distinct shape, not one
per page.
