docs-voice

name	docs-voice
description	Voice, tone, and format for the public Layers docs (`apps/docs`, built with Blume). Use when authoring or editing apps/docs prose — landing, guides, concepts, adapters, reference — or deciding headline grammar, benefit framing, the experimental disclaimer wording, or overlay-vs-layer usage.

Docs voice — Layers docs (apps/docs, built with Blume)

Keep landing, guides, concepts, 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. "Stop prop-drilling isOpen…" → then "open a layer from anywhere and await a typed result."
• Concrete before abstract. Name modals / drawers / toasts / confirms before the coinage "layer" / "overlay".
• Section headers by page type. Marketing = period-terminated benefit sentence ("Every adapter, the same API."); guides = action verb ("Configure serial scope"); 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.
• Keep // ^? type twoslash hints and live demos — proof, not decoration.
• State experimental 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 and fakes hierarchy. Leaf icons only where every peer has a natural glyph (adapter/integration brand SVGs). Guides, Concepts, Examples, Reference leaves: none. Section meta.ts icons and tab icons stay. Nested brand groups (e.g. Svelte): icon on the group only — don't repeat the same SVG on indented children.
• Adapter list order: core/vanilla → react → preact → solid → angular → vue → lit → alpine → svelte (runes → store). Every multi-adapter listing.

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 ("Named stacks") when the outcome is the hook.
• Don't manufacture social proof, download counts, "trusted by", or maturity adjectives ("production-grade", "battle-tested", "world-class") at v0.1.0 — live demos, source, and the changelog are the proof.
• Don't call the core accessible / portal-aware / UI-complete — consumers own rendering, focus, portals, and a11y. Say "state coordination, not UI ownership".
• Don't hype ("blazing-fast", "revolutionary").
• Don't oscillate "layer" (the API unit) and "overlay" (the category) — see apps/docs/content/concepts/glossary.mdx.
• 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): "Modals are just async functions you forgot to await."
• Overlay vs layer: "overlay" = the UI category; "layer" = Layers' unit / API term.

Verify

content/** MDX is excluded from oxfmt; .astro is not oxfmt-managed. Build green before commit (verify-after-each-step, update-docs).