Skip to content

OpenSenseNova/SenseNova-Skills / skills/sn-md-to-html-report

sn-md-to-html-report

Verified

将 Markdown 报告、研究笔记、行业分析、战略备忘录、技术白皮书、复盘、周报等长文档,重组并创作为有编辑判断、网页美感和证据秩序的自包含 HTML 专题页。用户要求“转成 HTML”“网页化报告”“美化报告”“做成专题页”“便于分享”“提升可读性/设计感”“把报告做成网页”时使用。必须先写 plan.md 再写 HTML,保留原文事实断言和结论强度,不套模板,不做机械 Markdown 转换。

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。
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall