Copy: pare product claims to what we can certify, cut rule-of-three cadence, record arch 10 §10

This commit is contained in:
2026-06-26 23:09:47 +03:00
parent c19857b0a7
commit 43d3b480d9
7 changed files with 92 additions and 35 deletions
@@ -683,6 +683,39 @@ choice isn't re-litigated per surface:
_(Consulted via /council → WAI-ARIA APG tabs/accordion/disclosure, IBM Carbon
accordion usage, NN/g #6/#8.)_
## 10. Product claims & promise copy
Declarative copy — the landing, the About modal, onboarding, empty-state value props —
makes **claims** about the product, not just feedback about an action. The care the §3
triad gives error wording applies here too: **say only what we can certify, and say it
once.** An overstated claim reads as insecurity, and the first time a user catches one
being false it costs more trust than the claim ever bought (NN/g credibility; GOV.UK
"don't oversell"). The test is not modesty for its own sake — it is that every sentence
survives a skeptical reading.
- **Claim what we can certify — not the future, not what we don't control.** "No account,
no server" is structural and always true (there is no backend). "Never leave your machine"
is a vow over every future build and every edge case; state the posture instead — "stored
locally on your device; there's no server to send them to."
- **No absolutes.** _never · always · fully · entirely · everything._ One edge case or one
future feature falsifies them, and the reader feels the overreach even when it happens to
hold. Prefer the scoped form: "works offline" over "fully offline"; "your library lives in
the browser" over "everything lives in the browser."
- **Don't promise durability the platform doesn't back.** Browser storage (IndexedDB, no
`persist()`) is best-effort and the browser may evict it. A chart is **saved**, not kept
forever — route the permanence claim through **export**, which is the real backup.
- **State a posture once per surface.** Repeating "local / no account / no server / offline"
across the hero, the lede, and a feature grid is three chances to sound unsure of it. Give
the posture one home and let the other surfaces describe the product.
- **Match the register, and don't under-sell.** Astrolabe is a free, spare-time tool: the
voice is plain and matter-of-fact, not manifesto. But concrete, true capabilities —
portable Vega-Lite JSON, two authoring modes, custom themes — are claims worth making
plainly. Reducing promises means cutting the _uncertain_ ones, never the real ones.
SOUL.md §"Local-Only by Default" is the internal **intent** and may be absolute; this
section governs how that intent is **phrased to users**, where the promise should be only as
strong as we can keep.
---
## Do / Don't
@@ -694,6 +727,8 @@ accordion usage, NN/g #6/#8.)_
- Adopt the APG keyboard pattern for new widgets; route all global keys through the one
router.
- Mark **optional** fields, not required ones (GOV.UK) — e.g. "Comment (optional)".
- In product claims, say only what we can certify, once per surface; route durability
through export.
- Consult `/council` when this contract is silent — then record the answer back here.
**Don't**
@@ -709,3 +744,5 @@ accordion usage, NN/g #6/#8.)_
- Don't ship a **dead disabled control** as a placeholder for an unbuilt feature — a
disabled button explains nothing and is skipped by assistive tech (GOV.UK, NN/g). Omit the
action until it works, then show it enabled (e.g. "Build Chart" appears with M4).
- Don't use absolutes in product claims (never/always/fully/everything) or promise what the
platform can't keep — say "saved," not "permanent."