SKILL.md
Paged Reports
Markdown in, print-ready document out. The pipeline is: markdown → HTML template with brand tokens → paged.js pagination → PDF (or a browser preview, or a magazine-mode URL).
This skill owns the mechanics only. Which font, which color, which size — that is the project's brand, not this skill's business. Read the tokens first, then render.
Where the tokens come from
Look in this order and stop at the first hit:
- The project's
DESIGN.md— frontmatter tokens are normative. - A brand skill in the project. For Focus.AI work that is
focus-ai-brand, whose
design-system reference carries the paged type scale under "Output-Format Tokens".
- Ask. Do not invent a palette — a report in the wrong colors is worse than one that
waited a minute for an answer.
Process
- Read the source markdown and decide the mode — standard (browser preview),
paged (PDF deliverable), or magazine (shareable scroll URL). The table in references/paged-system.md maps intent to mode.
- Pick a template from
templates/. Focus.AI ships four: client and labs, each in
standard and paged form. A project with its own brand copies one and swaps the token block at the top — the paged.js scaffolding underneath is identical.
- Structure the content to the page-break conventions:
.sectionwrappers,
.no-break-before on the first section after the cover, break-inside: avoid on anything that must stay whole. This is the part that separates a professional PDF from a wall of text — read the "Smart Page Break System" section before writing HTML.
- Render. Write the HTML to a temp path, then either open it for a Cmd+P preview or
drive headless Chrome for a direct PDF.
- Look at the output. Open the PDF, or convert its pages to images and inspect
them. Page breaks fail in ways that are invisible in the HTML — an orphaned heading at a page bottom, a table split across a spread, a blank page after the cover. Shipping an unopened PDF is how those reach the client.
PDF generation
The browser-automation skill (chrome-driver) provides the pdf binary:
PDF_BIN=$(ls -d ~/.claude/plugins/cache/focus-marketplace/chrome-driver/*/bin/pdf | sort -V | tail -1)
$PDF_BIN "file:///tmp/report-$(date +%s).html" ./output.pdfIf chrome-driver is not installed, fall back to the browser print path rather than silently producing HTML and calling it a PDF.
Reference
| Topic | Where |
|---|---|
Modes, /report arguments, template selection |
references/paged-system.md |
Smart page breaks, .section, widows/orphans |
references/paged-system.md |
Running headers, page numbers, @page rules |
references/paged-system.md |
| Cover pages, cards, stats, callouts, pull quotes | references/paged-system.md |
| Magazine mode: spreads, keyboard nav, print fallback | references/paged-system.md |
| paged.js init, print color preservation | references/paged-system.md |
| Focus.AI report templates (client/labs × standard/paged) | templates/ |
Pitfalls
- Fonts must load before pagination. paged.js chunks content on the fonts it has at
init. Initialize with PagedConfig = { auto: false } and call preview() inside document.fonts.ready — otherwise the layout shifts after the page boundaries are set.
print-color-adjust: exactor the background disappears. Browsers strip
backgrounds in print by default. A warm paper ground is a brand decision; losing it in the PDF is a rendering bug, not a preference.
- Never pure white, never pure black — if the brand says paper and ink, that applies
to print output too.
- A blank page after the cover means the first section inherited
break-before: page.
That is what .no-break-before is for.
- Magazine mode is screen-first. It has a print fallback, but if the deliverable is a
PDF, generate paged mode directly rather than printing the magazine.