BackToCimaCoppi 桌面端富色彩文档 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验证过的机制，三层缺一不可）：- 语义色定义在
:root的自定义属性上； - 用
@media (prefers-color-scheme: dark)覆盖同一批变量，跟随系统； - 再用
: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。