# The Longform Learning Playbook A repeatable loop for studying the best longform reading experiences on the web and folding what they do into this library. Run it whenever you find a longform site worth learning from — the goal is a growing, evidence-based reference, not one-off admiration. The principle behind it: **measure before you admire.** A screenshot tells you what a page looks like; computed styles tell you why it reads well. Every entry in this library is built on what the browser actually rendered, never on a guess. --- ## The loop, at a glance ``` pick ──▶ measure ──▶ codify ──▶ rebuild ──▶ critique ──▶ catalogue ──▶ pick again │ │ │ │ │ │ rubric forensics design styled a11y + specimen snippet tokens homage fidelity card + index ``` Each pass adds one specimen: a `learnings/NN-slug.md`, a style-matched `reports/NN-slug.html`, two screenshots, and a card on `index.html`. --- ## 1. Pick — is this site worth a slot? Not every pretty page earns a study. Score a candidate against this rubric; take it on if it clears most of it and brings something the library doesn't already have. - **Reading is the point.** The article/feature is the destination, not a teaser for something else. - **It survives the fold.** Type, measure and rhythm are considered, not default theme output. - **Mobile is designed, not just shrunk.** There is a real phone treatment. - **It has a point of view.** A signature you could describe in one sentence. - **It fills a gap.** A genre or emotional strategy the current eight don't already cover (see the taxonomy in `assets/data/design-tokens.md` → "Cross-cutting patterns"). Sources for candidates: awards galleries and longform showcases (e.g. Shorthand's "The Craft", publisher features, university newsrooms, design-studio blogs, well-run newsletters), plus any article that made *you* want to keep reading. --- ## 2. Measure — run the forensics Open the page in a browser and paste `workflows/forensics-snippet.js` into the DevTools console. Run it **twice**: once at desktop width (~1366px) and once at phone width (~390px, device toolbar). It prints the real design system: - body font / size / leading, and the **measure** (characters-per-line — the single most predictive "good longform" number: aim ~40 CPL on phones, 54–66 on desktop); - H1/H2 fonts, sizes, weights, style (watch for the signature move — an italic H1, a giant condensed display, a serif body); - link colour + decoration, blockquote / caption styling; - imagery strategy (contained vs full-bleed) and sticky chrome; - **visual cadence** — the count of significant visuals, visuals per 100 paragraphs, and how many screens pass between beats. This is the "images as narrative pacing" dimension: the [design system](../design-system/index.html) law is a visual beat at least every one to three screens. The snippet flags whether a page clears that floor. Capture desktop + mobile screenshots into `assets/screenshots/NN-slug-desktop.jpeg` and `-mobile.jpeg`. Decline cookie/consent banners; if one blocks the hero, hide it with `document.querySelectorAll('[class*="cookie" i],[id*="consent" i]').forEach(e=>e.style.display='none')` rather than accepting. > **Automated option.** The forensics in this repo were gathered headlessly with the Playwright > MCP (`browser_navigate` → `browser_resize` → `browser_evaluate` with the snippet's body → > `browser_take_screenshot`). Any headless browser that can read `getComputedStyle` works. --- ## 3. Codify — write the tokens Add a section to `assets/data/design-tokens.md` using the same shape as the existing eight: desktop block, mobile block, a one-line **design signature**, and **font substitutes** (name the free Google fonts that stand in for any proprietary faces). This file is the source of truth every report is built from. --- ## 4. Rebuild — the style-matched report Add the new site as an entry in `SITES` inside `workflows/build-reports.workflow.js` (copy an existing object and fill in `palette`, `fontRoles`, `typeScale`, `layout`, `signature`, `facts`, `screenshots`). Then re-run the workflow — completed sites return from cache, only the new one builds: ``` Workflow({ scriptPath: "workflows/build-reports.workflow.js", resumeFromRunId: "" }) ``` The workflow builds each report **in its reference's own visual language** (the homage) and runs an adversarial polish pass for accessibility, responsiveness and fidelity. It also writes the companion `learnings/NN-slug.md`. **Rules the builder holds to** (keep them if you build by hand instead): - faithful homage of the real design language — free Google fonts substitute for proprietary faces; - self-contained HTML, all CSS inline, no frameworks; - responsive with `clamp()`; never horizontally scroll the body; - accessibility floor: one `

`, ordered headings, `:focus-visible`, text-over-image on a scrim at ≥4.5:1, `prefers-reduced-motion` respected, real `alt` text; - **no hotlinked copyrighted photography** — evoke immersive looks with CSS colour-fields and gradients; use captured screenshots only inside a small, attributed "Visual reference" figure; - content is your own design *analysis* of the site, never the reference article's prose; - attribution + links back to the index and the original. --- ## 5. Critique — look at it Serve the folder (`python -m http.server 8099`) and open the report at 375 / 768 / 1280px. Ask the hard questions: does it actually look like the source? Is the signature the memorable element? Any horizontal scroll, invisible-until-JS content, or low-contrast text over imagery? Fix in the source, re-verify. A picture beats a paragraph — screenshot before/after. --- ## 6. Catalogue — add the specimen card Add one `
` to the grid in `index.html`, following the existing pattern: source-tinted `--sig` spine, the real palette as swatches, and the measured Body / Leading / Measure in the mono strip. Update the hero count and the "cross-cutting patterns" section if the new site shifts the taxonomy. --- ## Keeping it honest over time - **Re-measure occasionally.** Live sites change; a token file drifts. Re-run the snippet on the originals now and then and reconcile. - **Watch the taxonomy, not just the count.** The library is valuable when it *covers the space* of longform strategies. Prefer a candidate that adds a missing emotional or structural strategy over a seventh variation on one you already have. - **Retire weak entries.** If a newer specimen does the same job better, demote the old one. - **Every claim traces to a measurement.** No card metric that isn't in the token file; no token that wasn't read from a rendered page.