Format: vision paper

First entry in the formats library (9 - System/ui-ux/formats/). A format is a reusable document archetype - a fixed anatomy plus a rule for when to reach for it - distinct from the house kit (documentation-kit.css, the shared tokens and blocks every format is built from) and from a one-off page.

Reference build: template.html in this folder. Sample content ("A vision for didactic government documents") is house material, not a real publication - copy the file, replace the words, keep the shape.

What it is

A vision paper is one long, scrollable document that argues a single thesis, then walks it through a fixed number of numbered sections, each opening with a short summary before the detail. It reads start to finish, like an essay, not like a dashboard or a reference manual. The reader is expected to stay on the page for minutes, not seconds.

It generalises the long-form vision/manifesto page: a public body or team sets out a position (why we believe X, what we will do about it) and wants it read as an argument, with evidence, not skimmed as a spec.

When to reach for it

Rule of thumb: if the page's job is to be argued and read, use the vision paper. If its job is to be looked up, use the compendium or a documentation page with the on-this-page rail. The vision paper deliberately refuses that rail - see below.

Anatomy

1. Thin header - sticky, one line: wordmark left, two plain text nav links right (Contents, Authors). No logo art, no menu.
2. Hero - kicker label, document title, one-line dek, a plain Start reading → text link. Not a marketing headline, not a button.
3. Lead / abstract strip - date, authors and format in a narrow left column; the abstract paragraph beside it. One hairline rule above and below, no card, no shadow.
4. Jump to section - one <details> control, centred, closed by default. Opens a plain numbered list of the section titles. This is deliberately not the kit's .on-this-page sidebar: a vision paper is read in order, not browsed, so it gets one small control instead of a permanent rail competing with the text for width.
5. Numbered sections - five is the house default (fewer reads thin, more asks too much of one sitting). Each section is a kit's details.doc-section, opens with a TL;DR summary box (.callout, no colour modifier - grey, never tinted), then subsections.
6. Pull-quotes - sparing, one or two for the whole paper, never one per section. A short attributed sentence, not a slogan.
7. Inline citations - a normal accent-coloured link inside the sentence that needs it. No footnote numbers, no endnote list.
8. Authors / contributors block - plain list of roles near the end, before the footer.
9. Footer - plain, light, one hairline top border. No colour fill.

House adaptations (do not build this format any other way)

• Light theme only. No dark hero, no dark footer. The public long-form vision-paper page this generalises uses a saturated colour band across its footer; the house version drops that entirely - footer is plain paper background with a hairline top border, same as every other house page.
• Hero stays small. Title, one-line dek, one text link. No pill buttons, no stacked CTAs, no marketing energy. The hero's job is to name the document, not to sell it.
• Grayscale-first, one accent. The TL;DR box is the kit's default .callout (grey, --ink-soft border) - never .info/.warning/ .success. Table headers are untinted (kit default). The single accent (--accent) appears only on links, the current nav state and the pull quote's rule - never as a section-colour system.
• Reading column, not full width. Unlike house working documents/boards (which run full container width per feedback_html_output_rules.md rule 16), a vision paper is a continuous read: the whole body is capped at --measure-prose (68ch) inside a wider fixed header, matching the ≤65–72ch prose rule. This is the format's own justified exception to the boards' full-width default, not an oversight.
• Italic Georgia as the signature voice, used narrowly. The hero title and each section's number+title are --font-body (Georgia) italic - the format's one recognisable voice. Subsection headings (h3) are kept in the plain sans (--font-ui), deliberately not the signature serif, so only the top of each section gets the "full pop" (Kennedy: one thing per page gets all the emphasis, everything else leans one direction only). No external font is loaded - Georgia is a system font, one self-contained file.
• No invented numbers. The stat row in the sample shows the pattern directly: one real, cited figure (20%, Nielsen Norman Group, linked) next to a second figure deliberately left as - because no equivalent number exists yet. That is the house rule from feedback_html_output_rules.md #4 in action, not just stated.

A decision recorded, per rule 7's own exception clause

House rule 7 (feedback_html_output_rules.md) requires every section and subsection to be a collapsible <details>. This format collapses only the top-level numbered sections (open by default, so the page still reads as one continuous scroll) and leaves subsections as plain flowing prose, not individually collapsible. Folding every subsection of a five-section argument would fragment the one property that defines this archetype - a thesis walked through start to finish - into a picklist, which is the compendium's job, not the vision paper's. This is the documented exception the rule itself allows ("exceptions only where a format's own decision record says so").

Build checklist for a new vision paper

1. Copy template.html to the new document's folder.
2. Link documentation-kit.css at the correct relative path (two levels up from formats/vision-paper/ if left in place; adjust if moved).
3. Replace: wordmark, title, dek, kicker, date, authors, abstract, all five section titles/content, quote(s), citations, stat row, table, footer line. Keep the block count roughly the same - that discipline is the point of a format.
4. Do not add a second accent colour, a sidebar rail, or a hero button.
5. Run python3 "9 - System/ui-ux/token-audit.py" <file> - zero violations before shipping. Add any new bespoke measure (a ch cap, a bespoke font-size) as a named token in a local :root block inside the page's own <style>, never as a bare literal.
6. Verify no horizontal scroll at 375 / 768 / 1280px.
7. Open in the browser (open <file>.html) before calling it done.

Provenance

Format anatomy generalised from a public agentic-government long-form vision-paper layout (structure only - header/hero/lead-strip/TOC/numbered sections/pull-quotes/inline citations/authors block/footer). No text, brand, colour or asset from that source was copied; the palette, type, spacing tokens and every block come from the house kit, and the sample content is original, written for this workspace.