pro-report-builder

Pro Report Builder

制作精良的咨询报告，以独立 HTML 文件呈现。通过 Chrome 无头模式导出为 PDF。

安装

git clone https://github.com/thatrebeccarae/claude-marketing.git && cp -r claude-marketing/skills/pro-report-builder ~/.claude/skills/

快速参考

任务	方法
从头开始创建报告	阅读 REFERENCE.md，了解 CSS + HTML 模式
添加新的组件类型	使用 REFERENCE.md 中的现有组件组合
导出为 PDF	使用 Chrome 无头模式 --print-to-pdf（参见导出部分）
自定义品牌令牌	编辑 :root 块中的 CSS 自定义属性

何时使用此技能，而非 pro-deck-builder

	pro-report-builder	pro-deck-builder
格式	8.5x11" 纵向页面	16:9 横向幻灯片
内容流	多页、连续文本	单页幻灯片排版
导出	Chrome 无头模式 --print-to-pdf	Puppeteer
适用于	审计报告、评估、书面交付物	演示文稿、提案幻灯片

---

开始之前

第 1 步：了解需求

询问用户：

1. 文档类型是什么？ 审计报告、评估、技术简报、案例研究？
2. 大约需要多少页？ 有助于规划章节流程和页面分配。
3. 有哪些数据？ 原始数字、API 导出数据、电子表格？提取准确数值——有实际数据时绝不估算。
4. 文件应保存在哪里？ 默认值：./output/

第 2 步：规划文档结构

每份报告都遵循以下结构：

Cover Page --> Executive Summary --> Analysis Sections (3-6) --> Prioritized Recommendations --> Quick Wins --> Appendix

每个分析章节应占 1-2 页。建议卡片最占空间，需要仔细规划。

---

设计系统

可自定义的品牌标识

内置设计系统提供专业的默认样式。所有颜色令牌、字体排版和间距均通过 :root 中的 CSS 自定义属性定义。请覆盖这些属性以匹配你的品牌。

颜色令牌

:root {
  /* Accent -- change this to your brand color */
  --accent:        #3D7A5C;
  --accent-dim:    rgba(61, 122, 92, 0.08);
  --accent-dark:   #2E6B4A;
  --accent-light:  #6AB88A;

  /* Severity */
  --excellent:     #2e8b57;
  --warning:       #D97706;
  --critical:      #c0392b;

  /* Light-mode backgrounds (warm cream) */
  --bg-page:       #FAF7F2;
  --bg-surface:    #F2EDE6;
  --bg-elevated:   #EBE5DD;

  /* Light-mode text */
  --text-primary:  #0f0e0e;
  --text-body:     #57606a;
  --text-muted:    #8b949e;

  /* Borders */
  --border:        rgba(15, 14, 14, 0.1);
  --border-dim:    rgba(15, 14, 14, 0.06);

  /* Callout tints */
  --tint-blue:     #eaf2ed;
  --tint-green:    #eaf5ef;
  --tint-red:      #fef2f2;
  --tint-amber:    #fffbeb;

  /* Dark mode (cover page only) */
  --dark-bg:       #141414;
  --dark-surface:  #1E1E1E;
  --dark-text:     #f0f3f6;
  --dark-muted:    #6e7681;
  --dark-secondary:#9ca3af;
  --dark-border:   rgba(255, 255, 255, 0.08);
}

颜色规则：

• 所有内容页的背景均使用暖奶油色（#FAF7F2），而非白色。这是品牌差异化特征。
• 深色模式（#141414）仅用于封面页。
• 强调色用于强调线、表格标题、项目符号标记、优先级横幅强调元素和建议卡片左侧色条。仅在有意设计时使用，切勿用于装饰。
• 严重程度颜色（绿色/琥珀色/红色）仅用于性能指标，切勿用于装饰。
• 提示框色调（蓝色/绿色/红色/琥珀色）用于带左侧边框的提示框，并与其严重程度相匹配。

字体排版

角色	字体	字重	字号	字距	备注
封面标题	Switzer	Light (300)	36pt	-0.03em	深色封面上的文档名称。
封面副标题	Switzer	Regular (400)	16pt	normal	位于封面标题下方。颜色：--dark-muted。
封面标签	Cartograph CF	Regular (400)	8pt	+0.15em	全部大写。颜色：--accent。位于标题上方。
章节标题	Switzer	Regular (400)	18pt	-0.02em	内容页 h2。下方带强调线。
小节标题	Switzer	SemiBold (600)	12.5pt	normal	内容页 h3。
正文	Switzer	Regular (400)	9.5pt	normal	段落、描述。行高：1.6。
表头	Cartograph CF	SemiBold (600)	7.5pt	+0.05em	全部大写。强调色背景上的白色文字。
表格正文	Switzer	Regular (400)	8.5pt	normal	行背景交替显示。
KPI 数值	Cartograph CF	SemiBold (600)	16pt	-0.02em	KPI 卡片中的数字。
KPI 标签	Cartograph CF	Regular (400)	6.5pt	+0.06em	全部大写。位于 KPI 数值下方。
推荐卡片标签	Cartograph CF	SemiBold (600)	7.5pt	+0.04em	全部大写。字段标签。
优先级横幅	Cartograph CF	SemiBold (600)	9pt	+0.08em	全部大写。优先级级别标签。
页脚	Switzer	Regular (400)	7pt	+0.03em	居中。颜色：--text-muted。

关键字体排版规则：

1. 封面标题使用 Light (300)，而非 Bold。 大字号下的 Light 字重显得自信、高级。
2. 所有数字／数据内容均使用等宽字体。 KPI 数值、表头、推荐卡片标签、优先级横幅。
3. 正文使用 9.5pt 字号和 1.6 行高。 这是针对阅读优化的文档，而非幻灯片。
4. 表头使用强调色背景上的全大写等宽字体。 形成鲜明的表格风格。

字体默认设置（可替换）：

• Switzer：从 Fontshare CDN 加载（免费）。回退字体：system-ui, sans-serif
• Cartograph CF：商业字体，通过 local() 加载。回退字体：JetBrains Mono, monospace

页面尺寸

Width:   8.5in
Height:  11in
Orientation: Portrait

间距

区域	数值
内容内边距	0.6in 0.75in 0.7in
封面页内边距	0 1in 1in（底部对齐）
页脚	绝对定位，bottom: 0，padding: 10px 0.75in 14px
章节标题下边距	4px（之后强调线会在下方增加 20px 间距）
小节标题边距	20px 顶部，8px 底部

---

组件库

所有组件均在 REFERENCE.md 中提供完整的 HTML + CSS 文档。可用组件如下：

页面结构

组件	类	用途
页面容器	.page	带阴影的 8.5x11" 页面。
封面页	.cover-page	底部对齐内容的深色封面。
内容区域	.content	页面内带内边距的内容区域。
页脚	.page-footer	居中的页脚，含文档名称和页码。
章节标题	.section-title + .accent-rule	带强调色下划线的章节标题。
延续章节	.section-continued	多页章节的“（续）”标签。

数据展示

组件	类	用途
KPI 行	.kpi-row / .kpi-card	由大数字卡片组成的 4 列网格。
KPI 卡片（风险）	.kpi-card--risk	用于风险／负面 KPI 的红色调变体。
数据表	带严重程度类的 table	条纹行、强调色表头、严重程度颜色。

内容块

组件	类	用途
提示框	.callout + .callout-{color}	左侧带边框的洞察框（蓝色／绿色／红色／琥珀色）。
正文	.body-text	标准段落文本。
项目符号列表	.bullet-list	强调色圆点项目符号。
编号列表	.numbered-list	等宽字体的强调色编号标记。

建议

组件	类	用途
优先级横幅	.priority-banner + level class	层级标签（CRITICAL/HIGH/MEDIUM/LOW）。
建议卡片	.rec-card + level class	带左侧强调条的多字段卡片。
快速见效项表格	使用 .qw-num 的表格	带编号的行动项表格。

---

文档编排

必备页面

每份报告都必须包含：

1. 封面页（.cover-page）-- 深色背景、文档标题、元数据（日期、账户、周期）
2. 执行摘要 -- KPI 行 + 关键发现提示框 + 简要说明
3. 建议 -- 按优先级分组的优先级建议卡片
4. 快速见效项 -- 用于快速取得成效的简短行动表格

内容页类型

类型	使用场景	关键组件
数据表 + 说明	清单、基准比较	表格 + .body-text + .bullet-list
提示框组	深入分析特定项目	多个 .callout 提示框（绿色/红色/琥珀色）
表格 + 提示框	附带洞见的性能数据	表格 + 单个摘要提示框
建议卡片组	优先级建议	.priority-banner + .rec-card 卡片组
混合分析	多部分章节	表格 + 提示框 + 项目符号 + 子章节

---

叙述规则

1. 尽可能每页安排一个章节。 如果一个章节跨越多页，请在后续页面使用“（续）”。
2. 先呈现数据。 表格和 KPI 卡片应置于说明文字之前。
3. 证据之后放置提示框。 每个数据表后都应跟一个总结关键洞见的提示框。
4. 有实际数据时，切勿估算。 如果数据包含精确值，请计算准确总数。
5. 所有指标都要进行基准比较。 始终在指标旁展示行业基准。
6. 严重程度颜色 = 信号。 绿色/琥珀色/红色仅用于性能指标。
7. 提示框颜色应与严重程度匹配。 优势使用 .callout-green，问题使用 .callout-red，警告使用 .callout-amber，中性洞见使用 .callout-blue。
8. 章节标题下方添加强调线。 每个 .section-title 后都应跟 <hr class="accent-rule">。
9. 建议卡片字段保持一致。 每张建议卡片至少应包含：标题栏、ISSUE、ACTION 字段。

---

防止页面溢出

页面高度固定为 11in。超出页面容器的内容会在 PDF 中明显溢出。构建前必须为每一页规划内容预算。

高度预算

区域	高度
内容内边距（顶部 + 底部）	~1.3in
页脚	~0.4in
可用内容区域	~9.3in

组件密度限制

组件	每页最多项数	密集模式覆盖设置
建议卡片（完整字段）	3 张卡片	4 张及以上：删除可选字段
建议卡片（精简）	4-5 张卡片	将外边距缩减为 8px 0 12px
数据表	10-12 行	13 行及以上：将字体缩小至 7.5pt，内边距缩小至 3px 8px
提示框	每页 3-4 个	将内边距缩减为 10px 14px
项目符号列表	6-8 项	缩短描述

分页策略

1. 导出为 PDF 前，先在浏览器中测试每一页
2. 发生溢出时，将内容重新分配到各页
3. 每个 <div class="page"> 对应一张 PDF 页面
4. 对不应跨页拆分的组件使用 .keep-together
5. 重新分配内容时，更新所有后续页面的页码

---

反模式（绝不可做）

1. 不要使用白色背景。 内容页始终使用 #FAF7F2（暖奶油色）。
2. 不要将章节标题设为粗体。 .section-title 使用 Regular（400）。
3. 除章节标题下方 40px 的强调线外，不要添加装饰性强调条。
4. 报告中不要使用表情符号。 除非用户明确要求。
5. 内容页不要使用深色模式。 深色仅用于封面页。
6. 不要堆砌大段文字。 将长段文字拆分为项目符号列表。每个提示框最多 3 句话。
7. 数字必须使用格式。 始终使用 $X,XXX 或 $XXXK，并启用 tabular-nums。
8. 已有类时不要使用内联样式。 使用组件库。
9. 页面页脚不要使用等宽字体。 页脚使用正文字体。
10. 不要让 rec-card 单独出现在页面上。 优先级横幅和第一张卡片必须位于同一页。
11. 不要遗漏强调线。 每个 .section-title 后都必须紧跟 <hr class="accent-rule">。

---

PDF 导出

自动导出（首选）

使用 Chrome 无头模式，可靠地生成 8.5x11" 纵向 PDF：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --headless \
  --disable-gpu \
  --print-to-pdf="/OUTPUT/PATH/report.pdf" \
  --no-pdf-header-footer \
  --print-to-pdf-no-header \
  "file:///PATH/TO/report.html"

手动导出（备用）

1. 在 Chrome 中打开 HTML 文件
2. Cmd+P --> 另存为 PDF
3. 将边距设为 "None"
4. 启用 "Background graphics"
5. 纸张大小：Letter（8.5" x 11"）

必需的打印 CSS

每份报告都必须包含此 @page 规则和 @media print 块：

@page { size: 8.5in 11in; margin: 0; }
@media print {
  * { print-color-adjust: exact; -webkit-print-color-adjust: exact; }
  body { background: white; margin: 0; }
  .page {
    margin: 0;
    box-shadow: none;
    page-break-after: always;
    page-break-inside: avoid;
    width: 8.5in;
    min-height: 11in;
  }
  .page:last-child { page-break-after: avoid; }
}

---

QA 检查清单

交付前，请检查：

数据准确性

• 所有数字准确且内部一致
• 百分比在应相加的地方合计正确
• 收入数字在高管摘要 KPI、表格和 rec-card 引用中一致

页面溢出（检查每一页）

• 没有内容超出页面边界
• rec-card 页面最多包含 3 张完整字段卡片
• 含有 13 行及以上的数据表使用密集模式

视觉一致性

• 每个内容页都有 .page-footer，且页码正确
• 封面页没有 .page-footer
• 每个 .section-title 后都紧跟 <hr class="accent-rule">
• 跨页章节使用 "(continued)"
• 提示框颜色与其严重程度相符
• 优先级横幅使用正确的级别类

PDF 导出

• 存在带有 size: 8.5in 11in 的 @page 规则
• 全局应用了 print-color-adjust: exact
• PDF 中正确呈现所有背景颜色