sn-md-to-html-report

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

Report HTML

把报告文本创作为一份有编辑判断、网页美感、证据秩序、且只属于这份主题的单文件 HTML。

核心原则：保留事实断言，重构阅读和视觉体验，让设计从报告所属领域和内容任务里长出来。主题自己的世界——它的材质、工具、器物与语汇——是产生独特设计选择的来源。

设计判断原则

• 首屏即论点：首屏先找到这份报告所属领域里最有识别度、最能承载主题气质的事物或机制，并用最适合它的形式呈现：标题、图片、动画、实时演示或一个可互动瞬间。这个选择必须有明确判断；不要默认使用“大数字 + 小标签 + 辅助统计 + 渐变强调”，只有当它确实是主题最自然、最有力的入口时才使用。
• 文字系统承载页面性格：标题字体与正文字体要被有意搭配，不要沿用任何项目都能套上的常用字体组合；同时建立清晰的字阶，并有意识地设置字重、字宽和间距。让文字排印本身成为设计中可被记住的一部分，而不是只负责传递内容的中性容器。
• 结构即信息：编号、眉题、分隔线、标签等结构性手段，应该传递内容的真实信息，而不是装饰内容。许多通用设计都使用编号标记（01/02/03），但这仅适用于内容本身就是一个序列的情况——例如一个真实的流程或一份文字时间线，其中顺序承载着读者所需的信息。在使用编号标记之前，请先思考其是否真的有意义。
• 有意识地使用动效：先判断动效是否能服务主题、阅读或信息理解，再决定用在哪里：页面加载序列、滚动触发展示、悬停微交互或环境氛围。一个被编排好的关键动效通常比零散特效更有力量；动效选择必须服从整体美学方向。有些主题更适合克制处理，额外动画反而会削弱专业感，并让页面显得像 AI 生成的模板作品。
• 复杂度匹配愿景：视觉方向越繁复，执行就越需要足够的层次、细节和完成度；视觉方向越极简，间距、字阶、对齐和微细节就越要精准。优雅不等于少，也不等于多，而是把选定的方向执行到位。
• 认真处理文案：标题、导语、标签、按钮和说明都要被当作设计的一部分处理。可以对源报告的内容重写、压缩、合并和组织表达，但不得发明事实、口径或结论强度。文案和视觉一样会产生模板感。

设计知识的使用方式

• 层级：先决定读者第一眼、第二眼、第三眼分别看什么，再分配尺度、重量、留白和位置。
• 对比：用字体气质、字号、明暗、密度、动静和空间关系制造差异；不要只靠颜色强调。
• 对齐与网格：正文、图表、卡片、注释和导航都落在同一套网格和宽度档里，避免右边缘和左基线随手漂移。
• 邻近与分组：证据靠近判断，注释靠近对象，相关项成组，不相关项拉开。
• 重复与变奏：重复建立秩序，变奏表达章节差异；整页不能一章一个系统，也不能每章完全同形。
• 图地关系：纹理、背景、氛围和动效永远退到内容之后，不能抢走正文和证据的可读性。
• 节奏：长报告要有轻重、疏密、转场和停顿；不是把所有模块等权堆叠。

硬规则

• Markdown 是素材，不是页面结构；不要逐段照搬，也不要把所有内容塞进卡片。
• 先写 plan.md，再写 HTML；没有完整 plan 不动 HTML。
• 页面默认是单文件 HTML：语义 HTML + 内联 CSS；除非用户要求或项目已有资源体系，不拆分文件、不引 CDN。
• 可以用领域隐喻组织视觉和结构，但页面里的数字、来源、案例、判断、结论强度必须来自原报告。
• 不发明 logo、客户、证言、排名、地图点位、图表数据、置信度或看似合理但原文无法支撑的归纳。
• 图表、流程、时间线、地图式分组等必须自包含手写。

工作流

1. 读内容与任务：通读源报告，确认主题、领域、受众、用途、核心判断、证据、限制、重复内容、表格、图示和附录。
2. 第一遍：brainstorm 短设计计划：先根据 brief、报告领域、内容任务、证据结构和受众发散 2-3 个与内容契合的设计方向，不碰具体 HTML。每个方向用 compact token system 表达：Color 为 4-6 个命名 hex 值并说明语义用途；Type 定义 display、body，必要时定义 utility / mono；Layout 用一句话概念和 ASCII wireframe 描述；Signature 定义这页唯一会被记住的设计元素。
3. 审查并修订短设计计划：对照 brief 和报告内容检查每个方向是否真有内容来源。如果任何部分像类似页面的通用默认答案，而不是为当前报告做出的选择，必须修订该部分，并写明改了什么、为什么改。确认相对独特性后，选择 1 个方向进入完整计划。
4. 第二遍：完整页面计划：基于修订后的短设计计划，展开信息结构、首屏策略、页面拓扑、导航、章节版面、转场节奏和证据贴附方式；用层级、对比、对齐、邻近、分组、重复 / 变奏来组织信息。
5. 逐章做内容设计：每章写清 内容形状 -> 章节版面 -> 呈现形式 -> 排版处理。颗粒度到段或判断，不要整章放过；长论述也要做导语、拉引、边注或判断提块。
6. 定设计契约与 checklist：写 HTML 前把 tokens、字体角色、宽度档、章版面映射、动效策略、响应式降级、事实边界、泛模板自检和检查角度落到 plan.md。checklist 是开工前的契约，不是事后补救。
7. 写 HTML：只实现 plan.md，不要在 HTML 阶段另起一套视觉或结构。先搭全页骨架，再填内容和图表；所有颜色、字体和关键布局选择都必须从短设计计划派生。
8. 按检查角度审查：从事实保真、主题契合、美学一致性、字体层级、布局网格、内容塑形、动效克制、可访问性、响应式和分享性逐项检查；未通过就修正。

plan.md 必须包含

• 受众 / 用途：谁读，读完要做什么。
• 短设计计划：基于 brief 与内容信号 brainstorm 2-3 个方向；每个方向包含 Color、Type、Layout、Signature。
• 相对独特性审查：哪些部分像默认答案，改了什么，为什么改；确认后选择 1 个方向。
• 首屏策略：用什么主题领域代表物开篇，领读什么，如何形成焦点和图地关系。
• 信息结构与版式策略：拓扑、骨架、导航、章节版面、转场节奏、宽度档、移动端降级。
• 逐章内容设计表：每章的内容形状、章节版面、呈现形式、排版处理、证据贴附方式。
• 设计契约：tokens、字体角色、网格 / 宽度档、导航类型、章版面映射、动效策略、关键对比度、泛模板自检。
• checklist：写 HTML 前确认设计契约完整；交付前按检查角度逐项签收。

参考文件

• brainstorm 短设计计划前，读 references/01-aesthetic-direction.md。
• 定版式和逐章内容设计前，读 references/02-layout-and-content-design.md。
• 写 HTML 前，读 references/03-design-contract.md 并完成 checklist。
• 交付前，读 references/04-review-angles.md 并按角度审查。

HTML 要求

• 使用 CSS tokens 管理颜色、字体、间距、边线、宽度档和动效参数。
• 桌面端要真实使用横向空间；移动端无页面级横向滚动，长表和代码块可局部滚动。
• 导航若存在必须可用：锚点能跳、当前章可感知、键盘可达、小屏可降级。
• 图表与图示继承页面 token，不另起一套颜色和字号；颜色不能是唯一编码。
• 标题、导语、标签、注释和图表文案要经过编辑，不输出模板腔。