UX-08 phase 2a: short, plain notifications, and a ratchet for the rest

Every HA notification the add-on raises now has a title of at most 5 everyday words and a one-sentence body; a red alarm may use three so no action is lost. The texts live in app/messages.py, the rule in STYLE.md, and the detail that moved out in DOCS.md "Notifications", which each body links to. No notification_id, trigger or cadence changed. test_messages.py enforces the rule on every notification, fails any notification worded outside app/messages.py, and ratchets the kinds not yet rewritten (rows, banners, refusals, logs, options) through a shrinking allowlist of 200. Six tests re-pinned from prose to meaning. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LyR88rXETvwhTgx6yHE39p
2026-09-27 01:00:54 +02:00
parent 2503de124e
commit 50ccea3dd7
13 changed files with 1170 additions and 185 deletions
@@ -0,0 +1,48 @@
+# STYLE.md - how user-facing text is written (UX-08)
+
+This applies to everything a home owner or installer reads: notifications, phone pushes, the add-on page, refusals, add-on log lines at WARNING and above, and the names and descriptions of options. It is enforced by `goodwe_controller/test_messages.py`. Kinds that have not been rewritten yet are on its allowlist, and that allowlist only shrinks.
+
+## 1. Shape
+- **Title**: at most 5 everyday words. It says what is wrong ("Meter reading may be stuck"). No "GoodWe:" prefix, no full stop.
+- **Body**: **one sentence** of at most 25 words, saying what happened and what to do. A **red alarm** may use up to **3 sentences** (70 words, each sentence at most 30 words), so that no action a person must take is lost.
+- **Details**: the last line links to the add-on documentation and names the section with the rest: `Details: add-on documentation, section "<title>" under Notifications.` Background, figures, reason codes and history go there or into the log, never into the body.
+- **Status row**: at most 15 words. **Banner**: at most 12 words. **Refusal**: at most 30 words, naming the setting by its label. **Option name**: at most 6 words, not counting the group prefix. **Option description**: at most 30 words. Where a value comes from belongs in DOCS.md.
+- **Log line** (WARNING/ERROR): one line, at most 25 words. The reasoning goes on a DEBUG line. Log lines stay in English and are not translated.
+- **Sentences**: one idea each, active voice, present tense, with nothing nested in brackets. These translate well into Dutch and French.
+
+## 2. Numbers
+Use a number only if it helps the reader act, for example the peak limit, or what was asked and what was sent in a fault report. Write it the way `app/messages.py` does: `5 000 W`, `20 %`, `10 minutes`, `14:05`.
+
+## 3. Severity
+Severity is shown by the title and the colour, never by CAPITALS or by words like "BUG SIGNAL".
+
+| Level | Colour | When |
+|---|---|---|
+| alarm | red | Control stopped, money or energy lost now, a fault, or a person must act now. Up to 3 sentences. |
+| warning | orange | Control is still running, but something needs a look. 1 sentence. |
+| info | grey | No action needed. 1 sentence. |
+| resolved | green | An earlier alarm or warning has cleared. 1 sentence. |
+
+A rewrite never changes an alarm's severity, `notification_id` or cadence.
+
+## 4. Words - the same word for the same thing everywhere
+| Say | Not |
+|---|---|
+| battery | pack, BMS pack |
+| inverter, or its name | unit, device, actuator |
+| controller | loop, planner |
+| meter | P1 feed, telegram |
+| peak limit / this month's peak | ceiling, capaciteitstarief, billed quarter |
+| 15-minute period | quarter |
+| battery level | SoC, state of charge |
+| cut-out level | BMS floor, `bms_soc_floor` |
+| peak reserve | `peak_soc_floor`, EMS floor |
+| inverter rating | `max_w`, rail |
+| control is stopped / every inverter is set to 0 W | failsafe, trip, latch, parked |
+| software fault | BUG SIGNAL |
+| control board | master, ESP32 |
+| shadow mode | a mode that makes every decision but commands 0 W. The name is kept. |
+
+**Banned in titles and bodies** (the test fails on them): SAFETY-/TARIFF-/TEL-/CFG-/FW-/HW-nn and other card ids, integrator, anti-windup, windup, clamp, clamped, saturated, BUG SIGNAL, latch, latched, arbiter, allocator, register, `0x…`, layer 1/2/3, heartbeat, watchdog, telegram, ACK, CRC, OTA, Modbus, planner, `§n`, file names, IP addresses, option keys in snake_case, **HA entity ids**, and runs of 2 or more CAPITALISED words.
+
+HA entity ids are allowed only in refusals and validator messages, where the installer has to find that entity. They are never allowed in alarms or status rows.