Writing Style & Quality Bar

How every page here is written. This is a standard, not a suggestion — the QC checklist at the bottom is a gate, not a vibe. Capabilities (plugins, components, tokens) live in Site Authoring Capabilities; this page is the voice + structure.

Provenance

Adapted from the “Ward” documentation standard. Its principles (density, action-first, numbered steps, QC gate, anti-patterns) are kept. Its Notion-specific mechanics are translated, not dropped: Ward’s color-coded heading backgrounds become the editorial heading hierarchy below (a tiered band system in the brand palette, not 6 clashing colors); its callout color codes become Starlight admonitions; its toggles become <details>.

Voice

• Concise, high density. Every word earns its place. Cut filler (“in order to” → “to”).
• Active voice, action-first. Lead with the action, then the why if it’s not obvious.
• Short paragraphs — 2–3 sentences max. Walls of text are a defect.
• Sparing emoji. This is an editorial site, not a Notion page. An occasional sidebar icon is fine; emoji-per-bullet is not.
• Reuse before you write. Check existing docs, _INBOX/2-Research/, and existing components/templates before authoring something new.

Structure

1. Numbered steps for any procedure. If text introduces an action, it’s a numbered step — not a bare heading.
2. Sub-steps are indented numbered lists under their parent step.
3. Dividers (---) between major H2 sections and after an opening summary callout.
4. Numbered lists by default; bullets sparingly (use bullets for unordered sets, numbers for sequences).
5. Lead each page with one or two sentences of what it is and who it’s for.

Heading hierarchy

This is the on-brand translation of Ward’s colored heading backgrounds. You do not add colors yourself — the theme styles each Markdown level automatically (theme.css §3), so heading depth reads at a glance without garish per-level color tags:

Level	Renders as	Use for
# H1	Big editorial display (the page title — usually from frontmatter)	One per page. Don’t hand-write a second #.
## H2	Teal “section band” — accent rail + a faint left-anchored wash	Major sections (Ward’s H1/H2 role).
### H3	Gold accent bar	Sub-sections under an H2.
#### H4	Muted-strong kicker (deliberately plain)	Rare. Its plainness is a signal to restructure rather than nest deeper.

Rules:

1. Never skip a level (no ## → ####). Depth must be earned.
2. One # per page. Subsequent sections start at ##.
3. If you reach for #### often, split the page — deep nesting is the docs-site equivalent of Ward’s “H5/H6 = restructure” signal.
4. Don’t fake heading color with inline HTML/styles. The level is the color. For an emphasised callout, use an admonition (below), not a tinted heading.

Starlight mechanics (use these, not Notion-isms)

Ward’s color-coded callouts and toggles map to native Starlight features (heading colors are handled by the hierarchy above):

You want	Use	Not
Emphasis box	:::note / :::tip / :::caution / :::danger (or > [!NOTE] via starlight-github-alerts)	Inline-tinted headings / Notion color tags
Status on a heading/page	status: current|target|future|draft (heading badges)	Manual color tags
Collapsible / optional detail	<details><summary>…</summary>…</details>	Notion toggles
Brand color anywhere	a --zaj-* / --sl-* token	Hardcoded hex
Diagram	Mermaid fence or a diagrams/*.astro SVG	Pasted raster screenshot of a diagram
Hub of links / a CTA	<CardGrid> + <LinkCard> / <LinkButton> (.mdx)	A bare bullet list of links on a landing page
Per-tool alternatives (npm/pnpm, IDEs, envs)	<Tabs> / <PackageManagers> (.mdx)	Repeating near-identical blocks
A tight numbered procedure	<Steps> wrapping an <ol> (.mdx)	Bare headings as fake steps
Directory / file structure	<FileTree> (.mdx)	Hand-drawn ASCII tree

Admonition mapping (from Ward’s callout colors): info/highlight → :::note or :::tip; warning → :::caution; critical/blocker → :::danger; success/next-step → :::tip.

Built-in components beat raw markup — but only when they’re clearer. The full gallery and regression checklist is the Component library (skim it after editing tokens/theme). Components render only in .mdx: rename .md→.mdx (same slug) and add import … from '@astrojs/starlight/components'. A ## section that carries its own prose + code is a section, not a <Steps> item — don’t force it.

Code blocks

• Always set the language for highlighting.
• Add # Expected: to show expected output, # Note: for context.
• Inside a numbered step, indent the fence so it doesn’t break the numbering.

cd app
npm run build   # Expected: build completes, Pagefind index generated, exit 0

Frontmatter completeness

Fill every relevant frontmatter field (the docs-site analogue of “fill all fields”): title, description, sidebar (order/label/badge), and the optional taxonomy where it applies — tags, kind, status, plus playbook/template fields. Unknown-but-needed → leave it out rather than guessing; don’t ship a placeholder string.

Security

Never put secrets in docs — no API keys, license/purchase codes, tokens, passwords, or real credentials in prose, code blocks, or frontmatter. Use clearly-marked placeholders (<YOUR_TOKEN>) and reference a secrets manager.

Pre-publish QC checklist (the gate)

Run this before declaring a page done. The build is part of it.

• Leads with what-it-is / who-it’s-for in 1–2 sentences.
• Heading levels are sequential (one #, no skipped levels, #### is rare) — depth carries the hierarchy; no inline-tinted/faked headings.
• Every procedure uses numbered steps, not bare headings.
• Paragraphs are 2–3 sentences; no walls of text.
• --- dividers between major sections.
• Admonitions (:::note/tip/caution/danger) used for key info — correct type, not decoration.
• On .mdx pages, used built-in components where they beat raw markdown (CardGrid/LinkCard hubs, Steps, Tabs/PackageManagers, FileTree) — see the Component library; didn’t force one where prose or a table is clearer.
• No hardcoded colors; any visual themes via tokens and works in light and dark.
• Diagrams are Mermaid or a diagrams/*.astro SVG (themed, responsive viewBox, role/title/desc) — never a screenshot of a diagram. See AGENTS.md → “Custom visuals & components”.
• Relevant frontmatter filled (title, description, sidebar, tags/kind/status where applicable).
• No secrets anywhere.
• Internal links resolve; cd app && npm run build is green (starlight-links-validator enforces links).

Anti-patterns (do not ship)

• Walls of text; actions buried inside prose instead of numbered steps.
• Skipped heading levels, multiple # per page, or faking a heading’s emphasis with inline color/HTML instead of using the level + an admonition.
• Emoji-per-bullet / Notion-style decoration on a public editorial page.
• Hardcoded hex colors, or a visual that breaks in dark mode.
• A pasted screenshot where a Mermaid or SVG diagram belongs.
• Inventing a category (e.g. guides/) instead of using the live topics.
• Referencing an installed-but-unwired plugin as if it works (see capabilities).
• Over-engineering: a custom component when a Mermaid fence or admonition does the job.