| name | docs-voice |
| description | Voice, tone, and format for the public Persist docs (`apps/docs`, built with Blume). Use when authoring or editing apps/docs prose โ landing, guides, concepts, recipes, adapters, reference โ or deciding headline grammar, benefit framing, competitor framing, or anti-sell wording. |
Docs voice โ Persist docs (apps/docs, built with Blume)
Keep landing, guides, concepts, recipes, adapters, and reference reading like one voice.
Voice in one line
Senior-dev to senior-dev: concrete, API-literate, dry, honest about scope. No
hype. The differentiators are radical honesty (say what's planned / diverges /
was rejected) and the "when not to use it" anti-sell โ keep both.
Do
- Lead with the pain, then the mechanism. "Async IndexedDB hydrates after
first paintโฆ" โ then "
toHydrationSignal + useHydrated gates the tree."
- Concrete before abstract. Name localStorage / IndexedDB / zustand /
TanStack Store before the coinage "seam" /
PersistableSource.
- Section headers by page type. Marketing = period-terminated benefit
sentence ("One middleware, any store."); guides = action verb ("Gate UI
until hydrated"); reference = precise noun; concepts = model noun +
consequence.
- Card titles = the outcome; card bodies = the API.
- One idea per sentence in leads. Short claim first, then expand.
- State experimental / pre-1.0 status once per surface, one wording (see
Canonical patterns).
- Sidebar icons: all-or-none per sibling list. Blume does not reserve an
icon column โ sparse
sidebar.icon jaggeds labels. Guides, Concepts,
Recipes, Reference leaves: none unless every peer has a natural glyph.
Section meta.ts icons and tab icons stay.
- Adapter / listing order: core โ backends โ codecs โ sources โ frameworks
โ transport. Within sources: tanstack-store โ zustand โ jotai โ valtio โ
mobx โ pinia โ redux โ custom. Within frameworks: react โ preact โ solid โ
angular โ vue โ lit โ alpine โ svelte (runes โ store).
Don't
- Don't open a page with a 60+ word sentence.
- Don't restate the frontmatter
description in the first body sentence โ the
docs site renders description as the page subtitle, so an echoing opener
duplicates content. Open with a concrete scenario/pain instead.
- Don't title cards with bare feature nouns ("Cross-tab") when the outcome is
the hook ("Sync tabs without a custom
storage listener").
- Don't manufacture social proof, download counts, "trusted by", or maturity
adjectives ("production-grade", "battle-tested", "world-class") at pre-1.0 โ
live examples, source, and the changelog are the proof.
- Don't claim Persist owns UI, focus, or a11y โ consumers own rendering; Persist
owns the persistence + hydration lifecycle.
- Don't hype ("blazing-fast", "revolutionary").
- Don't treat query-cache persisters as competitors โ peers are store
persist middlewares (zustand / redux / pinia). TanStack Store is an
integration, not a rival.
- Don't invent Lucide icons for prose nav leaves to "fill out" a section โ
strip to none instead of decorating half the list.
Canonical patterns (use verbatim)
- Experimental disclaimer (banner / pill / callout / stability page):
"Experimental โ the API may change between minor releases. Pin your version."
- Pre-1.0 semver: breaking changes are expected and ship in minor
releases (
0.1 โ 0.2), not majors.
- Brand one-liner (memorable beat, not hype): "Any store, any storage, one
middleware โ no flash."
- Competitor set: zustand-persist, redux-persist, pinia-persist (and
hand-rolled store persistence). Not TanStack Query persist-client.
Product tenets
Decisions and messaging should align with product-tenets.
Verify
content/** MDX is excluded from oxfmt; .astro is not oxfmt-managed. Build
green before commit (verify-after-each-step).
Scheduled drift sync: update-docs.
Reference
