OpenSenseNova/SenseNova-Skills / skills/sn-md-to-html-report
sn-md-to-html-report
Verified将 Markdown 报告、研究笔记、行业分析、战略备忘录、技术白皮书、复盘、周报等长文档,重组并创作为有编辑判断、网页美感和证据秩序的自包含 HTML 专题页。用户要求“转成 HTML”“网页化报告”“美化报告”“做成专题页”“便于分享”“提升可读性/设计感”“把报告做成网页”时使用。必须先写 plan.md 再写 HTML,保留原文事实断言和结论强度,不套模板,不做机械 Markdown 转换。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.4 KB |
| references/01-aesthetic-direction.md | markdown | 5.4 KB |
| references/02-layout-and-content-design.md | markdown | 6.5 KB |
| references/03-design-contract.md | markdown | 4.6 KB |
| references/04-review-angles.md | markdown | 3.6 KB |
references/03-design-contract.md
View on GitHub# 03 · 设计契约
本文件用于写 HTML 前。设计契约是 `plan.md` 末尾的开工门禁:它把短设计计划、版式策略和内容设计压成 HTML 必须实现的清单,防止写着写着退回默认模板。
契约不是事后总结。没有契约,不写 HTML。
## 1. 契约必须回答的问题
- 页面基于哪个短设计计划和 compact token system?
- 首屏用什么主题领域代表物开篇?
- 哪些 token 必须出现在 `:root`?
- 字体角色是什么,是否真实加载?
- 页面使用哪些宽度档和网格?
- 每章对应什么版面?
- 哪些图表 / 图示必须实现?
- 哪些动效和氛围层必须实现,如何降级?
- 哪些事实边界不能越过?
- 哪些设计选择只属于这份报告?如果换到另一份报告仍成立,写明要改掉的地方。
- 写完后按哪些角度审查?
## 2. plan.md 推荐结构
```text
# 报告网页化 plan
[受众 / 用途]
[短设计计划]
brief 与内容信号:
候选方向:
选定方向:
相对独特性审查:
[选定 compact token system]
Color:
Type:
Layout:
Signature:
[首屏策略]
代表物:
领读内容:
焦点:
图地关系:
[信息结构与版式策略]
阅读层级:
页面拓扑:
页面骨架:
导航:
转场与节奏:
[逐章内容设计表]
章节 -> 内容形状 -> 章节版面 -> 呈现形式 -> 排版处理 -> 证据贴附 -> 小屏降级
[设计契约]
tokens:
字体角色:
网格 / 宽度档:
章版面映射:
图表 / 图示清单:
动效策略:
响应式降级:
事实边界:
泛模板自检:
检查角度:
[HTML 前 checklist]
```
## 3. tokens 契约
至少声明这些 token 类型,数值来自选定 compact token system 和版式策略:
```css
:root {
/* color */
--bg: ...;
--surface: ...;
--surface-2: ...;
--text: ...;
--muted: ...;
--line: ...;
--accent: ...;
/* type */
--font-display: ...;
--font-body: ...;
--font-mono: ...;
--step-0: ...;
--step-1: ...;
--step-2: ...;
--step-3: ...;
/* space */
--s1: ...;
--s2: ...;
--s3: ...;
--s4: ...;
--s6: ...;
--s8: ...;
--s12: ...;
/* layout */
--measure: ...;
--wide: ...;
--page-pad: ...;
/* shape and motion */
--radius: ...;
--line-w: ...;
--ease: ...;
--dur: ...;
}
```
要求:
- 间距走有限标度。
- 字号走比例系统。
- 连续正文只有一个 measure。
- 宽块、边栏、全幅都有明确用途。
- 关键文字 / 背景、图形 / 背景对比度写出。
## 4. 泛模板自检门禁
写 HTML 前,必须在 `plan.md` 中完成一次反向检查:
```text
泛模板自检:
这套视觉若换到另一份不同领域报告,哪些地方还成立?
哪些地方因此显得过于通用?
将修改哪 1-3 个设计选择,让首屏、字体、结构或图示更贴合当前报告?
```
要求:
- 自检发生在写 HTML 前,不是交付后的补充说明。
- 至少检查首屏代表物、字体角色、配色语义和章节版面机制。
- 若所有设计选择都能无损迁移到另一份报告,必须回到短设计计划阶段重选至少一个关键选择。
## 5. 章版面映射
写 HTML 前,逐章声明版面:
```text
章版面映射:
0 首屏 = 全幅代表物 + 主标题构图
1 总览 = 不对称网格
2 对比 = 横向画廊 / small multiples
3 证据 = 主文 + 边注
4 流程 = sticky 分屏
5 附录 = 单列流 + 贯通表格
```
HTML 写完后逐章对账。若 DOM 里没有对应布局,说明实现偏离契约。
## 6. HTML 前 checklist
写 HTML 前逐项确认:
- [ ] 短设计计划已选定,且不是通用模板。
- [ ] 首屏代表物来自主题领域,而不是默认大数字 / 三卡片。
- [ ] 配色、字体、纹理、动效和不可遗忘点已写入 plan。
- [ ] 信息结构、页面拓扑、骨架、导航、转场已写入 plan。
- [ ] 每章都有内容形状、章节版面、呈现形式和证据贴附方式。
- [ ] tokens、字体角色、宽度档、章版面映射已声明。
- [ ] 图表 / 图示清单已确定,且没有发明数据。
- [ ] 响应式降级已确定。
- [ ] 事实边界已写明。
- [ ] 泛模板自检已完成,过于通用的选择已修改。
- [ ] 检查角度已列出。
## 7. HTML 实现纪律
- 只实现 plan,不在 HTML 阶段重新发明风格。
- 先搭全页骨架和章节容器,再填内容。
- 每填完 2-3 章,对照章版面映射,防止后半段退回单列。
- 图表和图示使用页面 token,不另起一套视觉系统。
- 所有交互和动效都必须有无障碍与 reduced-motion 降级。
- 如果发现契约有问题,先回 `plan.md` 修改契约,再改 HTML。
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |