Verifiable Institutional PDF Presentation & Data Visualization System
This skill pairs with verifiable-pdf-pipeline (data integrity) and editorial-page-layout-guidelines (grid geometry) to produce publication-grade 16:9 dark executive slide decks and Letter light Swiss-ivory institutional reports inspired by McKinsey, Stripe Press, WEF, and The Economist.
1. Core Invariant: Substance Precedes Aesthetics
Every presentation or report built with this skill must obey the 10 Anti-Cheat Hard Rules defined in verifiable-pdf-pipeline/SKILL.md:
- Zero-Handwritten-Data Air-Gap — parse all numbers from immutable raw files in
data/raw/. - Reality & Invariant Compiler — enforce Pydantic domain bounds and accounting identities.
- Anti-Circular Verification — independent raw-file re-computation + Python AST check banning hardcoded literal assertions.
- Atomic Provenance Ledger — every published scalar mapped 1:1 in
data/provenance_ledger.json. - Negative Capability & The Sacred "N/A" — genuine upstream nulls render explicitly as
[N/A]rather than fabricated proxies. - Compilation Latch — PDF compilers invoke
verify_integrity.pyand abort on non-zero exit. - Category & Unit Guard — never blend incommensurable scopes or test methods.
- Statutory Proof — official gazette IDs required for any regulatory/tariff claim.
- Scientific Taxonomy & Registry Verification — reconcile binomials, authorities, phylogeny, and IUCN status verbatim against live GBIF/OpenTree/iNaturalist registries.
- Post-Render Prose Grounding (
vedit prose) — every rendered numeral in the final PDF traces back toprovenance_ledger.json,summary_metrics.json, or a DOI-backed entry inbackground_citations.json.
2. The 4 Golden Design Laws
Law 1: The 60-30-10 Color Hierarchy (Light & Dark Modes)
- Light Swiss Editorial Mode (Letter Reports):
60%Canvas: Swiss Warm Ivory (#fcfbf9) — painted explicitly viaonPage.30%Scaffolding: Deep Navy (#0f2b48), Slate (#334155), Steel (#64748b), Hairlines (#cbd5e1), Subtle Tint (#f1f5f9).10%Signal Accent: Cobalt (#0284c7), Amber (#d97706), Emerald (#059669), Signal Crimson (#dc2626— risk/surge only).
- Dark Executive Mode (16:9 Slide Decks):
60%Canvas: Deep Obsidian (#0b0f19) or Midnight Navy (#051c2c) — MUST be painted full-bleed inonFirstPage/onLaterPagesBEFORE flowables render, never relying on default white PDF paper!30%Scaffolding & High-Contrast Text: Subtle Tonal Band (#111827/#0a253a), Hairlines (#243247), Pure White Titles (#ffffff), Crisp Light Body (>= #e2e8f0at>= 9.5–10 pt), Secondary Captions (>= #cbd5e1, never dim#64748b–#94a3b8prose on dark). Always place a subtle horizontal dark scrim behind cover typography when parametric wireframe waves or bright artwork sit near text.10%Signal Accent: Electric Cobalt (#38bdf8), Bright Amber (#fbbf24), Emerald (#34d399), Signal Crimson (#f87171).
Law 2: Hairline & Whitespace Gravity (Zero Boxed Cards)
- Never trap metrics or prose inside heavy rectangular
BOXstrokes orINNERGRIDweb dashboard boxes. - Group KPIs and callouts via borderless tonal bands (
#111827dark /#f1f5f9light) crowned with a crisp1.2 pttop accent hairline, generous12–16 ptcolumn gutters, and booktabs-style Tufte ledgers (zero vertical lines).
Law 3: Minto Pyramid Action Titles
Every slide or report section opens with one complete, assertive claim, not a passive topic label:
- Prohibited:
"Global Emissions Trends" - Required:
"OECD-5 Cut Emissions -25.0%, Yet Emerging-3 Surged +235.8% to Lift Panel Totals to 23.52 Gt CO2e."
Law 4: Calibrated Vertical Fill Budgets + Visual Inspection
- Letter Reports (
612×792 pt):85%–92%target vertical fill (min >= 82%). - 16:9 Decks (
960×540 pt):72%–88%target vertical fill (min >= 72%). - Never treat an automated pass as the final word: export 180-DPI PNG previews via
audit_pdf.pyand visually inspect every rendered page for label overlaps, widow headline wraps, and optical balance.
3. Institutional Data Visualization Recipes (300 DPI, Transparent)
Render all charts with dpi=300, transparent=True, top/right spines stripped, and theme-matched palettes (dark vs light):
- Dual-Panel Time Series + Rate Acceleration: Historical monthly/daily trajectory with event shading and direct start/peak annotations paired with decadal/period rate bars.
- Stacked Mass-Balance Area + Indexed Trajectory: Stacked flow volumes with direct right-edge terminal labels (zero separate floating legend boxes!) paired with
Base = 100structural divergence lines. - Decoupling Quadrant Scatter + Dumbbell Compression: 2D growth-vs-outcome scatter with shaded target quadrant + leader arrows for tight clusters, paired with baseline-to-current horizontal dumbbells.
- Stephen Few Horizontal Bullet Graphs: 3 qualitative background bands + primary performance bar + vertical amber baseline/target tick + right-aligned delta text (trimmed x-axis spine using
ax.spines["bottom"].set_bounds(...)). - In-Memory Headless Tufte Sparklines:
46–66 pt × 13–16 ptmicro-lines rendered intoio.BytesIO()buffers and embedded directly inside ReportLab table cells with semantic emerald/crimson terminal dots. - Origin-Destination Matrix Heatmap & Ridgeline KDEs: Sequential palette with contrast-switched dual typography or overlapping distribution ridges marking $P_{50}$ and $P_{90}$.
4. Production ReportLab Implementation Patterns
4.1 Full-Bleed Canvas Painting (Critical for Dark & Ivory Themes)
Always register an onPage callback so the canvas background paints underneath every flowable on every page:
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 Safe Inter TTF Discovery with Clean Fallback
Never hardcode "Inter-SemiBold" without registering the TTF first—use a helper that checks INTER_FONT_DIR and standard OS font paths and falls back cleanly to 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 Two-Pass Running Headers & Dynamic Foliation
Use a subclass of reportlab.pdfgen.canvas.Canvas saving page state dicts in showPage() and stamping "Page X of Y" or "Slide X / Y" in save() (see examples/reportlab_premium_template.py).
5. 2023 Consulting Flagship Mode (WeasyPrint + Pure Vector Inline SVG)
For keynote-grade decks modeled on flagship 2023 institutional publications (Quantum Technology Monitor, The Economic Potential of Generative AI, Global Economics Intelligence, The State of Organizations), pair WeasyPrint (@page { size: 960pt 540pt; margin: 0; }) with 100% pure-vector inline <svg> exhibits:
- Dark-Hero / Pure-White-Data Polarity Cadence (Never Monotone):
- Cover Hero: Deep Midnight Navy (
#051C2C) transitioning to Cobalt (#0A2E8A), overlaid with a 42-strand parametric hyperbolic Bezier wireframe wave (#2251FF/#00A9F4) and clean editorial hero art on the right. - Executive Summary: Full-bleed
#051C2C, crisp28 ptwhite serif headline over a1.2 ptwhite horizontal rule, 3 airy sans columns, and 3 giant cyan/blue serif KPIs. - Split Chapter Dividers: Top
48%full-bleed luminous artwork anchored by a120 ptbold white serif numeral (1,2), bottom52%pure white with220 ptleft-indented serif chapter headline and 2-column framing copy. - Data Exhibit Slides: Pure
#FFFFFFcanvas,19.5–22 ptbold serif action title above a1.1 pt#051C2Crule, subtle bottom footnote separator, and a bottom-right#9AE6FFice-cyan section progress pill.
- Cover Hero: Deep Midnight Navy (
- High-Contrast Editorial Serif + Geometric Sans Pairing:
- Display Serif (
Charter/Georgia/BaskervilleBold): Cover titles, section numerals, slide action titles, giant54 pt#2251FFKPI callouts, and center donut totals. - Data Sans (
Inter/Helvetica Neue): Chart annotations, subtitles, ledger cells, footnotes, and implications copy.
- Display Serif (
- The 4-Tier McKinsey Blue Chromatic Ramp (Zero Rainbow Clutter):
#051C2CMidnight Navy (anchor totals, baselines, deep contractions) →#06319CDeep Royal →#2251FFElectric Blue (focal deltas, giant KPIs, expansion surges) →#00A9F4Vivid Cyan →#9AE6FFIce Cyan (secondary shares & section pills).
- Signature Vector SVG Exhibit Archetypes:
- Mass-Balance Waterfall / Bridge Chart: Anchor bars (
#051C2C), floating additions (#2251FF) and reductions (#00A9F4), dashed step connectors, top square-bracket span callouts, and floating serif net delta. - Small-Multiples Wall + Grey
»Implications Sidebar: Grouped5 + 3indexed trajectory cards paired with a right-hand#EFEFEFsidebar bridged by a circular#051C2C»chevron badge (3 ptwhite ring). - 10×10 Rounded-Square Waffle Unit Matrix: Bottom-up filled
10×10grids (#E5E7EBtrack, 4-tier blue fill) with centered bold numerals inside the gray negative space. - Donut Ring + 100% Stacked Share Shift: 5-step blue donut (
2 pxwhite slice dividers, serif center total) paired with2000vs2024columns linked by translucent flow ribbons. - WeasyPrint SVG Guardrails: Inside flex containers, always give inline
<svg>explicitwidth/heightinpt(and set.slide { height: 539.5pt; break-after: page; break-inside: avoid; }) to prevent sub-pixel blank spill pages or300 pxSVG collapse. Never use SVG 2paint-order="stroke"on<text>in WeasyPrint (it strokes over the text fill); use clean label offsets or an explicit backdrop<rect>instead.
- Mass-Balance Waterfall / Bridge Chart: Anchor bars (
- Full-Bleed Editorial Photo Magazine Mode (
612 × 792 ptLetter Portrait, WeasyPrint): When producing photography-first editorial magazines (Kinfolk × Cereal × Condé Nast Traveler × National Geographic style, as demonstrated indemos/felis-mundi-magazine/):- Typography & Paper Stock: Pair warm uncoated archival paper (
#FAF8F5) and deep carbon charcoal ink (#161616) with high-contrast Didone display serifs (Didot/Bodoni 72), warm book serif body copy (Charter/Baskervilleat9 pt,1.5×leading), and wide-tracked uppercase sans metadata (Inter,6.5–7 pt,+0.18emtracking). Flip running folios and credits seamlessly to pure#FFFFFFover full-bleed photography. - Cohesive Photography (
>= 50%Edge-to-Edge Bleed): Generate every plate under one locked Master Photographic Film Identity Core (seereferences/image_generation_recipes.md§5), vary spread architecture across adjacent pages (100% cover → 61% top bleed → 65% right vertical column → 100% photo essay → 76% diptych with4 ptwhite print gutters → 68% bottom bleed → 77% contact-sheet triptych → 100% closing dusk colophon), and credit AI photography transparently alongside a SHA-256 plate manifest. - WeasyPrint Magazine Guardrails (Empirically Verified):
- Drop Caps (
float: left): Never place afloat: leftdrop cap inside a CSS Grid or Flexbox item in WeasyPrint 67.0 (it shrinks the text column or mis-offsets/collides the drop cap). Useposition: absoluteblock columns (display: block) for split magazine pages so drop caps sit 100% flush-left with clean multi-line wrap. - Seamless Gradient Scrims: Never place a partial-height
linear-gradientoverlay box over bright sky or snow in WeasyPrint (Cairo paints a faint 1 px hairline seam along the box edge). Always size every scrim overlay to100%of its photo container and fade torgba(..., 0)inside the transparent stops. - Rotated Marginal Credits: Anchor vertical right-edge credits with
top: 18pt; right: 16pt; transform-origin: 100% 0%; transform: rotate(-90deg);(neverbottom right, which swings the rotated text below the container clip). - Clip-Aware Photo-Area Audit: Never trust raw
page.get_image_rects(xref)when using CSSobject-fit: cover(it returns the unclipped draw matrix and inflates coverage). Verify true visible photo coverage using an in-memory dual-key raster diff (demos/felis-mundi-magazine/scripts/audit_magazine.py) that replaces embedded images with two distinct solid key colors and counts exact changed pixels at 72 DPI—asserting>= 50.0%visible photography and>= 2full-bleed trim edges on every page.
- Drop Caps (
- Typography & Paper Stock: Pair warm uncoated archival paper (
- Scientific Monograph × Learning Magazine Crossover Mode (
612 × 792 pt, Kew × DK × NatGeo × SciAm, WeasyPrint): Demonstrated indemos/botanica-veridica/:- Hybrid Zero-Text Plate + Pure-Vector SVG Anatomy Overlay: Generate clean museum studio/field plates with zero embedded text, then overlay deterministic pure-vector SVG 90° elbow anatomy leader lines, circular anchor dots, circular magnifying-lens zoom medallions (
border-radius: 50%), and metric scale bars. Over dark/textured field photos, place labels inside high-contrast#FBF9F4archival pills (fill-opacity: 0.95) and attach each leader to the nearest pill edge so leaders never cross behind labels. - Specimen-Derived Mineral Palette (WCAG AA Engineered): Use warm eggshell paper (
#FBF9F4), archival stone callout boxes (#F1ECE1), deep charcoal ink (#181A18), and muted mineral spot colors (#005F5Abotanical teal,#8A530Bochre,#964123terracotta,#185D3Bemerald,#9C1F32carmine,#2C4966slate—all engineered>= 5.0:1on#FBF9F4). Always verify with the background-sampled WCAG 2.1 contrast gate (audit_contrast.py). - Interactive PDF/UA-1 + Print Pre-Press Dual Output: Compile digital monographs with
pdf_variant="pdf/ua-1", nested CSSbookmark-level: 1|2PDF outlines, clickable internal TOC/key jump links, and external registry links (GBIF/OpenTree); offer an optional--prepressflag emitting@page { bleed: 3mm; marks: crop cross; }for print houses. - Facing-Spread QA: Always run
render_spreads.pyto visually verify opposing spreads ([2|3],[4|5],[6|7],[8|9]) side by side for headline-baseline symmetry and cross-gutter visual weight. - Dual-Target Living Web Publication (
compile_living_web.py): From the exact same Rule-6-latchedsummary_metrics.json,provenance_ledger.json,background_citations.json, and pure-vectorsvg_exhibits.py, also emit a zero-CDN-dependency interactive HTML/SVG Living Edition where clicking any number pops open its live SHA-256 cryptographic receipt & raw API excerpt ([X-Ray Provenance]mode), botanical pins highlight anatomy interactively, and dichotomous keys run live in the browser. - Deterministic Geometry Gate (
vedit geometry): Always runvedit geometrybefore visual review to catch cross-line/same-line text collisions,flags=0vsTEXT_ACCURATE_BBOXESPDF clip-path character slicing, trim overflow, and wide-headline orphan wraps mechanically.
- Hybrid Zero-Text Plate + Pure-Vector SVG Anatomy Overlay: Generate clean museum studio/field plates with zero embedded text, then overlay deterministic pure-vector SVG 90° elbow anatomy leader lines, circular anchor dots, circular magnifying-lens zoom medallions (
- Rust-Native Typst
0.15.1Academic Monograph Mode (--pdf-standard ua-1,demos/typst-carbon-monograph/):- Native JSON Ingestion (Zero String Templating): Load
summary_metrics.jsonandprovenance_ledger.jsondirectly inside.typvia#let data = json(...)and#let ledger = json(...)(--root "$REPO"), achieving sub-second (~415 ms) incremental compilation with Knuth-Plass optical justification and native IEEE BibTeX (#bibliography("references.bib")). - Cross-Platform Bundled SIL-OFL Typography (
vedit fetch-fonts): Pass--font-path ~/.cache/verifiable-editorial/fontsto pin 8 SHA-256 verified open-source fonts (Cormorant Garamond, Source Serif 4, Inter, IBM Plex Mono) across macOS and Ubuntu Linux CI with0unembedded fonts. Enablenumber-type: "lining"on Cormorant Garamond titles, KPIs, and folios so numerals align crisply. - Certified ISO 14289-1 (
PDF/UA-1) Math & Vector Exhibits: Compile withtypst compile --pdf-standard ua-1, attach descriptive screen-readeralttext to everyimage(...)and every inline/block equation (#math.equation(alt: "...", $ ... $)), embed pure-vector SVG exhibits (∞ DPI), and certify viavedit prepress --min-dpi 300 --require-ua(liveveraPDF106/106passed rules,0failures).
- Native JSON Ingestion (Zero String Templating): Load
- PDF Sample Injection & Design DNA Cloning (Sovereign Zig 0.17.0 Harness):
- To adopt the visual identity of any external reference PDF (consulting report, botanical book, magazine, slide deck), run
vedit-zig inject <sample.pdf> --name <slug>(fromzig/zig-out/bin/vedit). The harness dissects trim dimensions, live margins, 60-30-10 pixel-measured WCAG palette, font hierarchy mapped to bundled SIL-OFL substitutes, and page-by-page column/photo/archetype cadence intoarchetypes/<slug>/{blueprint.json, skeleton.typ, AGENT_CARD.md}. - Scaffold an immediately buildable, SHA-256-sealed,
PDF/UA-1-certified publication cloned from that archetype viavedit-zig init ./target --archetype <slug>(zero Python required).
- To adopt the visual identity of any external reference PDF (consulting report, botanical book, magazine, slide deck), run
6. Supporting References & Runnable Examples
references/design_laws_and_lexicon.md— Extended design grammar, Gestalt spacing, and institutional style lexicon.references/image_generation_recipes.md— Fixed-spec visual continuity prompts for multi-asset cover/architecture illustrations.examples/reportlab_premium_template.py— Clean, runnable dual-mode (--mode dark|light) & dual-format (--format 16x9|letter) starter template with full-bleed background painting, safe Inter registration, hairline KPI strips, and Tufte ledgers.