# HTML → PDF Spec
> The single source of truth for *how* a CREATE / REFORMAT HTML page must be
> authored so it survives Chromium's print snapshot. Every template's
> `skeleton.html` is wired up to follow this spec; if you write a fresh HTML
> from scratch, follow this checklist before invoking
> `bash make.sh render`.
The pipeline is fixed: **HTML (file or URL) → Playwright Chromium →
`page.pdf()`**, driven by [`scripts/render_html.cjs`](../scripts/render_html.cjs).
There is no token pipeline, no ReportLab, no LaTeX. If a primitive cannot be
expressed in HTML+CSS+JS, it does not belong in this skill.
---
## 1. Page geometry
```css
@page { size: A4 portrait; margin: 14mm 12mm; } /* default for reports */
@page { size: A4 landscape; margin: 12mm 14mm; } /* dashboards / wide tables */
@page { size: Letter portrait; margin: 0.75in 0.6in; } /* US-only audience */
```
**A4 is the default — design every HTML against the A4 aspect ratio.**
The renderer (`render_html.cjs`) defaults to `--format A4`, and Chromium's
`page.pdf({ format: 'A4' })` *overrides* any CSS `@page { size: 8.5in 11in }`
you may have inherited from a web template. Mismatches between the CSS you
wrote-for and the format the renderer prints-to are the most common source
of "huge margins / clipped content / 16:9 layout that looks tiny on the
page" complaints.
Concrete numbers to design against (A4 portrait, 14×12 mm margins):
- Page size: **210 × 297 mm** (1 : 1.414 aspect ratio)
- Content area: **186 × 269 mm**
- Aspect ratio for full-bleed sections / hero blocks: **roughly 5 : 7**
(taller than your laptop screen — do not assume 16:9 or 4:3)
Hard rules:
- **Always declare `@page`.** Without it Chromium picks 8.5×11 with 1-inch
margins, and your layout drifts.
- **Don't write `8.5in 11in` or `Letter` unless the user is US-only.** It
will be silently overridden to A4 by the renderer's `--format A4`
default; the visual result is "your CSS thinks Letter, the PDF is A4"
and content overflows or gets cropped. Either author against A4 in CSS,
or pass `--format Letter` to the renderer to make CSS and PDF match.
- **Use `mm` / `in`, not `px`.** Pixels render at 96 DPI in Chromium and
look fine on screen but wrong in print. `vw` / `vh` / `100%` height
are also off-limits at the page level — you will get one "screen" per
page instead of A4 pages.
- The renderer accepts `--margin "14mm 12mm"` and `--format A4|Letter`;
CSS `@page` takes precedence over the CLI flags only when both are set.
- **Cover / full-bleed sections**: explicit `height: 268mm` (A4 portrait
297 − 2×14 mm − 1 mm bleed). For other margin schemes, recompute:
`height = 297 - top_margin - bottom_margin - 1mm`. Don't use `100vh` —
it expands with viewport, not with the printed page.
- **Charts / images** get `max-width: 100%` (relative to content area
186 mm, not viewport). Set explicit `mm` heights on `.chart-wrap`
rather than relying on `aspect-ratio` (Chromium's print pipeline
computes aspect-ratio from screen, then prints; the 1.414 page ratio
isn't applied).
### Screen-emulation block — make `open page.html` look like the PDF
The `@page` rule is **ignored on screen**, so opening the source HTML in
a browser shows one giant horizontal page that looks nothing like the
A4 PDF. **Every skeleton must include this `@media screen` block** so
the browser preview reads as a stack of A4 sheets — the agent (and the
human reviewer) gets the same geometry in both views, no surprise at
PDF time.
```css
@media screen {
html { background: #d0d0d0; }
body { margin: 0; padding: 20px 0; }
/* Each top-level renders as one A4 sheet on screen */
body > section {
width: 210mm;
min-height: 297mm; /* full A4; cover's height: 268mm is overridden up */
margin: 0 auto 20px;
background: #fff;
box-shadow: 0 4px 24px rgba(0,0,0,0.18);
box-sizing: border-box;
overflow: hidden;
}
}
```
Notes:
- The block is **screen-only**; `@page`, page-breaks, and Chromium's PDF
pipeline are unaffected.
- Sections that already have their own background (`.cover` linear-
gradient, dark conclusion blocks) keep their styling because class
selectors out-rank the type selector `body > section`.
- This is *visual* parity, not pixel-perfect — `page-break-inside: avoid`
and Chart.js render timing only run during PDF generation. For
pixel-perfect screen parity, opt in to a paged-media polyfill
([Paged.js](https://pagedjs.org/)); not required by default.
## 2. Universal print color fidelity
```css
* { -webkit-print-color-adjust: exact; print-color-adjust: exact; }
```
- Apply to the **universal selector**, not just `body`. Gradient KPI cards,
cover gradients, and dark conclusion blocks all desaturate without this.
- The renderer defaults to `printBackground: true`. Pass `--no-print-background`
only when you want a transparent body (rare).
## 3. Page-break rules
### 3.1 Protect elements from being split
- Wrap every chart / large table / multi-column card in a container with
`page-break-inside: avoid` (use `.avoid-break { page-break-inside: avoid }`).
- Use `page-break-after: always` on a wrapper element to force a split (e.g.
cover page, end of a chapter). **Use sparingly** — every forced split is a
page that can become half-empty.
- Headings should declare `page-break-after: avoid` (don't strand a title at
the bottom of a page).
- **Never** use absolute positioning to "fix" a layout that overflows. Re-flow
with `flex` / `grid` and adjust the `mm` sizing.
### 3.2 Page balance — every page must be full (≥ 2/3)
A protected element (chart card, table, conclusion block) that doesn't fit
in the remaining space gets pushed to the next page, leaving a fat blank
gap above it. Same for `page-break-before: always` on a section that comes
right after a short subsection. **This is the #1 cause of "amateurish"
PDFs.** Inspect every page and fix any blank gap > 1/3 of the page height.
**Estimate before authoring.** Rough capacity for A4 portrait at 14×12 mm
margins, body 10.5 pt / line-height 1.55:
| Element | Vertical cost (approx.) |
| --- | --- |
| Section header (eyebrow + h2 + rule) | 28 mm |
| Lead paragraph (3 lines) | 18 mm |
| KPI 4-grid (one row) | 28 mm |
| Chart card (default `.chart-wrap`) | 100 mm |
| Chart card (`.tall`) | 130 mm |
| Data table (10 rows) | 70 mm |
| Insight callout (1 paragraph) | 18 mm |
| Recommend triple (3-up cards) | 70 mm |
| Versus pair (2-up cards) | 65 mm |
| Body line | ~5 mm |
A4 content height ≈ **268 mm** (297 − 2×14 mm margin). Add up the elements
on a page, check whether they fit. If a chart card (100 mm) lands on a page
that already has 200 mm filled, **don't let it spill** — either pull
something forward (a small insight / takeaway) to fill the gap on the
current page, or re-order so the chart card starts the next page.
**Three fixes when a page has > 1/3 blank** (from cheapest to most-invasive):
1. **Pull next-section content backward** into the current page. Small
primitives travel well: insight callouts, takeaway rows, a footer-meta
block, even one extra KPI card. Move them across the section boundary
(the visual section break still works because the H2 below is
unmistakable).
2. **Expand current-section content**. Lengthen the lead paragraph,
add a 4-row "key facts" mini-table, or split a single big chart into
two smaller ones (one "overview", one "detail").
3. **Re-order major elements** so a tall element doesn't get orphaned.
Move a long table before a chart card if the table fills the gap better.
**Three things you must NOT do**:
- ❌ Add ` ` / ` ` / `.spacer { height: 50mm }` to fake fullness.
- ❌ Shrink page margins (`@page margin: 8mm`) to force-fit content.
- ❌ Inflate font-size / line-height purely to consume space.
**page-break-before discipline**: only `
` / cover / chapter headers
should carry `page-break-before: always`. H2 and H3 must not — that's
how short subsections create huge gaps. Sections that flow naturally fill
better than sections that hard-split.
**The check is iterative**. After the first render, open the PDF and
look at every page bottom. Fix the worst gap, re-render, repeat. Don't
declare done until the worst-page-gap is ≤ 1/3.
### 3.3 Running headers and footers
Headers/footers are part of the document contract, not decoration. For any formal or multi-page output (contracts, proposals, reports, forms, manuals, translated documents), decide and implement them before the first serious render.
Decision rules:
- If the source document has headers/footers, preserve their text and placement unless the user asks for a redesign.
- If the source has no headers/footers but the output is formal and multi-page, add a conservative running header/footer: document title or section identity in the header, page number or classification/date in the footer.
- Keep cover/title pages clean unless the source explicitly has first-page headers/footers.
- If no header/footer is appropriate (poster, single-page certificate, full-bleed cover), state that decision in the delivery note.
Implementation pattern for hand-authored HTML:
```css
@page { size: A4 portrait; margin: 18mm 20mm; }
.page {
position: relative;
min-height: 261mm; /* 297 - top/bottom @page margins */
padding-top: 10mm; /* reserved header area */
padding-bottom: 12mm; /* reserved footer area */
break-after: page;
}
.cover { padding-top: 0; padding-bottom: 0; }
.running-header {
position: absolute; top: 0; left: 0; right: 0; height: 7mm;
border-bottom: 0.5pt solid #bdbdbd;
font-size: 8.5pt; color: #555; line-height: 7mm;
}
.running-header .left { float: left; }
.running-header .right { float: right; }
.running-footer {
position: absolute; bottom: 0; left: 0; right: 0; height: 8mm;
border-top: 0.5pt solid #bdbdbd;
font-size: 8.5pt; color: #555; line-height: 8mm; text-align: center;
}
```
```html
Document titleSection
```
Verification:
- Rasterize at least one body page and the last/signature/table-heavy page; confirm header/footer alignment and no overlap.
- `pdftotext` should expose running text/page numbers, but visual raster is the real gate.
- If a footer collides with a table/chart, increase `.page` bottom padding or split/reflow the protected element; do not shrink margins below the document standard just to fit it.
### 3.4 Clickable TOC / index links
Every generated multi-page PDF must include a visible table of contents or
index that links to the corresponding section pages. This is part of the PDF
navigation contract, not optional decoration.
Author HTML TOCs with internal anchors and stable target IDs:
```html
Executive summary
...
```
Rules:
- Every major section, appendix, and reference block gets a unique ASCII `id`.
- TOC rows are real `` links, not inert `