pro-deck-builder

演示文稿设计师

为 PowerPoint 提供由风投支持的 SaaS 级设计品质。想想 Linear、Attio、Vercel、Raycast——而不是企业风格的剪贴画。

安装

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

快速参考

任务	方法
从头创建	阅读 REFERENCE.md，使用 PptxGenJS
编辑现有文件／使用模板	阅读 editing.md
读取／提取内容	python -m markitdown presentation.pptx
查看视觉概览	python scripts/thumbnail.py presentation.pptx

---

开始之前（必做步骤）

步骤 1：询问用户

编写任何代码之前，先询问：

1. 浅色模式还是深色模式？ 深色模式 = 高端／主题演讲风格。浅色模式 = 报告／数据密集型演示文稿。
2. 偏好哪种配色？ 展示下方的配色表，或询问用户是否有品牌色。
3. Logo？ 询问用户是否有要加入的 Logo 文件（PNG/SVG 路径）。

步骤 2：查找字体

检查已安装的字体——高端字体能带来显著提升：

# macOS — list all installed font families
fc-list : family | sort -u

# Search for premium fonts first
fc-list : family | grep -iE "inter|dm.sans|poppins|avenir|futura|geist|sf.pro|sf.mono|jetbrains|fira.code|montserrat|playfair|source.sans"

# Check macOS Font Book directories directly
ls ~/Library/Fonts/ /Library/Fonts/ /System/Library/Fonts/Supplemental/ 2>/dev/null

字体选择优先级：

1. Inter — SaaS UI 的黄金标准（如果已安装，所有内容都使用它）
2. DM Sans — 几何感强，适合初创公司
3. Poppins — 圆润亲和
4. Avenir / Avenir Next — 随 macOS 提供，拥有与 Apple 风格相近的优雅气质
5. Calibri — 稳妥的后备选择，始终可用

用于数据／等宽字体： JetBrains Mono > Fira Code > SF Mono > Consolas

---

设计语言：由风投支持的 SaaS

美学原则

1. 通过层次营造纵深感 — 表面元素浮于背景之上。卡片和面板通过阴影与精细边框体现微妙的层次，而不是使用纯色块。
2. 醒目的字体，极简装饰 — 依靠字体层级传递信息。不要添加强调线、装饰形状或剪贴画。
3. 克制用色 — 仅少量使用一种强调色（10%）。整体以中性色为主。色彩用于传达信息，而非装饰。
4. 留白充足 — 空间感传递自信。如果幻灯片显得空疏，就放大内容，不要添加更多内容。
5. 每个元素都必须有存在的理由 — 添加任何内容之前，先问问它传达了什么。如果删掉它也没有任何变化，就删掉。

浅色模式与深色模式

用户为整套演示文稿选择一种模式。整套演示文稿中绝不混用两种模式。

---

色彩系统

深色模式（默认——高端／主题演讲风格）

令牌	值	用途
bg-primary	0A0A0C	幻灯片背景（深空黑）
bg-surface	17181A	卡片、面板（深石板色）
bg-elevated	1E1F23	高层级表面、悬停状态
bg-glass	不透明度为 4% 的 FFFFFF	半透明叠加层
text-primary	FFFFFF	标题、关键信息
text-secondary	A0A0A0	正文、描述
text-muted	5A5A5E	说明文字、元数据、标签
border-subtle	不透明度为 8% 的 FFFFFF	卡片边框

浅色模式（报告／数据密集型）

令牌	值	用途
bg-primary	FFFFFF	幻灯片背景
bg-surface	F8F9FA	卡片、面板
bg-elevated	FFFFFF	高层级表面（使用阴影）
text-primary	111111	标题、关键信息
text-secondary	555555	正文、描述
text-muted	999999	说明文字、元数据、标签
border-subtle	E8E8E8	卡片边框

---

配色系统

每种配色定义一种强调色（使用比例为 10%）以及语义状态色。强调色决定整体个性，其余部分均采用中性色。

内置调色板

名称	点缀色	十六进制	适用场景
Electric Blue	强烈的天蓝色	0055FF	SaaS、科技、产品
Neon Lime	酸性绿	39FF14	开发工具、性能
Hot Coral	温暖而充满活力	FF6B6B	营销、创意
Indigo	深紫色	6366F1	初创公司、AI/ML
Teal Trust	冷静而自信	0D9488	医疗保健、金融
Amber Signal	温暖而权威	F59E0B	咨询、战略
Rose	精致的粉色	F43F5E	设计、品牌、奢华
Emerald	成长绿	10B981	可持续发展、成功
Cyan Edge	鲜明的蓝绿色	06B6D4	数据、分析
Violet	富有创意的深邃感	8B5CF6	教育、创新
Slate	无点缀色	64748B	极简、低调
Gold Standard	金融级高端质感	D4AF37	投资者、董事会演示文稿

自定义调色板（用户品牌色）

如果用户提供了品牌色，请构建自定义调色板：

const palette = {
  accent: "0055FF",      // primary brand color
  accentMuted: "0055FF" + " at 15% opacity", // for tinted backgrounds
  positive: "10B981",    // good, up, success
  warning: "F59E0B",     // attention, caution
  critical: "EF4444",    // bad, down, error
};

色彩应用：85/10/5 规则

• 85% — 背景 + 中性色文本（取自模式的 bg + text 令牌）
• 10% — 点缀色（关键数字、图表主色、CTA、活动状态）
• 5% — 语义状态（KPI 和数据中的正向/警告/严重状态）

---

字体排版

字体优先级

运行字体发现（上文第 2 步），然后选择：

优先级	标题	正文	数据/等宽字体	风格
第 1 优先级	Inter 700	Inter 400	JetBrains Mono	Linear/Vercel
第 2 优先级	DM Sans 700	DM Sans 400	Fira Code	几何风格的初创公司
第 3 优先级	Avenir Next Bold	Avenir 400	SF Mono	接近 Apple 风格
第 4 优先级	Poppins 700	Poppins 400	JetBrains Mono	友好、现代
安全选项	Calibri Bold	Calibri	Consolas	始终可用

适用于编辑类/金融类演示文稿：

标题	正文	风格
DM Serif Display	DM Sans	精致的编辑风格
Playfair Display	Source Sans Pro	奢华、金融
Georgia	Calibri	经典企业风格

字号比例

角色	大小	字重	用途
主视觉标题	54-72pt	粗体（700）	仅标题页
幻灯片标题	32-40pt	粗体（700）	每张内容页
小节标题	20-24pt	半粗体（600）	幻灯片内的小节
正文	14-16pt	常规（400）	段落、项目符号
图注/元信息	10-12pt	常规（400）	脚注、来源
KPI 大数字	48-72pt	粗体（700）	仪表板重点展示
KPI 标签	9-10pt	半粗体、全大写、+字距	KPI 数字下方
数据/数字	11-14pt	等宽常规	表格、数据标签

字体排版规则

• 正文和列表左对齐——仅标题和 KPI 数值居中
• 每份演示文稿最多使用 2 种字体系列（数据另加 1 种等宽字体）
• 仅小标签（KPI 标签、类别标签）使用全大写 + charSpacing
• 行高：正文为 1.3 倍，标题为 1.1 倍
• 强调时不要使用下划线——请使用粗体或点缀色

文本适配（防止溢出）

如果不检查内容长度就使用固定字号，大数字和标题必定会溢出。请遵循以下规则：

大型 KPI 数字——根据字符数缩放字号：

字符数	示例	最大字号（卡片）	最大字号（独立显示）
1–4	$4.2M	48pt	72pt
5–7	$5,307K	36pt	54pt
8–10	$5,307,540	28pt	44pt
11+	$12,345,678	22pt	36pt

规则：优先使用缩写数字。 $5.3M > $5,307,540。只有在表格或脚注等需要精确度的地方才使用完整数字。

幻灯片标题——换行前的最大字符数：

字号	最大字符数（宽约 9"）	超出时的处理方式
54pt	~30	缩小到 44pt 或改写得更短
44pt	~38	缩小到 36pt 或改写得更短
36pt	~46	缩小到 32pt 或改写得更短
32pt	~52	使用副标题容纳溢出内容

规则：设置 fontSize 前先统计字符数。 切勿让内容幻灯片标题换成两行。章节分隔页可以换行。

窄容器中的正文（洞察面板、侧边栏）：

窄面板（宽度 < 4"）中的文本溢出是常见问题。PptxGenJS 不会自动缩小文本。请遵循以下规则：

容器宽度	最大 fontSize	每行最大字符数（约）	1.25 倍行距下的最大行数
4.0"+	14pt	~55	高度 ÷ 0.22"
3.0-3.9"	11pt	~45	高度 ÷ 0.18"
2.0-2.9"	10pt	~35	高度 ÷ 0.16"
< 2.0"	9pt	~25	高度 ÷ 0.15"

规则：添加文本前先估算行数。 统计文本字符数，除以每行最大字符数，得出行数，然后确认文本能放入容器高度。如果放不下：（1）减小 fontSize；（2）缩短文本；或（3）增大容器。切勿让文本悄然溢出——它会被裁切或与相邻元素重叠。

// ✅ CORRECT: 2.8" panel → max 10pt, ~35 chars/line
// "Welcome series dominates at 62%..." = 90 chars ≈ 3 lines
// Container h: 1.6" → fits ~10 lines at 10pt. Safe.
s.addText("Short, edited copy.", {
  x: 6.55, y: 1.45, w: 2.7, h: 1.6,
  fontSize: 10, fontFace: theme.font.body,
});

// ❌ WRONG: 2.8" panel with 14pt font and 200+ char paragraph
s.addText("Very long paragraph that will overflow...", {
  x: 6.55, y: 1.45, w: 2.8, h: 1.6,
  fontSize: 14, fontFace: theme.font.body,  // too large for narrow panel
});

图表数字格式

始终为图表数字设置易读的格式——坐标轴或数据标签中都不能出现“1000000”这样的原始数字。

关键：valAxisLabelFormatCode 仅设置坐标轴格式。showValue: true 显示的数据标签需通过 dataLabelFormatCode 单独设置格式。 如果设置了 valAxisLabelFormatCode，却没有设置 dataLabelFormatCode，数据标签就会显示“2888000”这样的未经格式化的原始数字。numFmt 不是有效的 PptxGenJS 属性——始终使用 dataLabelFormatCode。

首选方法——使用原始值的 OOXML 条件格式： 使用原始（未缩放）值，并让 OOXML 条件数字格式处理显示。这是最可靠的方法，也适用于混合量级的数据（例如同时包含 $2.9M 和 $3.6K 的图表）。

// ✅ BEST: Raw values + OOXML conditional format
// Under 1K: whole number ($500)
// 1K-999K: X.XXK ($540.18K, $57.72K)
// 1M+: X.XM ($2.9M)
const currFmt = '[>=1000000]"$"#,##0.0,,"M";[>=1000]"$"#,##0.00,"K";"$"#,##0';

values: [2888000, 717734, 425467, 3655],  // raw dollar values
dataLabelFormatCode: currFmt,              // conditional brackets OK here
valAxisLabelFormatCode: '"$"#,##0.0,,"M"', // simple format only (no brackets)

// ✅ ALSO OK: Pre-scale when all values are same magnitude
values: [2888, 718, 425],  // raw values divided by 1000
dataLabelFormatCode: '"$"#,##0"K"',
valAxisLabelFormatCode: '"$"#,##0"K"',

// ❌ WRONG: Raw values with axis-only format
values: [2888000, 718000, 425000],
valAxisLabelFormatCode: "$#,##0,K",  // axis may format but data labels show 2888000
// ❌ WRONG: numFmt (not a valid PptxGenJS property)

OOXML 条件格式参考（与原始值搭配使用）：

数据范围	格式代码	显示效果
货币（自动缩放）	'[>=1000000]"$"#,##0.0,,"M";[>=1000]"$"#,##0.00,"K";"$"#,##0'	$2.9M、$540.18K、$500
普通数字（自动缩放）	'[>=1000000]#,##0.0,,"M";[>=1000]#,##0.00,"K";#,##0'	2.9M、540.18K、500
百分比	'0%'	50%、85%

格式代码语法： OOXML 支持最多 2 个方括号条件和一个默认格式：[condition1]format1;[condition2]format2;defaultFormat。每个末尾的 , 都会将数字除以 1,000（因此 ,, 表示除以 1M）。

重要：valAxisLabelFormatCode 不支持 OOXML 条件方括号 [>=1000]。 根据数据范围，为坐标轴使用简单格式：

坐标轴范围	valAxisLabelFormatCode	显示效果
最高约为 999K	'"$"#,##0,"K"'	$0K、$100K、$500K
最高约为 10M 及以上	'"$"#,##0.0,,"M"'	$0.0M、$0.5M、$1.0M
最高约为 999	'"$"#,##0'	$0、$100、$500

dataLabelFormatCode 使用支持方括号条件的条件格式 currFmt，而 valAxisLabelFormatCode 使用简单格式。在条形图中始终设置 showValue: true 和 dataLabelPosition: "outEnd"，这样读者无需对照坐标轴即可看到准确数值。

---

间距

标记	值	用途
xs	0.125"	分组元素内部
sm	0.25"	标签与数值之间、图标与文本之间
md	0.375"	卡片内各区块之间
lg	0.5"	卡片之间、主要区块之间
xl	0.75"	内容区域之间

布局网格（10" × 5.625"）

Margins:       0.5" from all edges
Content area:  9.0" wide × ~4.5" tall
Title zone:    y = 0.3"
Content zone:  y = 1.0" to y = 5.0"
Footer zone:   y = 5.2"
Card gap:      0.25" - 0.3"

---

Logo 放置

查找 Logo

find ~/Desktop ~/Downloads ~/Documents -maxdepth 3 -iname "*logo*" \( -name "*.png" -o -name "*.svg" -o -name "*.jpg" \) 2>/dev/null

放置模式

幻灯片类型	位置	尺寸	备注
标题页（左上角）	x:0.5, y:0.4	w:1.5, h:0.5	低调的品牌标识
标题页（居中）	x:4.0, y:0.8	w:2.0, h:0.7	位于标题文本上方
内容页	x:8.5, y:0.2	w:1.0, h:0.35	每页右上角
结束页	x:3.5, y:1.5	w:3.0, h:1.0	居中，主视觉尺寸

Logo 规则

• 始终使用 sizing: { type: "contain", w, h } 以保持纵横比
• 内容页：宽度最多为 1"，不要喧宾夺主
• 标题页/结束页：宽度最多为 3"，突出品牌形象
• 深色模式：如果有白色/浅色 Logo 版本，请使用（询问用户）
• 幻灯片母版：如果 Logo 要显示在每一页上，请将其添加到母版定义中

---

图标

流程：react-icons → sharp → PNG → PptxGenJS

npm install -g react-icons react react-dom sharp

优先使用 Lucide（react-icons/lu）或 Feather（react-icons/fi）——它们与 Linear/Vercel 的图标风格相符。

软件包	导入项	风格
react-icons/lu	Lucide	Linear 风格，简洁
react-icons/fi	Feather	纤细、现代
react-icons/hi2	Heroicons v2	类似 Apple 风格
react-icons/tb	Tabler	笔画统一

图标尺寸

场景	显示尺寸	颜色
KPI 卡片图标	0.35" × 0.35"	深色背景上用强调色，浅色背景上用柔和色
特性行图标	0.4" × 0.4"	强调色圆圈内用白色
章节分隔符	0.5" × 0.5"	强调色
行内项目符号	0.25" × 0.25"	text-secondary

---

可复用组件

底部提示框（标准化）

许多幻灯片会以一个突出显示的提示框收尾（建议、关键洞见、总影响）。所有幻灯片中的提示框在视觉上必须完全一致：

属性	值	说明
框高	0.6"	始终为 0.6"，绝不可用 0.5"、0.7" 或 0.9"
文本高度	0.5"	加上内边距后可放入 0.6" 的框内
字号	11pt	始终为 11pt 粗体，绝不可用 12pt 或 13pt
字体	theme.font.body	粗体，左对齐，valign: "middle"
框的 x/w	x: 0.5, w: 9.0	占满内容宽度
文本的 x/w	x: 0.7, w: 8.6	与框边缘内缩 0.2"
文本 y 偏移	框的 y + 0.05"	使文本在框内垂直居中
圆角半径	0.06"	所有提示框保持一致

// Standard bottom callout — copy this pattern exactly
s.addShape(pres.shapes.RECTANGLE, {
  x: 0.5, y: calloutY, w: 9.0, h: 0.6,
  fill: { color: "DCFCE7" },  // or theme.accentMuted, "FEF3C7", etc.
  line: { color: theme.status.positive, width: 0.75 },
  rectRadius: 0.06,
});

s.addText("Callout text here.", {
  x: 0.7, y: calloutY + 0.05, w: 8.6, h: 0.5,
  fontSize: 11, fontFace: theme.font.body, bold: true,
  color: "166534", align: "left", valign: "middle",
});

表格 + 提示框布局（避免重叠）

在表格下方放置提示框之前，务必先计算表格底部的位置。 PptxGenJS 表格不会自动报告自身高度，因此必须手动计算：

tableBottom = tableY + (rowCount × rowH)
calloutY = tableBottom + 0.15"  // minimum 0.15" gap

确认 calloutY + 0.6"（提示框高度）< 5.2"（页脚区域）。 如果不满足，应减小 rowH 或表格字号；绝不能让提示框与页脚重叠。

行数（含表头）	rowH: 0.32"	rowH: 0.36"	rowH: 0.42"	rowH: 0.48"	rowH: 0.55"
6 行	1.92"	2.16"	2.52"	2.88"	3.30"
7 行	2.24"	2.52"	2.94"	3.36"	3.85"
8 行	2.56"	2.88"	3.36"	3.84"	4.40"
11 行	3.52"	3.96"	4.62"	—	—

表格从 y: 1.0" 开始，且提示框需要 0.75"（0.15" 间距 + 0.6" 框）时，为避免触及页脚，表格高度上限为 3.45"。请据此选择 rowH。

跨幻灯片一致性规则

重复元素在所有幻灯片中都必须使用相同尺寸：

1. 底部提示框 — 每张幻灯片使用相同的 h、fontSize 和内边距（参见上述标准）
2. 图表字号 — 如果多张幻灯片中包含条形图/折线图，所有图表都使用相同的 dataLabelFontSize、catAxisLabelFontSize 和 valAxisLabelFontSize
3. 表格样式 — 表头行样式（hdr()）和单元格样式（cell()）应定义为辅助函数，并复用
4. 卡片尺寸 — 如果多张幻灯片使用统计卡片，应保持卡片的宽度、高度和圆角半径一致
5. 章节徽章位置 — 影响力徽章（例如 “$400K-$800K”）应使用相同的 x、y、w、h 和 fontSize

规则：在脚本顶部定义可复用常量，用于任何出现在多张幻灯片中的尺寸。

---

幻灯片构成

变换布局 — 首要规则

同一种布局连续使用不得超过两次。请轮换使用：

类型	使用时机	元素
标题幻灯片	开场/收尾	主视觉文字、副标题、徽标、日期
KPI 仪表板	执行摘要	3-5 张卡片、大号数字
图表 + 洞见	附带背景信息的数据	60/40 分栏
全宽图表	图表即主题	全宽展示、叠加提示框
图标特性网格	特性、支柱	3-4 行图标 + 文本
数据表	财务数据、对比	样式化行、等宽数字
章节分隔页	章节之间	深色/强调色背景上的醒目标题
引言	用户评价	大号斜体文字、署名
大号数字	单一关键统计数据	居中显示的超大指标
对比	前后对比、对照	并排分栏
图片 + 文本	产品、案例研究	图片半幅出血
结束页	结尾	徽标、CTA、联系方式

---

反模式（绝对不要这样做）

1. 绝对不要在标题、副标题或各级标题下方添加水平装饰线/条 —— 这是最明显的 AI 痕迹。不要在文字下方放置细长矩形（高度：0.03-0.05）作为装饰分隔线。标题页不要放，章节分隔页不要放，结尾页不要放，任何地方都不要放。如果你觉得幻灯片需要视觉分隔，请改用留白或浅色面板。
2. 不要在形状上使用渐变填充 —— 使用纯色 + 细微边框
3. 不要使用浓重的阴影 —— 不透明度最高为 0.1，模糊度为 6
4. 不要在连续的幻灯片中重复布局
5. 不要居中对齐正文 —— 除标题/KPI 外，所有内容都左对齐
6. 字体不要超过 2 种（另加 1 种等宽字体）
7. 不要堆砌大段文字 —— 每张幻灯片正文最多 6 行
8. 不要使用装饰性形状 —— 不要随意放置圆形、三角形、曲线
9. 不要使用剪贴画 —— 使用 Lucide/Feather 图标
10. 不要使用彩色卡片背景 —— 卡片使用 bg-surface + 细微边框
11. 不要使用 Unicode 项目符号 —— 使用 bullet: true
12. 不要在同一套幻灯片中混用浅色和深色样式
13. 不要使用未设置格式的图表数据标签 —— 如果使用 showValue: true，就必须同时设置 dataLabelFormatCode。单独设置 valAxisLabelFormatCode 不会格式化数据标签。为获得最佳效果，请使用带原始值的 OOXML 条件格式。
14. 不要在窄面板中放置未经尺寸检查的长文本 —— 在宽度小于 4" 的任何容器中添加正文前，先估算行数（字符数 ÷ 每行字符数），并确认文本适合容器高度。如果放不下，请减小字号或缩短文本。
15. 不要让标注框样式不一致 —— 所有全宽底部标注框在每张幻灯片中都必须使用相同高度（0.6"）、文本字号（11pt）和内边距。定义一次标注框样式，并原样复制。
16. 不要让标注框与表格重叠 —— 始终计算 tableBottom = tableY + (rows × rowH)，并将标注框放在至少 tableBottom + 0.15" 的位置。未经确认不会与表格重叠时，绝不要硬编码标注框的 y 坐标。
17. 不要让图表字号不一致 —— 如果多张幻灯片中包含图表，请统一使用 dataLabelFontSize、catAxisLabelFontSize 和 valAxisLabelFontSize 的值。将这些值定义为常量并重复使用。

---

QA（必需）

假设存在问题。首次渲染永远不会正确。

内容检查

python -m markitdown output.pptx
python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|click to"

视觉 QA（使用子 Agent）

python scripts/office/soffice.py --headless --convert-to pdf output.pptx
pdftoppm -jpeg -r 150 output.pdf slide

子 Agent 提示词：

Inspect these slides. Assume issues exist — find them.
Look for:
- TEXT OVERFLOW: Numbers or titles that wrap to a second line inside their container. Also check body text in narrow panels (<4" wide) — long paragraphs at font sizes >11pt will overflow.
- ACCENT LINES: Any thin horizontal bars/lines under titles or headings (must be removed)
- CHART DATA LABELS: Raw unformatted numbers on data labels (e.g., "2888000" instead of "$2,889K"). This is the #1 chart bug — valAxisLabelFormatCode does NOT format data labels.
- CHART AXES: Raw unformatted numbers on axes (should be $500K not 500000)
- Overlapping elements, cramped spacing (<0.3"), insufficient margins (<0.5")
- Low contrast, text-only slides, repeated layouts, placeholder text
- Mode inconsistency (light elements on dark or vice versa)
- Big numbers that should be abbreviated ($5.3M not $5,307,540)
- CALLOUT INCONSISTENCY: Bottom callout boxes with different heights, font sizes, or padding across slides (all must be h:0.6", fontSize:11)
- TABLE-CALLOUT OVERLAP: Callout boxes overlapping tables — calculate tableY + (rows × rowH) and verify callout clears it
- CHART FONT INCONSISTENCY: Different dataLabelFontSize, catAxisLabelFontSize, or valAxisLabelFontSize between charts on different slides

修复 → 重新渲染 → 检查 → 重复，直到没有问题。至少完成一轮修复。

---

依赖项

npm install -g pptxgenjs                          # Creation
npm install -g react-icons react react-dom sharp  # Icons
pip install "markitdown[pptx]" Pillow             # Reading + QA
# Also: LibreOffice (soffice) + Poppler (pdftoppm) for visual QA

实现

阅读 REFERENCE.md，了解 PptxGenJS API 模式，以及浅色和深色模式下的完整幻灯片组合代码。

品牌背景（可选）

如果工作目录中存在 brand-profile.json，请在制作幻灯片前阅读。用品牌色（主色、次色、背景色）覆盖默认的 RRBC 调色板；如果有品牌字体，则使用品牌字体（否则回退到系统字体）；并在标题页和页眉中加入品牌名称。此配置文件由 brand-dna 技能生成。