static-page-stack

静态页面技术栈（SOTA，2026）

自我演进技能：此技能会在使用过程中不断改进。如果指令有误、参数发生偏移，或需要采用变通方案，请立即修正此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

用户想要制作静态 HTML 页面，并融合三种美学基因：

• 杂志 / 数据新闻（The Pudding、NYT Upshot）
• 技术文档（Material/Docusaurus/Starlight）
• 计算笔记本（Quarto/Observable/Jupyter Book）

……并嵌入三种 SVG：

• 程序化图表（Vega-Lite / Observable Plot / D3）
• 手工编写的内联 SVG（插图）
• 白板风格（Excalidraw / tldraw）

触发场景包括：“创建一个静态页面”“构建一个仪表板”“设计一份事后复盘”“搭建一个技术文档网站”“我该用什么 HTML/CSS 技术栈”“这堆 Tailwind 代码难以维护”。

推荐技术栈（简要版）

层级	首选	备选	原因
内容编写	Quarto	Quartz、Jupyter Book 2 / MyST	支持多页面、原生支持代码+正文+数学公式+执行，采用 MIT 许可证，Bundesbank/BIS/USGS 均在使用
视觉系统	Open Props + 原生现代 CSS	Pico.css	用语义化令牌（Brotli 压缩后 4 KB）取代 Tailwind 工具类堆砌；OKLCH + 容器查询 + light-dark() 在 2026 年已可用于生产环境
排版	Inter + Crimson Pro + Fira Code	IBM Plex 系列	均为 FOSS；字体搭配经过 NYT/Pudding 级别的测试
程序化图表	Observable Plot	Vega-Lite、ECharts	默认样式比 Vega-Lite 更简洁；无需使用 D3 即可满足约 95% 的需求；采用 ISC 许可证，由 Bostock 领衔开发
白板	Excalidraw + excalidraw_export CLI	tldraw（注意：商业许可证每年 6,000 美元）	采用 MIT 许可证，成熟可靠，可在构建时渲染 SVG
手绘风格程序化图表	rough.js（少量使用）	roughViz、chart.xkcd	仅用于传达“这是探索性的 / 存在不确定性”的场景
手工编写的内联 SVG	SVG 中使用 CSS 变量的模式	共享图标使用 <symbol><use>	var(--token) 可在内联 SVG 中生效，提供统一的设计令牌入口
滚动叙事	Closeread（Quarto 原生）	Scrollama	Closeread 专为 Quarto 打造；非 Quarto 项目可用 Scrollama（约 7 KB）

重要说明（请勿跳过）

2026 年的“XHTML”指语义化 HTML5，而非严格的 XHTML

如今已无人再编写字面上的 application/xhtml+xml。“优雅的 XHTML”在现代用法中实际指由构建工具强制生成的、格式规范的语义化 HTML5。Quarto 恰好会生成这种内容——包含 <article>、<aside>、<figure> 等元素——而无需你手动编写每个尖括号。如果用户说“XHTML”，请确认他们可能指的是遵循结构规范的语义化 HTML5。

Tailwind 本身不是问题

问题在于 Tailwind CDN + 临时拼凑的工具类，没有设计系统，而且每次都会重新生成。Open Props 同样能提供“开箱即用的全套令牌”体验，但它使用语义化 CSS 变量，并且这些变量会传递到内联 SVG 中。正是这一特性让整个技术栈保持一致。

Distill 已停止更新，Idyll 处于休眠状态——不要推荐它们

• Distill.pub 于 2021 年停止发布。distillpub/template 仓库看起来仍很活跃（972 颗星），但没有资金支持。
• Idyll-lang 上一次有实质意义的更新是在 2023 年 2 月。
• 2026 年的精神续作是 Quarto 的文章布局 + Closeread，而不是 Distill 的分支。

tldraw 含有非 FOSS 商业条款

tldraw 2.x+ 采用双重许可，源码可见：业余用途（带水印、非商业）或商业用途 每年 $6,000。除非 tldraw 的特定功能（交互式嵌入、精致的手绘风格）值得付出这笔费用，否则默认选择 Excalidraw（MIT）。

决策流程

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)

具体迁移：从 Tailwind CDN 拼凑代码迁移到 Quarto + Open Props

分阶段迁移（多分支仪表板总计约需 5-6 周）：

阶段 1 — 试点（1-2 周）： 将一个页面/分支转换为 Quarto。编写自定义 SCSS 主题，复用现有配色，并将其表示为 Open Props 令牌 + OKLCH，以匹配当前视觉效果。将其作为独立的 dashboard-quarto/ 目录发布。

阶段 2 — 美学升级（1 周）： 换用 Inter + Crimson Pro + Fira Code，将临时拼凑的 Tailwind 颜色替换为通过 oklch.fyi 生成的 OKLCH 配色阶梯，并统一图示/图表组件。

阶段 3 — 图表（1 周）： 将手工编写的含数据 SVG 转换为 Observable Plot 规范。说明性 SVG（架构图、流程图）改用 Excalidraw。

阶段 4 — 滚动叙事（1 周）： 选择 2-3 个解释机制的页面，改写为由滚动驱动的 Closeread 说明文。

阶段 5 — 推广（其余每个页面约 1 周）： 使用阶段 1 的模板。

需要指出的反模式

在用户代码中看到以下情况时，推荐使用技术栈中的替代方案：

1. 静态页面中使用 <script src="https://cdn.tailwindcss.com"> → 改用 Quarto + Open Props。Tailwind CDN 不会进行树摇优化 → CSS 臃肿、没有设计系统，而且每次重新生成都会产生偏差。
2. 内联 base64 编码的 SVG <img> → 使用带 var(--token) 的内联 <svg>，以便在整个设计系统中传递样式；或者使用 <svg><use href="#sym"> 来共享图标。
3. 在图表中手动输入数值（“预测：189K，实际：223K”）→ 使用从 CSV/parquet 读取数据的 Observable Plot，这样修正数字后图表会重新渲染。
4. 在多个页面中重复使用 style="color: #abc123" → 在 :root 中定义 OKLCH 配色，通过 Open Props 令牌公开，并使用 var(--color-*) 引用。
5. 项目希望绘制具备编辑出版质量的图表，却使用 Mermaid/Graphviz → 改用 Excalidraw 或手工编写的内联 SVG。（Mermaid 很适合“根据文本生成方框和箭头”，但永远达不到编辑出版质量。）

如实说明权衡（不要夸大优势）

• Quarto 的默认主题达不到杂志级水准。 可以实现 Bundesbank 级的输出效果，但需要花约 1-2 周编写自定义 SCSS 主题。如果用户想要无需任何设计工作即可上手的杂志风格，那么在 2026 年没有真正能胜任的 FOSS 方案——The Pudding 的 svelte-starter 最接近，但它使用的是 Svelte+Vite（不是 Quarto）。
• Observable Framework 面临 Observable Inc 裁员后的风险（2023 年，可能还有 2025 年）。ISC 许可意味着可以创建分支，但与 Posit 对 Quarto 的投入相比，其企业支持力度较弱。
• Open Props 需要学习令牌命名规则。 它不像 Tailwind 那样“即插即用”。其优势在于能构建一致的设计系统，但第一周的学习曲线更陡峭。

如何应用此技能

1. 明确用户的实际需求——单页还是多页？代码多还是文本多？有图表还是只有示意图？纯叙述还是数据驱动？
2. 使用上方的决策流程，选择框架 + 图表库 + 示意图库这套组合。
3. 默认使用 Quarto + Open Props + Observable Plot + Excalidraw，除非有具体原因不适用。
4. 如果用户想了解比较分析，请参阅 references/full-research-synthesis.md，了解各层的证据总结。
5. 不要推荐已停用或维护停滞的工具（Distill、Idyll、plain Tailwind CDN）。
6. 为新项目搭建脚手架时，请从 references/sota-urls.md 中的 URL 获取起始模板。

执行后复盘

如果某项建议在实际使用中不符合用户需求（例如，Quarto 的构建对于其项目规模来说过于繁重，或 Observable Plot 无法实现所需的可视化），请更新此技能——记录具体情况以及实际奏效的替代方案。不要留待“下次再说”。