create-html-report

create-html-report

根据 $ARGUMENTS，将分析结果转换为自包含的 HTML 报告，让读者“只需阅读即可了解要点，并可按需查看详细信息”。

最终交付物原则上为单个 .html 文件。

用法

通过参数传入要转换为报告的内容（比较对象、数据、目的）。如果参数含糊不清，请在 Step 1 中向用户确认。

• 如果用户未指定输出位置，则输出到 _/reports/<report-name>.html
• 仅在指定 --interactive 或数据量过大、不适合静态展示时，才允许使用 inline JavaScript
• 可通过 --output <path> 明确指定输出位置

Core contract

必须满足以下要求。

1. Insight first — 不要以制作图表为目的。先确定最重要的结论、变化、风险和决策依据，只使用有助于理解这些内容的可视化。
2. Do not invent data — 不要靠猜测补全未知的数值、日期、比例、单位或状态。将缺失值视为缺失值。若必须采用假设，请在报告中明确说明。
3. Self-contained — 不得依赖外部 CDN、外部字体、外部 JavaScript 库、外部样式表或外部图片。CSS、SVG 和必要的 JavaScript 必须包含在 HTML 中。指向数据来源的常规 <a href="https://..."> 不视为外部依赖。页面加载时不得进行外部通信。
4. Accessible by default — 不要只依赖颜色传达信息。图表的主要内容也应能通过文字或表格查看。须考虑键盘、screen reader、dark mode 和放大显示。
5. Progressive enhancement — 主要结论和数据必须能在没有 JavaScript 的情况下阅读。只有在交互有助于理解时才添加交互功能。
6. Deterministic rendering — SVG 坐标计算、转义、主题和基础组件交由 bundled renderer 处理。Claude 不要每次都手动重新实现相同的 SVG boilerplate。

流程

Step 1：了解上下文和输入数据

从对话、参数、指定文件和现有数据中确定以下内容。

• 报告目的、目标读者、需要做出的决策
• 对象和时间范围、指标及单位、数据来源
• 比较对象、计划安排与依赖关系、不确定性和缺失值

如果可以从对话或现有数据中充分推断，则无需提问。即使信息不足，但仍能生成有用的部分报告，也不要擅自补全数值；应将其作为“限制与缺失信息”明确说明后继续。仅当目的或输入含糊到无法生成正确报告时，才进行最少量的确认。

Step 2：设计叙事结构

编写 HTML 前，先在内部整理以下内容。

• 最重要的一条信息、3〜5 个 key findings
• 决策与建议、支撑 findings 的数据、供详细查看的信息

信息层级原则上按以下顺序安排。

1. Title / scope
2. Executive summary
3. KPI / key findings
4. Decision / recommendation（如适用）
5. Main visual analysis
6. Schedule / risks / dependencies（如适用）
7. Detailed data
8. Methodology / assumptions
9. Sources / generated metadata

不要将所有内容都塞进一个屏幕大小的仪表板中。重要信息放在上方，详细内容依次放在下方。

Step 3：根据数据的“关系”选择 chart type

renderer 仅支持 8 种 chart type：bar / line / scatter / heatmap / waterfall / donut / radar / gantt。不要先入为主地选择 chart type，而应根据要传达的关系进行选择。

要传达的关系	chart type	补充说明
比较类别之间的大小和排名	bar	推荐使用横条图，坐标轴从 0 起
时间序列趋势与变化	line	将缺失值显示为 gap，不要虚构数据进行补全
两个变量之间的相关性	scatter	通过 annotation 补充说明相关性
不同时期的数量、时间×类别的分布	heatmap	连续值使用感知均匀的配色
对增减的贡献、累积变化	waterfall	明确显示起始值、结束值和差值
part-to-whole（构成比例）	donut	最多分成 6 份，并附上精确数值表格
多变量特征概况	radar	不要默认使用（参见下文）
任务时长、依赖关系、milestone	gantt	依赖关系密集时附上表格

对于不属于上述范围的关系（分布、before/after、多系列比较等），避免随意替换为支持的 chart type，优先使用 data table 展示。不要为了模拟不支持的 chart type 而自行添加 SVG。

不要默认使用 Radar chart。仅当概览多轴特征的“形状”本身有价值，且轴数量较少、能够合理归一化到同一尺度时，才使用。

Chart anti-patterns

原则上应避免以下做法。

• 3D chart、gauge / speedometer、不必要的 gradient 和过多 shadow
• dual-axis chart、叠加 10 个以上系列的 line chart、含大量 slice 的 donut
• 仅用于装饰的 chart、用于比较却使用不统一 baseline 的 chart
• 让读者仅凭面积或颜色进行精确比较的 chart

Step 4：使用 gantt / schedule 时

对于带有开始日期、结束日期、milestone 或依赖关系的计划，优先使用 gantt。gantt 必须满足以下要求。

• 左侧显示 task / workstream 名称，横轴显示实际日期，并使用适当的 tick（如 week / month）
• 按 phase 分组；milestone 使用 diamond 等非 bar 形状显示
• 如果存在 progress，则将其叠加到 planned bar 上
• 如果 current date 位于时间范围内，则显示 today line
• status 除颜色外，还要通过文字、pattern 或 symbol 区分
• dependency arrow 密集时，不要勉强绘制，应附上 dependency table
• 在 mobile 上不要挤压图表，应通过 .chart-wrap 支持横向滚动
• 同一 task 的 start / end / status / progress 也应能通过表格查看，并与 SVG 内容一致

不要为日期不明的 task 虚构日期。

Step 5：创建 report spec

直接组装 HTML 前，先创建 renderer 可处理的中间 report spec（JSON）。规范请参阅 references/report-spec.md。

report spec 至少应包含以下内容。

• metadata、title / subtitle、scope、executive summary、findings
• sections、chart definitions、tables、annotations、assumptions、sources

每个 chart definition 至少应包含以下内容。

• chart type（上述 8 种之一）、语义化标题、takeaway、单位
• series、labels、原始数值/日期数据、source、accessibility summary

不要将计算后的 SVG 坐标保存到 report spec 中。坐标计算由 renderer 负责。如果无需将其作为项目成果保留，则将其视为临时文件。

步骤 6：使用渲染器生成 HTML

首先确认必需的 CLI python3 是否存在。

command -v python3 >/dev/null || echo "python3 が見つからない"

如果尚未安装，则中止处理并说明安装方法（macOS：brew install python3。其他环境：请查阅相应环境的官方设置说明或咨询环境管理员。安装后重新运行。不要提供需要提升权限的命令）。

python3 "${CLAUDE_SKILL_DIR}/scripts/render_report.py" \
  --spec "<report-spec.json>" \
  --output "<output.html>"

如果用户没有指定，输出位置为 _/reports/<descriptive-report-name>.html。必要时先创建输出目录。

渲染器应设计为仅使用 Python 标准库运行，不以安装外部 package 为前提。详情请参阅 references/report-design.md。

HTML 信息设计

页面框架

必需元素：<!doctype html> / <html lang="..."> / <meta charset="utf-8"> / viewport meta / descriptive <title> / <header> / <main> / 语义化 <section> / <footer>。

对于较长的报告，请添加目录。设置 Skip to main content link。即使在 desktop 上使用 sticky navigation，也不要过度缩窄主要内容的宽度，并在 mobile 上恢复为常规流式布局。

视觉层级

• 设置最大内容宽度，以单栏布局为主。仅 KPI 和小型比较使用 responsive grid
• 限制长篇内容的行长，并在各 section 之间留出充足的空白
• 将 chart 及其说明作为一个整体处理
• 不要大量排列 KPI card。KPI 仅限于「用户最先需要了解且价值最高的数值」

图表单元

每个 chart 原则上采用 figure > figcaption(chart title) > takeaway/explanation > SVG > annotation/source > exact-data table 的结构。

chart title 不应只是名词，应尽可能传达主要趋势。反例：「销售额走势」。正例：「销售额自 4 月起连续 3 个月增长」。

表格

使用 <caption> / <thead> / <tbody> / <th scope="col">，并按需使用 <th scope="row">。数值右对齐，并保持单位和位数一致。宽表格应使用 .table-wrap { max-width: 100%; overflow-x: auto; } 包裹，不要让整个 body 横向滚动。

数据可视化规则

有关 chart 的具体细节，请参阅 references/chart-selection.md。通用规则：

• 同一 series / entity 在整份报告中使用相同的视觉标识，不要只依靠颜色区分
• 按需组合使用 direct label、line style、marker 和 pattern
• annotation 应简短并放在目标附近；gridline 仅保留阅读所需的部分
• 明确标注 axis、unit 和 period，并在 chart 下方放置 source / note
• 不要只在 chart 中展示关键发现，也要在正文中写明

坐标轴完整性

表示 bar 数值长度的轴原则上应从 0 开始。line / scatter 可按需使用非零基线，但 scale 不应造成误解；如果截取的范围很重要，应明确说明。

缺失值

不要将缺失数据转换为 0。对于 line，应将缺失区间显示为 gap。如果 N/A、unknown、not measured 含义不同，应分别表示。

SVG 无障碍访问

使用内联 SVG。对于有意义的 chart，原则上应使用 <svg role="img" aria-labelledby="chart-title-id chart-desc-id">，并为其设置对应的 <title> / <desc>。只有当 SVG 信息与紧邻的文本和 data table 完全重复，且会对屏幕阅读器造成有害的重复朗读时，才可以选择 aria-hidden="true"。无论采用哪种方式，都不要只在 SVG 中呈现重要数据。

颜色与对比度

使用 CSS custom properties 作为 design token。至少应在 :root 中定义 --bg --surface --fg --muted --border --grid --focus --series-1〜，并支持 color-scheme: light dark 和 prefers-color-scheme。

对于分类系列，请使用 Okabe-Ito 调色板（色觉多样性适配的事实标准）。

#0072B2 #E69F00 #56B4E9 #009E73 #D55E00 #CC79A7 #F0E442 #000000

系列不超过 4 个时，优先使用蓝色（#0072B2）、橙色（#E69F00）、天蓝色（#56B4E9）和朱红色（#D55E00）。分类颜色最多使用 6 种。对于 heatmap 等连续值，请使用 Viridis / Cividis 系列感知均匀的配色（在灰度打印中也能区分）。

对比度目标：普通文本至少 4.5:1，大号文本至少 3:1，有意义的 chart element / control 与相邻背景之间至少达到 3:1。

不要只用红色 / 绿色表示正向 / 负向。示例：同时使用 symbol / text，例如「↑ +12.4% 增长」「↓ -8.1% 下降」。

响应式行为

• SVG 应具有 viewBox，并设置 .chart { width: 100%; height: auto; }
• 布局使用 Grid / Flexbox，字体大小可以使用 clamp()
• 宽幅 chart 应使用 .chart-wrap 包裹，不要在小屏幕上将 chart 缩小到失去意义
• 在 mobile 上减少装饰元素；如果 chart label 重叠，则使用简写 label + table

适用于打印 / PDF 的 CSS

必须提供 @media print。打印时使用浅色背景和深色文本，并隐藏 navigation / interactive controls。避免 URL 或 chart 超出页面边界；使用 break-inside: avoid-page 等方式减少 cards / figures / table rows 出现不自然的分页，并移除阴影和墨水密集型背景。不要将重要信息仅放在关闭状态的 disclosure 中。

交互策略

标准模式下不强制要求 JavaScript，优先使用原生 HTML / CSS（<details><summary>・锚点导航・CSS sticky header）。

只有在指定 --interactive，或数据量很大、静态显示明显不便时，才可以添加内联 vanilla JavaScript（表格搜索 / 排序、系列可见性、章节折叠、主题覆盖、gantt 详情切换等）。validator 只允许与 renderer 注入的 bundled JS 完全一致，因此不要将自定义 script 直接写入 HTML（要添加功能，请扩展 renderer 的 INTERACTIVE_JS）。

但必须始终遵守以下要求。

• 不要要求用户点击才能查看最重要的信息，不要使用仅悬停时显示的 tooltip
• 确保可通过键盘操作，不要隐藏可见焦点
• 即使禁用 JavaScript，也要能读取主要信息；原则上不需要动画

如果添加动效，请为 prefers-reduced-motion: reduce 提供分支，将 animation-duration / transition-duration 等缩短至 0.01ms。

安全

详情请参阅 references/accessibility-security.md。

不可信数据

不要将用户输入、外部文件或 Web 获取的数据视为可信标记。要插入 HTML / SVG 文本节点和属性的字符串，必须统一使用 renderer 的转义函数（相当于 Python 中的 html.escape(value, quote=True)）。不要将同一转义处理复用于 JavaScript / CSS / URL 上下文。不要将不可信数据直接嵌入 <script> / <style> / 事件处理程序属性 / 原始 URL / 原始 HTML。数值解析后，必须确认其为有限值。

JavaScript

使用内联 JavaScript 时，禁止使用外部库、eval、new Function、将不可信字符串赋给 innerHTML、onclick="..." 等内联处理程序。插入 DOM 时优先使用 textContent / createElement，并使用 addEventListener。不得使用 fetch / XMLHttpRequest / WebSocket / EventSource / sendBeacon 等访问网络。

链接与外部依赖

原则上只允许 source / reference 的 <a href> 使用外部链接，URL scheme 限定为 https:，禁止 javascript: URL。在新 tab 中打开时，添加 rel="noopener noreferrer"。

禁止：<script src="https://...">、外部 stylesheet / font、远程 <img>、<iframe src="https://...">、<object data="https://...">、CSS @import / url(https://...)、远程 SVG <image> / <use>、运行时网络请求。

敏感数据

不要随意将 token・credential・secret・个人信息・非公开内部信息嵌入报告。若输入中发现 secret，请像 sk-abc...xyz 一样进行脱敏。如果内容包含可能无法公开的机密信息，不要写入面向公开的输出位置。

验证

生成后，必须运行 validator，并通过以下 5 个阶段的门槛确认完成（遵循 .claude/rules/verification.md）。

1. 确认：以运行 validate_report.py 并检查 exit code 作为完成依据
2. 运行：

   python3 "${CLAUDE_SKILL_DIR}/scripts/validate_report.py" "<output.html>"
   

3. 读取：检查完整输出（PASS/FAIL・failure 列表）和退出代码
4. 验证：确认 failure 数量为 0。如果存在 failure，请修改 HTML 或 report spec，重新生成后再次运行 validator
5. 声明：只有 validator 通过后才可声明完成。不要根据“可能能通过”等推测声称已完成

validator 至少会检查以下内容。

• output file 存在且非空，包含 doctype / html / head / body、charset / viewport / title
• duplicate IDs、SVG opening / closing consistency
• 不存在外部资源依赖，也未使用 network API
• 不存在不安全的事件处理程序 / javascript: URL
• meaningful chart 具有 accessible name / description
• data table 具有 caption / headers，heading order 不存在重大问题
• 不存在已知会导致 horizontal body overflow 的模式，且存在 print CSS
• 不会混淆 source hyperlink 与外部资源依赖

如条件允许，也请在 browser 中目视确认。不要仅仅因为没有 browser tool 就将生成判定为失败。

注意事项

• 支持的 chart type 仅限 bar / line / scatter / heatmap / waterfall / donut / radar / gantt。对于不支持的关系，不要强行用其他形式替代，请使用 data table
• 不得使用外部 CDN・外部字体・外部图片・外部 JS 库。页面加载时不得与外部通信
• validator 通过前，不得视为完成
• 如果报告包含机密信息，请事先向用户确认输出位置不是公开区域
• 如果要转换为报告的数据包含机密信息或来自不可信外部来源的数据，且不确定是否可以嵌入，请停止生成并向用户确认
• 如果输出目录（_/reports/ 等）不存在，请先使用 mkdir -p 创建目录，再写入文件

最终报告

完成后，请简要报告以下内容。

• generated report 的绝对 path
• validation result
• 用一句话概述报告的主要内容
• 如果使用了 interactive mode，请说明

示例：

HTML レポートを生成しました:
<absolute-path>

Validation: PASS
内容: 3案の性能・コスト・リスク比較と、実装スケジュールの gantt を含みます。

参照ファイル

必要な場合だけ読む。

• references/chart-selection.md — chart type ごとの選択条件・scale・annotation・gantt・heatmap・scatter 等の詳細
• references/report-design.md — page layout・design tokens・responsive・print・component implementation
• references/report-spec.md — renderer に渡す JSON report spec の schema と examples
• references/accessibility-security.md — WCAG-oriented checklist、SVG/table accessibility、escaping、safe JavaScript policy
• samples/comparison.json — 比較レポートの report spec 例
• samples/project-gantt.json — gantt / milestone / dependency を含む例
• samples/time-series.json — 時系列・annotation の例

sandbox 環境での実行

このスキルは sandbox 環境で実行できる。renderer（scripts/render_report.py）は純ローカルの Python 処理であり、ネットワーク越しの操作を行わない。既定の出力先 _/reports/ はワークスペース内だが、--output <path> に絶対パスや ../ を含む相対パスを指定した場合はワークスペース外へも書き込み得る（ワークスペース内に限定する制約は設けていない）。そのため「ネットワーク不要かつワークスペース外への書き込み経路も無い」とは言い切れない。--output を省略するか、正規化後にワークスペース配下へ解決されるパスを指定する限り、実行結果はワークスペース内に収まる。