Tools-pages style guide

Style rules for /tools/* pages and their supporting components in this repo (weather-flower, dice-roller, future tools). Covers prose, changelog writing, and other cross-tool conventions.

Versioning rules and same-day consolidation are documented in each tool’s changelog.js header comment — they aren’t repeated here. This guide is about how to write the entries, not how to number them.

Changelogs

Tense

Past tense. The changelog describes work that has been done — “added”, “fixed”, “renamed”, “broadened” — not work in progress and not “we add” / “the patch adds”. This applies to summaries, top-level bullets, and sub-bullets equally.

One topic per bullet

Each top-level bullet covers one topic. “What changed” and “what stayed the same as a deliberate decision” are two topics, not one. If you find yourself joining two ideas with “Also…” or starting a new sentence that introduces a distinct change, split it into a new bullet.

Sub-bullets

When a top-level bullet describes a category of work with multiple sub-categories (e.g. several kinds of prose change, several kinds of configuration update), break those out as sub-bullets via the { text, children } shape.

Each sub-bullet follows this shape:

Category clause, past tense. Optional colon, then 2–3 illustrative examples, then etc. if the list is longer in reality.

Rules for sub-bullets:

• Lead with a category clause that names what kind of change before showing examples. Don’t drop the reader into the data.
• Examples are illustrative, not exhaustive. Pick 2–3 that teach the pattern; use “etc.” to acknowledge the rest. The complete list lives in the diff.
• Parallel structure across siblings. All sub-bullets in a list should share a shape (e.g. all ” : …”). Inconsistent shapes make the list harder to scan.

No trailing metrics

Don’t close a bullet with “100 lines edited” / “across all six biomes” / “no calibration shift”. Scope claims belong to the summary or the parent bullet. A sub-bullet that ends with a metric is signalling it’s been asked to do two jobs.

Worked example: changelog sub-bullets

Bad:

"`village` → `settlement` / `local` / `the centre`; `village green` → `the green`; `the lord's reeve` → `the reeve`; `lord's men` → `the watch`; `manor's [X]` → `the [X]`. Fixed counts went scale-relative: `twenty-three` → `into the dozens`. Singular nouns broadened: `the village dog` → `the dogs`. Preserved: parish, priest, diocese, bishop, chronicler, abbey, chapter-house, church, cathedral; tavern, innkeeper, blacksmith, smithy, cooper, verger, steward, apothecary, chandler, miller; `lower quarter` / `upper quarter`; `the lord`. 100 lines edited across all ten effect blocks; no calibration shift, only prose framing."

Three problems: one bullet doing four jobs, exhaustive lists, trailing metrics.

Good:

{
  text: "**Cross-infrastructure prose neutralization**. ...",
  children: [
    "Settlement-specific language was generalized: `village` → `settlement` / `local` / `the centre`, `the lord's reeve` → `the reeve`, etc.",
    "Specific numbers were scaled appropriately: `eighty-six out of seven hundred` → `over a tenth of the surviving population`, `fourteen people` → `over a dozen`, etc.",
    "Singular nouns were broadened: `the village dog` → `the dogs`, `village girls` → `householders`, `village healer` → `the healer`.",
    "Scale-flexible vocabulary was preserved: parish, priest, chronicler, abbey, church, cathedral (religious vocabulary); tavern, innkeeper, blacksmith, smithy (occupations at every scale); `the lord` (fantasy-generic noble figure).",
  ],
}

Each sub-bullet names its category, shows a few examples with “etc.” where the real list is longer, and shares a ” was/were ” shape with its siblings. Past tense throughout. The scope claim (100 lines, no calibration shift) belongs to the parent bullet or the summary, not down here.

Weather flower — petal descriptions

The description: field on each petal in src/data/weather/<biome>/<season>.yaml renders inside the Today’s Forecast card as italic Crimson Pro at 13px, ~260px column width (about 40–45 characters per line). The card has a fixed visual envelope; descriptions outside that envelope shift the card’s height as the GM rolls through weather, breaking the panel’s visual rhythm.

Target length: 110–180 characters

• Upper bound 180 keeps the description inside the card’s reserved space. Above this the panel starts to push other elements down visibly.
• Lower bound 110 is a soft floor — terser is fine where the petal is doing low-key work. Don’t pad to reach 110.
• Median lands around 130 in the current catalogue; aim for that band when writing new petals.

What to keep in a description

• The petal’s sky-and-air image — the one or two distinctive phrases that tell the GM what kind of weather this is. (“Heat-haze on the horizon at midday; the sky a pale washed blue from dawn to dusk.”)
• A physical signature the GM can describe at the table — what’s in the air, what the light looks like, what’s underfoot.

What to leave out

• Community / adaptation response. That belongs in the cue card’s Conditions or Scene Beats fields, not the petal description. (“The village shutters early” → strip; it’s not a sky condition.)
• Mechanical claims. DCs, movement penalties, visibility ranges. Those belong in Challenges and Movement & Visibility on the cue card.
• Historical or cultural backstory unless it IS the core image. (“The Polish-Slavic name for…” can stay if the etymology is the petal’s identity; trim if it’s flavour overlay on a description that has its own image.)
• Time / duration language. Setting describes the now. (“Heat that has held for weeks” → describe the current heat.) Same rule applies to the cue card’s Setting field; petal descriptions are the GM-facing twin.