# Doc HTML Style

> 仅手动触发。把已定内容制作成桌面阅读优先、自包含、支持明暗主题的单文件 HTML 技术文档。只在用户显式输入 /doc-html-style 时使用；移动端像素预览用 design-preview，内容归层用 doc-layer-system。

- Skill: `backtocimacoppi/doc-html-style` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add backtocimacoppi/doc-html-style`
- Raw SKILL.md: https://api.skillmd.com/api/skills/backtocimacoppi/doc-html-style/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: BackToCimaCoppi (https://skillmd.com/u/backtocimacoppi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/backtocimacoppi/doc-html-style

---


# 桌面端富色彩文档 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"]` / `:root[data-theme="light"]` 覆盖一层，保证手动切换能压过系统偏好。
  组件样式只准吃这些 token，不准在组件规则里写死颜色值。
- **宽内容自己滚，页面不滚**：表格、代码块等宽内容各自套 `overflow-x:auto` 的容器，`body` 本身绝不允许横向滚动。
- **数字对齐**：表格里的数字列用 `font-variant-numeric: tabular-nums`。
- **目录导航看篇幅给**：长文档（需要翻页/多个大章节）才加 sticky 目录或锚点导航；一屏能看完的短文档不强行加目录，加了反而是噪音。

---

## 3. 色彩纪律（本skill的差异化重点——"更丰富但不失控"）

本 skill 的目标是比朴素的单色调更丰富的配色，但"丰富"不等于"随便加颜色"，靠以下纪律兜底：

- **颜色按语义角色/轴分配**，不做装饰性撒色。常见轴：状态轴（完成/进行中/阻塞/风险）、类别轴（不同模块/类型）、结论轴（通过/待定/驳回）。同一个轴的色相在同一份文档里固定，不中途洗牌。
- **同时出现的语义轴建议不超过 2–3 个**——这是防止"更丰富"滑向"大杂烩"的唯一硬限制。轴一旦超过3个，说明这份文档想同时表达的维度太多，应该拆分层级（比如用嵌套分组）而不是继续加色相。
- **写完配色，跑一遍自检脚本**：`scripts/check_contrast.py`，把每个语义色在浅色模式和深色模式下的"文字色-背景色"组合都跑一遍，任何一组不达标（正文对比度<4.5:1，大字/图形<3:1）都要回去调整，不能凭肉眼感觉"应该还行"。
- **参考起点**：`references/色彩与主题参考.md` 里有一套浅/深两色系的示例语义色，可以当起点看效果、照着调整，**不是强制调色板**，照抄整套等于又做了个模板。
- **"AI感"反模式清单**（文档场景专用，出现即可视为设计投入不走心）：
  - 每一张卡片不分主次都套同样的阴影+圆角；
  - 标题滥用渐变文字；
  - 强调色没有语义绑定，纯粹"好看就用"；
  - emoji 当图标大量堆砌当装饰；
  - 大面积紫蓝渐变当背景/hero区。

---

## 4. 自检表（判失败）

**结构类**
- 判失败：页面出现 375/750 手机舞台或 `scale(0.5)`（说明抄错了skill）。
- 判失败：某个语义色只在浅色或只在深色模式下定义了，另一模式漏掉。
- 判失败：表格或代码块导致整个 `body` 出现横向滚动条。
- 判失败：内容区宽度按手机窄栏（~720px及以下）设计，而这是一份桌面文档。

**色彩类**
- 判失败：某个语义色的"文字-背景"组合跑 `check_contrast.py` 显示 fail，但仍用在正文或关键状态标识上。
- 判失败：同一份文档里，某种颜色在不同地方分别代表了两种不同含义（比如红色一会儿表示"风险"一会儿表示"已完成"）。
- 判失败：同时出现的语义轴超过3个还继续加新色相，而不是拆分层级。
- 判失败：命中"AI感"反模式清单里的两条及以上。

---

## 5. 关系/边界（划归下游）

| 边界外的事 | 归谁管 |
|---|---|
| 手机端页面/小程序效果图还原 | `design-preview` |
| Artifact 沙盒发布规则（CSP、字体内联等） | `artifact-design` |
| 文档内嵌图表的配色/图例/可区分度 | `dataviz` |
| 内容该写进哪层文档、内容矛盾听谁的 | `doc-layer-system` |

本 skill 只管：已经确定要写的内容，如何组织成一份桌面优先、色彩克制而丰富、明暗皆宜的自包含 HTML。