Static Page Stack

Static Page Stack (SOTA, 2026)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to use this skill

The user wants to produce static HTML pages that combine three aesthetic DNAs:

• Magazine / data-journalism (The Pudding, NYT Upshot)
• Technical documentation (Material/Docusaurus/Starlight)
• Computational notebook (Quarto/Observable/Jupyter Book)

…and embed three kinds of SVG:

• Programmatic charts (Vega-Lite / Observable Plot / D3)
• Hand-authored inline SVG (illustrative)
• Whiteboard-style (Excalidraw / tldraw)

Triggers include: "create a static page", "build a dashboard", "design a post-mortem", "set up a technical-doc site", "what HTML/CSS stack should I use", "this Tailwind soup is unmaintainable".

The recommended stack (TL;DR)

Critical clarifications (don't skip these)

"XHTML" in 2026 means semantic HTML5, not strict XHTML

Nobody writes literal application/xhtml+xml any more. What "elegant XHTML" actually means in modern usage is well-formed semantic HTML5 enforced by the build tool. Quarto outputs exactly this — <article>, <aside>, <figure> — without making you hand-author every angle bracket. If a user says "XHTML", clarify they probably mean semantic HTML5 with structural discipline.

Tailwind itself isn't the problem

The problem is Tailwind CDN + ad-hoc utility-class soup, no design system, regenerated each time. Open Props gives you the same "drop-in tokens for everything" feel but as semantic CSS variables that propagate INTO inline SVG. That last property is what makes the stack coherent.

Distill is dead, Idyll is dormant — don't recommend them

• Distill.pub stopped publishing in 2021. The distillpub/template repo looks alive (972 stars) but has no funding story.
• Idyll-lang's last meaningful update was Feb 2023.
• The 2026 spiritual successor is Quarto's article layout + Closeread, not a Distill fork.

tldraw has a non-FOSS commercial clause

tldraw 2.x+ is source-available under a dual license: hobby (watermarked, non-commercial) or $6,000/year for commercial. Default to Excalidraw (MIT) unless tldraw's specific features (interactive embeds, polished hand-drawn aesthetic) justify the cost.

Decision flow

User wants a static page →
  ├─ Single document, code-heavy, math? → Quarto (single-file render)
  ├─ Multi-page investigation/dashboard? → Quarto with sidebar nav OR Quartz (digital garden) if cross-linking dominates
  ├─ "Pure data dashboard, no narrative"? → Observable Framework (caveat: Observable Inc layoff risk)
  ├─ "I want sidebar nav, search, code blocks"? → Astro Starlight + MDX (functional docs aesthetic)
  └─ "I want maximum flexibility, willing to design"? → Astro + custom theme + Open Props

User wants a chart →
  ├─ Static, magazine-quality default? → Observable Plot (default pick)
  ├─ Need interactivity, dynamic spec generation? → Vega-Lite
  ├─ Need polished interactive dashboards, Canvas OK? → ECharts
  ├─ Want sketchy "this is exploratory" framing? → rough.js / roughViz
  └─ Need bespoke custom path/glyph? → D3 (rare; Plot covers ~95%)

User wants a diagram →
  ├─ Architecture, flow, illustrative? → Excalidraw + excalidraw_export
  ├─ Premium aesthetic, budget for $6k/yr? → tldraw + tldraw-cli
  ├─ Inline SVG with design tokens? → Hand-author with var(--token-*)
  └─ Reused across many pages? → <symbol><use> pattern (caveat: shadow DOM blocks per-instance CSS)

Concrete migration: Tailwind CDN soup → Quarto + Open Props

Phased migration (~5-6 weeks total for a multi-spoke dashboard):

Phase 1 — Pilot (1-2 weeks): Convert one page/spoke to Quarto. Match current visual output by writing custom SCSS theme that reuses existing palette but expressed as Open Props tokens + OKLCH. Ship as separate dashboard-quarto/ directory.

Phase 2 — Aesthetic upgrade (1 week): Swap to Inter + Crimson Pro + Fira Code, replace ad-hoc Tailwind colors with OKLCH-generated palette ramps from oklch.fyi, standardize figure/chart components.

Phase 3 — Charts (1 week): Convert hand-authored data-bearing SVGs to Observable Plot specs. Illustrative SVGs (architecture, flowcharts) move to Excalidraw.

Phase 4 — Scrollytelling (1 week): Pick 2-3 mechanism explainer pages. Rewrite as Closeread scroll-driven explainers.

Phase 5 — Roll out (~1 week per remaining page): Use phase 1's templates.

Anti-patterns to call out

When you see these in user code, recommend alternatives from the stack:

1. `<script src="https://cdn.tailwindcss.com">` in a static page → Use Quarto + Open Props instead. Tailwind CDN doesn't tree-shake → bloated CSS, no design system, every regeneration drifts. 2. Inline base64-encoded SVG `<img>` → Use inline <svg> with var(--token) for design-system propagation, OR <svg><use href="#sym"> for shared icons. 3. Hand-typed numeric values in charts ("forecast: 189K, actual: 223K") → Use Observable Plot reading from a CSV/parquet so the chart re-renders if the number is corrected. 4. `style="color: #abc123"` repeated across pages → Define an OKLCH palette in :root, expose via Open Props tokens, reference via var(--color-*). 5. Mermaid/Graphviz in a project that wants editorial-quality diagrams → Switch to Excalidraw or hand-authored inline SVG. (Mermaid is great for "boxes-and-arrows generated from text" but never reaches editorial quality.)

Honest tradeoffs (don't oversell)

• Quarto's default theme is not magazine-grade. Bundesbank-quality output exists, but you'll spend ~1-2 weeks on a custom SCSS theme. If the user wants plug-and-play magazine aesthetic with zero design work, no FOSS option in 2026 truly delivers — The Pudding's svelte-starter is closest but it's Svelte+Vite (not Quarto).
• Observable Framework has post-layoff risk at Observable Inc (2023, possibly 2025). ISC license means a fork is viable but corporate backing is thinner than Posit's commitment to Quarto.
• Open Props requires learning the token naming scheme. Not "plug and play" like Tailwind. The payoff is a coherent design system, but the first week is steeper.

How to apply this skill

1. Identify the user's actual ask — single page or multi-page? Code-heavy or prose-heavy? Charts or just diagrams? Pure narrative or data-driven? 2. Use the decision flow above to pick the framework + chart-lib + diagram-lib trio. 3. Default to Quarto + Open Props + Observable Plot + Excalidraw unless something specific rules it out. 4. Reference `references/full-research-synthesis.md` for the per-layer evidence summary if the user wants to see the comparative analysis. 5. Don't recommend dead/dormant tools (Distill, Idyll, plain Tailwind CDN). 6. Pull starter templates from the URLs in `references/sota-urls.md` when scaffolding a new project.

Post-Execution Reflection

If a recommendation didn't fit the user's needs in practice (e.g., Quarto's build was too heavy for their scale, or Observable Plot couldn't express their viz), update this skill — note the case and the alternative that actually worked. Don't defer to "next time."

Full Research Synthesis (2026-04-25, 18 parallel agents) <!-- SSoT-OK: versions below are research-timestamp evidence, not canonical pins -->

This is the comparative analysis backing the recommendations in SKILL.md. Original research lives in the project that triggered it: ~/eon/opendeviationbar-patterns/findings/dashboard/spokes/2026-04-25-postmortem/learn/_research-static-page-stack-2026.md.

Method

18 parallel research agents, each researching one specific area of the static-page stack. Constraints encoded in every prompt:

• Three aesthetic DNAs: magazine/data-journalism + technical-doc + computational notebook
• Three SVG sources: programmatic charts + hand-authored inline + whiteboard-style
• Explicitly NOT text-source diagrams (Mermaid/Graphviz)

Version numbers below are evidence of currency at research time. They are not canonical pins — install the latest from the upstream URL.

Per-layer findings

Authoring framework

Top: Quarto. MIT license. Manuscript layout + Closeread extension for scrollytelling. Native Observable Plot integration via OJS cells. Multi-page navigation with sidebar + cross-references. Used in production by Deutsche Bundesbank, Bank for International Settlements, US Geological Survey. Quarto 2 (Rust rewrite) announced for 2026; current 1.x line stable through year-end. Default theme requires custom SCSS investment (~1-2 weeks) to reach magazine quality.

Strong alternative: Observable Framework. ISC license. Multi-page static dashboard via file-based routing. Polyglot data loaders (Python/R/JS run at build time). Plot-first. Active maintenance through 2026 (most recent point release in Q1 2026). Risk: Observable Inc layoffs (2023, possibly later) — fork viability is the contingency.

Strong alternative for cross-linking: Quartz. MIT, current major v4 line (2024-2026), ~12k stars. TypeScript/JSX, Markdown-native. Bidirectional links + graph view + backlinks panel out of the box. Best fit when forensic-investigation cross-linking is the dominant navigation property.

Other notable: Jupyter Book 2 / MyST. BSD-3-Clause. Strong multi-page TOC with myst.yml. Status: Alpha (not stable yet) — risk for production at the time of writing.

Functional but not magazine: Astro Starlight + MDX. MIT. Functional-docs default theme. ~1-2 weeks of custom CSS to reach magazine parity. Best when MDX component flexibility is the priority.

VitePress. MIT. Vue-centric. Powers vuejs.org/vitejs.dev. Default theme plain; custom theme via slot system + CSS variables. Picks: extend default theme rather than replace.

Manubot. AGPL 3.0. Manuscripts-as-website with GitHub-hosted Git workflow. Built on Pandoc. Best for collaborative academic content with chain-of-custody requirements.

The Pudding's svelte-starter. MIT. Real shippable boilerplate from data-journalism gold standard. Svelte+Vite stack. Closest to magazine-grade out of the box but requires Svelte expertise.

Avoid: Distill.pub template. Stopped publishing in 2021. Repo alive (~972 stars) but no funding story. Modern equivalent is Quarto + Closeread.

Avoid: Idyll-lang. Last meaningful update Feb 2023. Effectively dormant.

Avoid: Pollen. Racket-only ecosystem; niche; minimal community since around 2020.

Charts (programmatic SVG)

Top: Observable Plot. ISC. Cleaner defaults than Vega-Lite. ~95% of bar/line/scatter/heatmap needs. Mike Bostock-led. Stable 0.6.x line at research time, healthy maintenance pace. Native fit with Quarto + Observable Framework.

Vega-Lite. BSD-3-Clause. Best for complex specs, dynamic generation, interactive charts. JSON verbosity is the friction.

Apache ECharts. Apache 2.0. Wins on polished interactive dashboards (Canvas/SVG hybrid). ~80 KB minified bundle. Better aesthetics than Plot for very-data-heavy dashboards. Steeper config learning curve.

D3. GPL-3.0 (note: source-disclosure required if you ship D3 code). 20+ years battle-tested. Use when Plot doesn't cover your case (custom path, force simulation, 100k+ points).

Pancake (Svelte-native). MIT. Pure-static, server-side render, zero JS. Maintenance is dormant (last update ~4 years ago at research time) — note risk.

rough.js / roughViz / chart.xkcd. MIT. Sketchy programmatic SVG. Use sparingly for "exploratory / uncertainty implied" framing.

Avoid: visx (React-only), Plotly (~300 KB bundle), Chart.js (canvas, no SVG semantic).

Diagrams (whiteboard / sketchy)

Top: Excalidraw + excalidraw_export CLI. MIT, recent stable point release (April 2026), mature. CLI options: Timmmm/excalidraw_export, realazthat/excalidraw-brute-export-cli, JRJurman/excalidraw-to-svg. Export light + dark variants, post-process to strip hard-coded colors, wrap in component using data-theme.

tldraw. Recent v4 line at research time, stable. SVG export ~13% smaller than Excalidraw via DOM-based rendering. Non-FOSS license: hobby (watermarked, non-commercial) or $6,000/year commercial. tldraw v1.x remains MIT but is legacy. Default to Excalidraw unless tldraw's specific features (interactive embeds, polished hand-drawn aesthetic) justify the cost.

Penpot. MPL 2.0. Full design suite, heavier than whiteboard tools.

CSS / design system

Top: Open Props. MIT. Adam Argyle (Google/Chrome Labs). 500+ CSS variable design tokens (color/space/type/shadow/animation). ~4 KB Brotli. Multiple distribution formats (CSS/JS/JSON). Compatible with inline SVG theming via CSS custom properties.

Modern CSS features that change the game (2025-2026 production-ready):

• OKLCH colors (~82% support) — generate palettes from a single hue
• Container queries (~92% support) — components responsive to container, not viewport
• @scope (late 2025) — CSS scope without BEM
• light-dark() function — native light/dark switching
• text-wrap: pretty/balance — magazine-grade typography
• View Transitions API (full-page MPA support 2026) — smooth animations between static pages without JS

Pico.css. MIT, current v2 line, ~14.8k stars. Classless semantic styling with OKLCH theming. Multiple themes built-in. Trade-off: less granular control than Open Props.

Water.css / Sakura / NewCSS. Lighter, classless. Sakura is dual-tone via SASS. NewCSS is terminal/retro aesthetic.

Typography

FOSS body fonts (best defaults): Inter (sans), IBM Plex Serif or Crimson Pro (editorial), Fira Code or Source Code Pro (mono). All elevate to magazine-grade output.

Variable fonts: Recursive (5 axes including Casual). Subset to axes you use to manage file size (typical variable font: ~100-200 KB).

Fluid type scales: utopia.fyi generates clamp() functions eliminating breakpoints.

Color: OKLCH is the production standard. Tools: oklch.fyi, oklch.com, Figma OKLCH plugin. Generate palettes by varying L, holding hue+chroma. Store as CSS custom properties: --color-primary-50 through --color-primary-900. Named tokens beat scales.

Scrollytelling

Closeread. Quarto extension, active 2024-2026. Native scrollytelling for Quarto users. Sticky figures + scroll-triggered reveals.

Scrollama. ~7 KB, IntersectionObserver-based. Russell Goldenberg (The Pudding). Industry standard primitive when not using Closeread.

GSAP ScrollTrigger. Now fully free (Webflow acquisition). ~30 KB. Best for cinematic scrubbing or pin-unpin sequences. Overkill for simple figure swaps.

Lenis. ~3 KB smooth scrolling, doesn't break CSS sticky. Companion to Scrollama, not replacement.

Avoid: Idyll-lang. Dormant.

Inline SVG composition patterns

Token propagation: <path fill="var(--icon-primary, #000)" d="..."/>. CSS custom properties propagate INTO inline SVG. Use currentColor for single-color icons.

Accessibility:

<svg
  role="img"
  aria-labelledby="fig-title"
  aria-describedby="fig-desc"
  viewBox="0 0 24 24"
>
  <title id="fig-title">Architecture diagram: request flow</title>
  <desc id="fig-desc">
    Shows client → API gateway → service mesh with 3 replicas
  </desc>
  <!-- paths -->
</svg>

Symbol/use for shared icons:

<svg hidden>
  <defs>
    <symbol id="icon-download" viewBox="0 0 24 24">
      <path fill="var(--icon-primary, #000)" d="..." />
    </symbol>
  </defs>
</svg>
<svg role="img" aria-labelledby="ref-dl">
  <use href="#icon-download" />
  <title id="ref-dl">Download</title>
</svg>

Caveat: <use> doesn't grant CSS access to inner <path> elements (Shadow DOM boundary). Use CSS variable fallbacks in the symbol definition.

Optimization: SVGOMG (browser-based) or SVGO (CLI). 50%+ file reduction.

Inline vs `<img src=...svg>`: Inline for token-driven/interactive SVGs; external for reused decorative assets where HTTP/2 caching wins.

URLs

See sota-urls.md for the full link list grouped by layer.

SOTA URLs (grouped by stack layer)

Authoring frameworks

• Quarto — <https://quarto.org>
• Manuscripts: <https://quarto.org/docs/manuscripts/>
• Themes: <https://quarto.org/docs/output-formats/html-themes.html>
• Cross-references: <https://quarto.org/docs/authoring/cross-references.html>
• Awesome Quarto: <https://github.com/mcanouil/awesome-quarto>
• Closeread (Quarto scrollytelling extension) — <https://github.com/qmd-lab/closeread>
• Observable Framework — <https://observablehq.com/framework/> · <https://github.com/observablehq/framework>
• Quartz (digital garden) — <https://github.com/jackyzha0/quartz> · <https://quartz.jzhao.xyz>
• Astro Starlight — <https://starlight.astro.build>
• Awesome Starlight: <https://github.com/trueberryless-org/awesome-starlight>
• VitePress — <https://vitepress.dev>
• Awesome VitePress: <https://github.com/logicspark/awesome-vitepress-v1>
• Jupyter Book 2 / MyST — <https://jupyterbook.org> · <https://mystmd.org>
• Manubot — <https://manubot.org>
• The Pudding boilerplate — <https://github.com/the-pudding/svelte-starter>
• Tom Critchlow's wiki pattern — <https://tomcritchlow.com/wiki/>

Charts

• Observable Plot — <https://observablehq.com/plot> · <https://github.com/observablehq/plot>
• Plot for D3 users: <https://observablehq.com/@observablehq/plot-for-d3-users>
• Vega-Lite — <https://vega.github.io/vega-lite> · examples: <https://vega.github.io/vega-lite/examples/>
• Apache ECharts — <https://echarts.apache.org> · <https://github.com/apache/echarts>
• D3 — <https://d3js.org>
• rough.js — <https://roughjs.com> · <https://github.com/rough-stuff/rough>
• roughViz — <https://github.com/jwilber/roughViz>
• chart.xkcd — <https://timqian.com/chart.xkcd/>
• Pancake (Svelte-native) — <https://pancake-charts.surge.sh/>

Whiteboard / sketchy diagrams

• Excalidraw — <https://excalidraw.com> · <https://docs.excalidraw.com>
• Export API: <https://docs.excalidraw.com/docs/@excalidraw/excalidraw/api/utils/export>
• excalidraw_export CLI: <https://github.com/Timmmm/excalidraw_export>
• Quarto extension: <https://github.com/parmsam/quarto-excalidraw>
• Astro dark-mode workflow: <https://alexop.dev/posts/excalidraw-dark-mode-astro-diagrams/>
• tldraw — <https://tldraw.dev> · License: <https://tldraw.dev/community/license>
• tldraw-cli: <https://github.com/kitschpatrol/tldraw-cli>
• Penpot — <https://penpot.app>

Visual system / CSS

• Open Props — <https://open-props.style> · <https://github.com/argyleink/open-props>
• Pico.css — <https://picocss.com> · <https://github.com/picocss/pico>
• Modern CSS Toolkit 2026 — <https://www.nickpaolini.com/blog/modern-css-toolkit-2026>
• Modern Font Stacks (system) — <https://github.com/system-fonts/modern-font-stacks>

Typography

• Inter — <https://rsms.me/inter>
• Crimson Pro — <https://fonts.google.com/specimen/Crimson+Pro>
• Fira Code — <https://github.com/tonsky/FiraCode>
• IBM Plex — <https://www.ibm.com/plex/>
• Recursive (variable, 5 axes) — <https://www.recursive.design/>
• Utopia (fluid type scales) — <https://utopia.fyi>

Color

• OKLCH picker — <https://oklch.com> · <https://oklch.fyi>
• Figma OKLCH palette generator — <https://www.figma.com/community/plugin/1583211869437365830/oklch-palette-generator>

SVG composition

• SVGOMG (browser-based optimizer) — <https://jakearchibald.github.io/svgomg>
• SVGO (CLI) — <https://github.com/svg/svgo>
• Accessible SVGs reference — <https://css-tricks.com/accessible-svgs>

Scrollytelling

• Closeread (Quarto-native) — <https://github.com/qmd-lab/closeread>
• Scrollama — <https://github.com/russellgoldenberg/scrollama>
• GSAP ScrollTrigger — <https://gsap.com/docs/v3/Plugins/ScrollTrigger/>
• Lenis (smooth scroll) — <https://github.com/darkroomengineering/lenis>

Reference data-journalism / inspiration

• The Pudding — <https://pudding.cool> · resources: <https://pudding.cool/resources/>
• NYT Upshot GitHub — <https://github.com/theupshot> · NYT Newsdev: <https://github.com/newsdev>
• FiveThirtyEight data — <https://github.com/fivethirtyeight/data>
• The Markup — <https://github.com/the-markup>