# Design system Every value on the page comes from a token in the `:root` block at the top of `report.css`. `build.py` writes one small block ahead of it that sets the five theme colors from `report.json` and nothing else. If you want to change how the report looks, change a token. If you find yourself typing a raw size or color into a rule, the system is missing a token and the rule is a bug. ## Color The theme carries five colors: `--paper`, `--ink`, `--accent`, `--secondary`, `--wash`. Everything else is mixed from them with `color-mix()` in oklab, so a new theme moves the whole page and never leaves a stranded gray behind. | Token | Mix | Default | On paper | Use | |---|---|---|---|---| | `--ink-soft` | ink 80% on paper | `#4d4c47` | 7.76:1 | standfirst, secondary reading text | | `--muted` | ink 62% on paper | `#706f69` | 4.55:1 | labels, captions, footnotes, byline date, the stage progress fill | | `--rule` | ink 16% on paper | `#d2cfc8` | 1.40:1 | quiet hairlines and dividers | | `--rule-strong` | ink 52% on paper | `#84837d` | 3.43:1 | any edge that is a control's only affordance | | `--card-border` | ink 28% on paper | `#b7b5ae` | 1.85:1 | card and panel borders | | `--line` | secondary 70% with ink | `#3e5548` | 7.29:1 | connection lines in the artwork | | `--ink-strong` | ink 88% with black | `#21211d` | 14.57:1 | primary button on hover | | `--focus` | accent | `#a33e36` | 5.74:1 | focus ring | | `--select` | accent 22% on paper | `#e7cbc1` | 9.53:1 behind ink | `::selection` | | `--scrim` | paper 70%, transparent | | | veil behind the contents panel | Text holds 4.5:1 or better everywhere, captions included. `--rule` is meant to be quiet, not invisible; anything a reader can click or tab to gets `--rule-strong` so its boundary clears 3:1. The methods band sits on `--wash`, so it redefines `--muted` locally as ink 66% on wash, which keeps that text at 4.81:1 on its own background. `--rule-strong` is the border of anything a reader can click, and it holds 3.43:1 on paper. It is not the stage progress fill: that fill sits on `--wash` rather than on paper, where the same mix reads 2.99:1, so the fill takes `--muted` and holds 3.96:1 against its own track. The ruling inside a drawing is ink at 16 percent, the same value `--rule` carries, so the grid under the marks reads as ruled paper rather than as a haze. It dissolves under a radial mask instead of stopping at a rectangle. Every page declares `color-scheme: light`, so a reader whose system is set to dark gets scrollbars and form chrome that match the paper instead of chrome painted for a theme the page does not have. Color-mix in oklab is required. That means a 2023 or newer browser. The icon is the one color that is not mixed by the stylesheet, because it is a file rather than a rule; `build.py` mixes it in oklab itself, so it lands on the same value a `color-mix()` would give. ## Type Two families, no third. `--font-serif` reads: body, headings, the quote. `--font-sans` labels: header chrome, buttons, nav, eyebrows, captions, byline, step card headings, footnotes. `--font-numeral` is Times, used only for large figures because it has lining numerals that share a baseline; it always runs with `font-variant-numeric: lining-nums tabular-nums`. `--font-code` is the one exception and it is not used by a report at all. The guide prints command lines a reader has to transcribe exactly, and a proportional face makes a flag, a path and a line continuation hard to read, so `pre` and `code` on that page run in a mono stack. | Token | Size | Line height | Role | |---|---|---|---| | `--t-1` | 13px | `--lh-label` 1.5 | eyebrows, labels, captions, controls, footer | | `--t0` | 15px | `--lh-label` | contents rows, small copy | | `--t1` | 17px | `--lh-body` 1.55 | body, step card headings | | `--t2` | 22px | `--lh-subhead` 1.45 | running subheads, `h3`, brand mark | | `--t3` | 28px | `--lh-title` 1.29 | section titles, quote | | `--t4` | 40px to 61px | `--lh-display` 1.2 | cover title, findings numerals | Six steps, and only two things on the page are allowed to be large: the cover title and the findings numerals. Nothing is uppercase. Labels take `--track-label` at 0.01em; display type takes normal tracking, because the serif already closes up at size. Measure is `--reading`, 30em of the body size, so it follows the type instead of guessing at it. The target is 60 to 72 characters a line on the named faces: Iowan Old Style and Palatino Linotype hold about 60, Georgia and Charter about 68. A reader who has none of them installed falls through to Times, which is narrower than every named face and runs to about 73. The fixed 640px this replaced was borrowed from a wider face and held 93. ## Space `--s1` 4px, `--s2` 8px, `--s3` 12px, `--s4` 16px, `--s5` 24px, `--s6` 32px, `--s7` 48px, `--s9` 96px, `--s10` 128px. The scale keeps its numbering with 64px missing, so the day something needs it, `--s8` goes back in its place and no other name moves. Paragraph gap is `--s5`, heading to body is `--s6`, a section heading clears its section by `--s7`. Three lengths sit off that scale because they are the size of one thing: `--quote-rule` 40px opens a pull quote, `--card-w` 416px is the step card and the column it sits in, and `--panel-w` is the contents panel. `--band-skirt` is `--s7` under another name: the soft edge below the phone band, which the step slots clear as well as the band itself. ## Grid One gutter and three role widths. A role always uses its own width, so the page reads as disciplined without every element sharing one left edge. | Token | Value | Role | Left edge at 1440 | At 390 | |---|---|---|---|---| | `--wrapper` | 1400px | header, cover, notice, footer | 84px | 32px | | `--figure` | 1092px | scrolly stage, findings grid | 174px | 32px | | `--reading` | 30em, 510px at 17px | prose, quote, cover deck, section headings that open prose | 465px | 32px | | `--gutter` | `clamp(32px, 8vw - 24px, 64px)` | page margin | 64px | 32px | A section heading takes the width of what it opens, not a width of its own: it is on `--reading` over prose and on `--figure` over the findings grid and the scrolly, so a heading always starts on the left edge of the block under it. The methods band is two columns inside `--figure`, the note on `--reading` and the citations beside it. `--pad-wrapper` is the one formula that puts a full-bleed element on the wrapper: it is the gutter, or half the space outside 1400px plus the gutter, whichever is larger. The contents panel uses the same value for its right edge, so it lands on the header's own right edge. Section rhythm is flat: `--section` gives every section `clamp(40px, 5vw, 64px)` top and bottom, whatever it holds. The two bookends, the cover and the footer, use `--bookend`, which runs to 128px on a tall screen and backs off on a short one. `--header` is 68px and feeds the sticky header, the stage offset and `scroll-padding-top`, so those three can never drift apart. `--cover-art` caps the cover drawing at 48svh so the whole cover, scroll cue included, stays in one screen. `--band` is the height of the pinned stage once it becomes a band, `clamp(220px, 38svh, 320px)`, and the step slots offset their cards by it. `--reading-print` is the measure on paper, 27em of the printed body size. It is not a fourth role width; nothing on screen uses it. Smooth scrolling is off. A contents jump can cross thousands of pixels, and animating that runs the reader through every scrolly state on the way, so jumps are instant and `scroll-padding-top` puts the landing under the header. ## Controls, states and hit targets One control component: `.button` and `.control` share centered content, `--radius-control` 6px, a `--rule-strong` border, sans at `--t-1`, and `--tap` 44px of minimum height. Cards and panels use `--radius-card` 8px. Those are the only two radii. Two links are the size of their own type and cannot take that height: the brand in the header, 22px, and the template link in the notice, 20px. Each carries its hit area behind it in a `::before` inset by half of what the link is missing, `calc((var(--tap) - 100%) / -2)` top and bottom. The target is 44px at every width; the type and the focus ring stay the size the reader sees. Hover has two patterns and no third. Text links move `text-decoration-color` from `--rule-strong` to `--accent` over `--dur-hover` 140ms. Blocks, meaning buttons, contents rows and the contents summary, fill with `--wash`; buttons add a 1px lift over `--dur-control` 160ms and contents rows add a 2px accent inset rule. Focus is one rule everywhere: `--focus-width` 2px solid `--focus` at `--focus-offset` 3px. The ring follows each element's own radius, so it never cuts a corner or overlaps a neighboring row. Every section heading is a link to its own section, so a reader can take the address of the part they are reading. The link wraps the title rather than sitting beside it as a glyph: a permalink beside the title contributes its own name to the heading's, and every heading would then be announced with four words that are not the heading. It carries no decoration at rest, so a heading still reads as a heading, and the underline arrives on hover in the accent the way it does on every other text link. The same `::before` hit box sits behind it, so a one line heading is a full `--tap` target without a 44px line box. ## Motion Two curves. `--ease` `cubic-bezier(.32,.72,0,1)` carries every arrival and reflow. `--ease-draw` `cubic-bezier(.33,1,.68,1)` carries anything that draws or erases a stroke. Durations are `--dur-hover` 140ms for pointer feedback, `--dur-control` 160ms for buttons, `--dur-panel` 180ms for the contents panel. Reduced motion and the paused state run the same code path: transitions and animations drop to `.01ms` with no delay instead of being removed, so every end state is still correct and nothing has to branch. The media query is gated on `:root:not(.motion-on)`, which report.js sets when the reader turns motion back on with the header control. Without that gate the control would flip its own label and change nothing, which is worse than not offering it. The stage has its own durations, and they are tokens like everything else: `--dur-travel` 620ms for a mark moving between layouts, `--dur-draw` 240ms for one stroke or one line being drawn, `--dur-erase` 140ms for lines clearing out, `--dur-color` 340ms for a mark taking or releasing the accent, `--dur-ring` 380ms for the orbit ring and its label, `--dur-progress` 300ms for the progress rule and `--dur-caption` 320ms for the caption. `--draw-start` 434ms is when a new line starts drawing, about seventy percent of the way through the travel, so the lines arrive with the marks rather than after them. Per-element timing rides on custom properties build.py or report.js writes: `--md` is a mark's own travel delay, `--d` a line's draw delay, `--ring-delay` holds the ring back until the lines finish. The stagger those last two come from is stated once, in tokens: `--line-delay-first` 14ms and `--line-delay-last` 110ms across the lines of one state, `--intro-mark-step` 30ms and `--intro-stroke-step` 12ms across the marks and the strokes of the cover intro. report.js reads all of them, and every duration it waits on, out of the stylesheet at startup, so a timing cannot be changed in one file and left behind in the other. The intro draws each stroke with a dash of one length. Strokes are not the same length, so every stroke carries `pathLength` from build.py: the dash is then the stroke, whatever its own arc length is, and nothing is left drawn short. The delay is one rule over `--i`, the mark's index, and `--j`, the stroke's index in its mark, both written into the markup, so a mark of any stroke count staggers without a rule of its own. Only `transform`, `opacity`, `stroke-dashoffset` and `stroke` ever animate. The progress rule changes width with `scaleX`, not `width`, so no transition on the page can force a layout. ## The scrolly The stage is `position: sticky; top: 0; height: 100svh` with `padding-top` of `--header` plus 4px, so the pinned frame clears the header. `--stage-h-safe` is the viewport minus the header, written by report.js at load and on a width change; the drawing's width is capped by it, so the art always fits the frame. The steps column is led in by one stage height and pulled back by half a step (`padding-top: 100svh; margin-top: -56svh`), each slot is `112svh` with its card centered, and an `80svh` tail follows the last one. One passive scroll listener, throttled with `requestAnimationFrame`, makes active the last card whose top has passed a line at 0.88 of the viewport height; one `IntersectionObserver` at `rootMargin: "25% 0px"` decides whether that listener does any work. Resize recomputes on a width change only, so a mobile browser hiding its own chrome cannot fire a state change. Each step card carries the caption of the state it fires, as visually hidden text. That copy is the only description of the drawing in the document: the stage's own `figcaption` is the sighted duplicate and is hidden from assistive technology, so hiding this one too would leave a screen reader with no idea what the drawing shows. It is hidden from the eye rather than from the page, in reading order, inside the card it belongs to. With scripting off there is no state to show and nothing to pin, so the scrolly is not a staged column at all: the card's caption is shown, `.scrolly` stops being a grid, the drawing sits once at `--figure` under the same `--cover-art` cap the cover uses, and the steps run down the `--reading` column in the order they are written. The lead-in, the slots, the tail, the progress rule and the stage caption all go. A card keeps no chrome but a hairline above it, because nothing here can become active. ## The contents panel The panel is a native `
`, so it opens with scripting off. `initContents` in `report.js` adds four things and nothing else: it marks the reader's current section with `aria-current` when the panel opens, closes on a click outside or on the scrim, closes on Escape and returns focus to the summary, and moves focus to the landing section after a jump. A click on the scrim reports the `
` itself as the event target, which is how the handler tells a scrim click from a click on the panel. Quote sections carry no title and are left out of the contents. ## Sections The findings grid is `--figure` wide and takes its column count from the item count: one item fills the row, two or four sit as a pair, and everything else runs three across. A numeral is one line of `--font-numeral` at `--t4` with `--lh-numeral`, so a row of statistics shares one baseline. The optional `unit` sits under the numeral and the optional `note` under the text, both sans at `--t-1` in `--muted`. Neither is emitted when the author leaves it out. The quote sits on the reading column, left aligned, opened by `--quote-rule` in the accent. Its attribution is a paragraph with a `` in it, not a `