# 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 | Need | Format | |---|---| | Argue one thesis end to end, meant to be read start to finish | **Vision paper** (this format) | | One idea, one screen, no scroll needed | One-pager (`documentation-design.md` grammar, no dedicated template yet) | | Reference material - every block type on one page, browsed not read | Compendium (`documentation-compendium.html`) | | Teaching page with a sidebar for jumping between many topics | Documentation page (`documentation-kit.css` §3 ORIENTATION, `.on-this-page` rail) | | A screen or interaction to prove | Clickable mockup, not a document at all | 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 `
` 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) - **A dark hero or footer also needs a light mode** (Frank, 14-09-2026). 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. - **Colour carries meaning, used narrowly here.** 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 `
`. 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" ` and report the count of violations. 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 `