mirror of
https://github.com/olehomelchenko/astrolabe.git
synced 2026-08-08 02:02:33 +00:00
Copy: pare product claims to what we can certify, cut rule-of-three cadence, record arch 10 §10
This commit is contained in:
@@ -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."
|
||||
|
||||
Reference in New Issue
Block a user