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."