doc-html-stylelisted

# 桌面端富色彩文档 HTML 样式规范 **一句话**：先判形状、按语义角色配色、token 化明暗主题、桌面优先、自包含单文件——不套模板，套的是判断力 + 一组硬规则 + 一个自检脚本。 --- ## 0. 适用/不适用 | | 场景 | 处理方式 | |---|---|---| | ✅ 适用 | 技术文档、设计文档、业务QA、评审报告、复盘总结等要写成 HTML 成品供人在电脑上阅读 | 走本 skill 全流程 | | ➡️ 交接 | 手机端页面预览/效果图（如小程序页面还原） | 转 `design-preview`，那是750px舞台+手机边框的约定，和本skill的桌面优先方向相反 | | ➡️ 交接 | 产物是 Claude Artifact（走 Artifact 工具发布） | 转 `artifact-design`，那边受 CSP 沙盒限制（字体要内联data URI等），本skill的文档是普通本地/仓库文件，没有这层限制 | | ➡️ 交接 | 文档里要嵌入真实数据图表（折线图/柱状图/散点图等） | 图表内部的配色、图例、可区分度规则转 `dataviz`，本skill只管文档整体的版式和色彩体系，不重新发明图表配色 | | ➡️ 交接 | "这段内容该写进L几层文档""这个矛盾该听哪份文档的" | 转 `doc-layer-system`，本skill不管内容归层，只管已经定好要写的内容怎么呈现成HTML | --- ## 1. 先判断文档形状（核心机制，替代"选模板"） 动笔前必须先想清楚，而不是从骨架库里选一个： | 问题 | 影响什么 | |---|---| | 读者是谁？（同事/客户/长辈/自己存档） | 决定语气克制度、术语密度 | | 篇幅多大？一屏能看完，还是要翻很久？ | 决定要不要加目录导航（见第2节） | | 主信息载体是什么？代码 / 决策表格 / 问答对 / 时间线 / 纯叙述 | 决定主视觉语言用什么承载——不是套哪个骨架，是这份文档"主要靠什么讲话" | | 要不要导出打印/转PDF分享？ | 决定要不要写 `@media print` | | 这次投入多大的视觉设计精力？ | 借用"实用 vs 精修"这把尺子——内部小QA记录用不着跟对外设计文档一样精修，先掂量清楚再动笔，别每次都往最大做 | `references/形态标定样例.md` 里有三种典型形状的落地片段，遇到没见过的形状（比如时间线/复盘）现场按这套判断逻辑推，不强行往三个例子里套。 --- ## 2. 硬规则（结构，任何形状都适用） - **自包含单文件**：CSS/JS 全部内联在 `<style>`/`<script>` 里，不外链 CDN 字体或脚本。 - **桌面优先尺寸**：内容区一般 `max-width` 定在 1000–1400px 之间居中，用 `clamp()` 做流式排版。**明确不用 375/750px 手机舞台或 `scale(0.5)`**——那是 `design-preview` 的约定，本skill反过来。 - **token 化明暗主题**（抄 `artifact-design` 验证过的机制，三层缺一不可）： 1. 语义色定义在 `:root` 的自定义属性上； 2. 用 `@media (prefers-color-scheme: dark)` 覆盖同一批变量，跟随系统； 3. 再用 `:root[data-theme="dark"]` / `:ro