可验证的机构级PDF演示与数据可视化系统
此技能与 verifiable-pdf-pipeline(数据完整性)和 editorial-page-layout-guidelines(网格几何)配合,生成出版级别的16:9深色高管幻灯片和信纸浅色瑞士象牙白机构报告,灵感源自麦肯锡、Stripe Press、WEF 和《经济学人》。
1. 核心不变法则:内容先于美学
使用此技能构建的每份演示文稿或报告必须遵守 verifiable-pdf-pipeline/SKILL.md 中定义的10条反作弊硬规则:
- 零手写数据气隙 — 所有数字必须从
data/raw/中的不可变原始文件解析。 - 现实与不变编译器 — 强制实施 Pydantic 域边界和会计恒等式。
- 反循环验证 — 独立的原始文件重新计算 + Python AST 检查,禁止硬编码的字面量断言。
- 原子溯源账本 — 每个已发布的标量在
data/provenance_ledger.json中一一对应。 - 负能力与神圣的“N/A” — 真正的上游空值显式呈现为
[N/A],而非虚构的替代值。 - 编译锁定 — PDF 编译器调用
verify_integrity.py,并在非零退出时中止。 - 类别与单位守卫 — 绝不混合不可通约的范围或测试方法。
- 法定证明 — 任何监管/关税声明都需要官方公报 ID。
- 科学分类与注册表验证 — 对照实时 GBIF/OpenTree/iNaturalist 注册表,逐字核对双名法、权威信息、系统发育和 IUCN 状态。
- 渲染后文本接地(
vedit prose) — 最终 PDF 中渲染的每个数字都可追溯到provenance_ledger.json、summary_metrics.json或background_citations.json中由 DOI 支持的条目。
2. 四大黄金设计法则
法则 1:60-30-10 色彩层次(浅色与深色模式)
- 浅色瑞士编辑模式(信纸报告):
60%画布:瑞士暖象牙白(#fcfbf9)—— 通过onPage显式绘制。30%骨架:深海军蓝(#0f2b48)、石板灰(#334155)、钢灰(#64748b)、发丝线(#cbd5e1)、微淡色调(#f1f5f9)。10%信号强调色:钴蓝(#0284c7)、琥珀色(#d97706)、翡翠绿(#059669)、信号红(#dc2626—— 仅限风险/激增)。
- 深色高管模式(16:9 幻灯片):
60%画布:深曜石黑(#0b0f19)或午夜海军蓝(#051c2c)—— 必须在onFirstPage/onLaterPages中在流式对象渲染之前全出血绘制,绝不能依赖默认的白色PDF纸!30%骨架与高对比度文本:微色调带(#111827/#0a253a)、发丝线(#243247)、纯白标题(#ffffff)、清晰浅色正文(>= #e2e8f0,字号>= 9.5–10 pt)、次要说明文字(>= #cbd5e1,深色上绝不用昏暗的#64748b–#94a3b8)。当参数化线框波浪或明亮艺术作品靠近文字时,始终在封面排版后方放置微妙的水平深色遮罩。10%信号强调色:电光钴蓝(#38bdf8)、亮琥珀色(#fbbf24)、翡翠绿(#34d399)、信号红(#f87171)。
法则 2:发丝线与留白重力(零方框卡片)
- 绝不要将指标或文本内容困在厚重的矩形
BOX描边或INNERGRID网页仪表板方框中。 - 通过无边界的色调带(深色
#111827/ 浅色#f1f5f9)对 KPI 和标注进行分组,顶部冠以清晰的1.2 pt顶部强调发丝线,宽松的12–16 pt列间距,以及 booktabs 风格的 Tufte 表格(零垂直线)。
法则 3:明托金字塔行动标题
- 每张幻灯片或报告部分以一个完整的、有主张的论断开头,而不是被动的主题标签:
- 禁止:
"全球排放趋势" - 必需:
"经合组织五国减排 -25.0%,但新兴三国激增 +235.8%,推动面板总量达到 23.52 Gt CO2e。"
法则 4:校准的垂直填充预算 + 视觉检查
- 信纸报告(
612×792 pt): 目标垂直填充率85%–92%(最低>= 82%)。 - 16:9 幻灯片(
960×540 pt): 目标垂直填充率72%–88%(最低>= 72%)。 - 绝不要将自动通过视为最终结果:通过
audit_pdf.py导出 180 DPI 的 PNG 预览,并目视检查每个渲染页面的标签重叠、孤行标题换行和光学平衡。
3. 机构级数据可视化配方(300 DPI,透明背景)
以 dpi=300、transparent=True 渲染所有图表,移除顶部/右侧轴线,并使用主题匹配的调色板(dark vs light):
- 双面板时间序列 + 加速度图: 历史月度/日度轨迹,带事件阴影和直接起点/峰值标注,配以十年/周期速率柱状图。
- 堆叠质量平衡面积图 + 指数轨迹: 堆叠流量体积,带直接右边缘终端标签(零独立浮动图例框!),配以
Base = 100结构性离散线。 - 解耦象限散点图 + 哑铃压缩: 二维增长与结果散点图,带阴影目标象限 + 针对密集簇的引导箭头,配以基线到当前的水平哑铃图。
- Stephen Few 水平子弹图: 3 个定性背景带 + 主要性能条 + 垂直琥珀色基线/目标刻度 + 右侧对齐的差值文本(使用
ax.spines["bottom"].set_bounds(...)修剪 x 轴脊柱)。 - 内存中无头 Tufte 迷你图:
46–66 pt × 13–16 pt的微线条,渲染到io.BytesIO()缓冲区,并直接嵌入 ReportLab 表格单元格,使用语义化的翡翠绿/信号红终端点。 - 起点-目的地矩阵热图 + 山脊线 KDE: 顺序调色板,带对比切换的双排版或重叠分布山脊线,标记 $P_{50}$ 和 $P_{90}$。
4. 生产级别 ReportLab 实现模式
4.1 全出血画布绘制(对深色和象牙白主题至关重要)
始终注册一个 onPage 回调,使得画布背景在每一页上绘制在所有流式对象之下:
from reportlab.lib import colors
def paint_background(canv, _doc, bg_hex="#0b0f19", accent_hex="#38bdf8", page_w=960.0, page_h=540.0):
canv.saveState()
canv.setFillColor(colors.HexColor(bg_hex))
canv.rect(0, 0, page_w, page_h, fill=1, stroke=0)
if canv.getPageNumber() == 1:
canv.setFillColor(colors.HexColor(accent_hex))
canv.rect(0, page_h - 4, page_w, 4, fill=1, stroke=0)
canv.restoreState()
4.2 安全的 Inter TTF 发现与干净回退
绝不要不注册 TTF 就硬编码 "Inter-SemiBold"——使用一个辅助函数,它检查 INTER_FONT_DIR 和标准操作系统字体路径,并干净地回退到 Helvetica:
import os
from pathlib import Path
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont
def register_editorial_fonts() -> dict[str, str]:
search = [Path(os.environ["INTER_FONT_DIR"])] if os.environ.get("INTER_FONT_DIR") else []
search += [Path.home() / "Library/Fonts", Path("/Library/Fonts"), Path("/usr/share/fonts/truetype/inter")]
files = {"regular": "Inter-Regular.ttf", "semibold": "Inter-SemiBold.ttf",
"bold": "Inter-Bold.ttf", "italic": "Inter-Italic.ttf", "bold_italic": "Inter-BoldItalic.ttf"}
found = {r: d / f for d in search if d.is_dir() for r, f in files.items() if (d / f).is_file()}
if {"regular", "bold", "italic", "bold_italic"}.issubset(found):
for role, name in [("regular", "Inter-Regular"), ("bold", "Inter-Bold"),
("italic", "Inter-Italic"), ("bold_italic", "Inter-BoldItalic")]:
pdfmetrics.registerFont(TTFont(name, str(found[role])))
semi = "Inter-Bold"
if "semibold" in found:
pdfmetrics.registerFont(TTFont("Inter-SemiBold", str(found["semibold"])))
semi = "Inter-SemiBold"
pdfmetrics.registerFontFamily("Inter-Regular", normal="Inter-Regular", bold="Inter-Bold",
italic="Inter-Italic", boldItalic="Inter-BoldItalic")
return {"regular": "Inter-Regular", "semibold": semi, "bold": "Inter-Bold",
"italic": "Inter-Italic", "bold_italic": "Inter-BoldItalic", "mono": "Courier"}
return {"regular": "Helvetica", "semibold": "Helvetica-Bold", "bold": "Helvetica-Bold",
"italic": "Helvetica-Oblique", "bold_italic": "Helvetica-BoldOblique", "mono": "Courier"}
4.3 双通道运行页眉与动态页码
使用 reportlab.pdfgen.canvas.Canvas 的子类,在 showPage() 中保存页面状态字典,并在 save() 中打上 "Page X of Y" 或 "Slide X / Y" 的印记(参见 examples/reportlab_premium_template.py)。
5. 2023 咨询旗舰模式(WeasyPrint + 纯矢量内联 SVG)
对于基于旗舰级 2023 年机构出版物(《量子技术监测》、《生成式 AI 的经济潜力》、《全球经济情报》、《组织状态》)的关键级演示文稿,将 WeasyPrint(@page { size: 960pt 540pt; margin: 0; }) 与 100% 纯矢量内联 <svg> 展品配对:
- 深色英雄 / 纯白数据极性节奏(绝不单调):
- 封面英雄: 深午夜海军蓝(
#051C2C)过渡到钴蓝(#0A2E8A),覆盖 42 股参数化双曲贝塞尔线框波浪(#2251FF/#00A9F4)和右侧干净的编辑式英雄艺术作品。 - 执行摘要: 全出血
#051C2C,清晰的28 pt白色衬线标题,下方为1.2 pt白色水平标尺,3 列宽松无衬线列,以及 3 个巨大的青色/蓝色衬线 KPI。 - 拆分章节分隔页: 顶部
48%全出血明亮艺术作品,锚定一个120 pt粗体白色衬线数字(1、2),底部52%纯白色,带有220 pt左缩进衬线章节标题和两列框架文本。 - 数据展示幻灯片: 纯
#FFFFFF画布,19.5–22 pt粗体衬线行动标题,下方为1.1 pt#051C2C标尺,底部微妙的脚注分隔线,以及一个右下角的#9AE6FF冰青色章节进度药丸。
- 封面英雄: 深午夜海军蓝(
- 高对比度编辑衬线 + 几何无衬线配对:
- 展示衬线(
Charter/Georgia/Baskerville Bold): 封面标题、章节数字、幻灯片行动标题、巨大的54 pt#2251FFKPI 标注和中心环形图总计。 - 数据无衬线(
Inter/Helvetica Neue): 图表注释、副标题、表格单元格、脚注和影响分析文本。
- 展示衬线(
- 四层麦肯锡蓝色彩渐变(零彩虹杂色):
#051C2C午夜海军蓝(锚定总计、基线、深度收缩)→#06319C深皇家蓝 →#2251FF电光蓝(焦点差值、巨大 KPI、扩张激增)→#00A9F4鲜亮青色 →#9AE6FF冰青色(次要份额和章节药丸)。
- 标志性矢量 SVG 展品原型:
- 质量平衡瀑布/桥接图: 锚定条(
#051C2C)、浮动增加值(#2251FF)和减少值(#00A9F4)、虚线步骤连接线、顶部方括号跨度标注和浮动衬线净差值。 - 小倍数墙 + 灰色
»影响侧边栏: 分组的5 + 3指数轨迹卡片,配以右侧#EFEFEF侧边栏,由一个圆形#051C2C»V 形徽章(3 pt白色环)连接。 - 10×10 圆角方形华夫格单元矩阵: 从底部向上填充的
10×10网格(#E5E7EB轨道,四层蓝色填充),在灰色空白区域居中放置粗体数字。 - 环形图 + 100% 堆叠份额变化: 5 步蓝色环形图(
2 px白色切片分隔线,衬线中心总计)配以2000年与2024年的列,由半透明流动带连接。 - WeasyPrint SVG 护栏: 在 flex 容器内,始终为内联
<svg>指定明确的width/height(以pt为单位)(并设置.slide { height: 539.5pt; break-after: page; break-inside: avoid; }),以防止亚像素空白溢出页或300 px的 SVG 折叠。绝不要在 WeasyPrint 中在<text>上使用 SVG 2 的paint-order="stroke"(它会在文本填充之上描边);而是使用干净的标签偏移或显式的背景<rect>。
- 质量平衡瀑布/桥接图: 锚定条(
- 全出血编辑摄影杂志模式(
612 × 792 pt信纸纵向,WeasyPrint): 当制作摄影优先的编辑杂志(Kinfolk × Cereal × Condé Nast Traveler × National Geographic 风格,如demos/felis-mundi-magazine/所示)时:- 排版与纸张质感: 将温暖的无涂层档案纸(
#FAF8F5)和深炭黑墨水(#161616)与高对比度 Didone 展示衬线(Didot/Bodoni 72)、温暖的书卷气衬线正文(Charter/Baskerville,字号9 pt,行距1.5×)以及宽距大写无衬线元数据(Inter,6.5–7 pt,+0.18em字间距)配对。在全出血摄影上无缝地将运行中的页脚和鸣谢文字翻转为纯#FFFFFF。 - 统一的摄影(
>= 50%边缘到边缘出血): 在一个锁定的主摄影胶片身份核心下生成每一版(参见references/image_generation_recipes.md§5),在相邻页面之间变化跨页架构(100% 封面 → 61% 顶部出血 → 65% 右侧垂直列 → 100% 摄影散文 → 76% 双联画,带4 pt白色印刷版距 → 68% 底部出血 → 77% 联系表三联画 → 100% 结尾黄昏版权页),并透明地标注 AI 摄影,同时附带 SHA-256 版次清单。 - WeasyPrint 杂志护栏(经验证):
- 首字下沉(
float: left): 绝不要在 WeasyPrint 67.0 的 CSS Grid 或 Flexbox 项目内放置float: left首字下沉(它会缩小文本列或导致首字下沉错位/碰撞)。对于分栏杂志页面,使用position: absolute块级列(display: block),以使首字下沉完全左对齐并实现干净的多行环绕。 - 无缝渐变遮罩: 绝不要在 WeasyPrint 中将部分高度的
linear-gradient叠加框放置在明亮的天空或雪地上(Cairo 会沿着框边缘绘制一条微弱的 1 px 发丝缝)。始终将每个遮罩叠加层的大小设为照片容器的100%,并在透明停止点内渐变为rgba(..., 0)。 - 旋转边缘注释: 使用
top: 18pt; right: 16pt; transform-origin: 100% 0%; transform: rotate(90deg);锚定垂直的右侧边缘注释。
- 首字下沉(
- 排版与纸张质感: 将温暖的无涂层档案纸(