Determinism over prompting
Free-form generation drifts. A fixed pipeline with a reviewed content file does not.
BrochureConverter.
A production pipeline for bringing legacy brochures into a new house style, with accessibility and content fidelity built into the process. AI interprets the source. People review the decisions. Scripts build and check the output.
01 / The problemA new house style.
A new house style.
The same old bottleneck.
Large organisations sit on hundreds of documents in a house style that has since moved on. Restyling them is manual DTP work: slow, expensive, and no two conversions come out quite the same. Accessibility is usually bolted on afterwards, if at all. And when someone retypes text into a new layout, wording changes without anyone noticing.
Don’t let the model design.
Let it judge, and let scripts build.
The model does the parts that need judgment: reading the structure of a messy source, deciding what is a callout and what is a caption, spotting a wrong cross-reference. Everything else — layout, pagination, tagging and checking — is deterministic code. That gives one rule that holds the whole system together: same input, same output.
Reproducibility starts with the reviewed content file, config, design tokens and a fixed pipeline. Model interpretation is reviewed before that build input is locked.
03 / The flowSix steps.
Six steps.
People at the right gates.
- 01Analyse
Profile
The source PDF is analysed: fonts, sizes and colours become a style map — heading, lead, callout, table, footer. Hidden text and low-resolution images are flagged.
- 02Human gate
Plan, then approval
A human sees the structure, the doubtful cases and the expected deviations before anything is built.
- 03Human review
Draft and review
Content is written to a plain-text content file. A reviewer fixes cross-references, merges split paragraphs, writes alt text, and logs every textual correction.
- 04Deterministic build
Build
One pipeline renders HTML, prints the PDF, and post-processes it to PDF/UA.
- 05Stop on failure
Gates
Automated accessibility and fidelity checks. If a hard gate fails, nothing ships.
- 06Human handover
Handover
Output, edit log and QA report go to a DTP specialist and the content owner. Content issues are reported, never silently corrected.
04 / Under the hoodA pipeline.
A pipeline.
Not a layout prompt.
| Layer | What it does |
|---|---|
| Orchestration | A Claude skill: instructions and scripts. Three workflows: legacy PDF, new Word text with images, and legacy PDF with reviewer comments. |
| Extraction | PyMuPDF reads text spans with font, size and colour. A style profiler maps them to roles and writes a reviewable style file. |
| Content model | A small markup language (content.md) plus a JSON config. Blocks for chapter openers, callouts by function — tip, caution, info, question — quotes with photo, tables, figures with alt text, and columns. |
| Design tokens | Colours, type sizes, leading, tints and radii are generated from the designers’ InDesign (IDML) template into tokens.css. Never edited by hand. A palette report flags off-palette colours and conflicting styles between documents. |
| Rendering | HTML/CSS template, printed to PDF by headless Chromium (Playwright). Custom pagination rules: measured fit for one-page chapters, column balancing, 10 mm print margins, and an approximated 7 pt baseline grid. Figtree and a custom headline face as WOFF2. |
| PDF/UA post-processing | pikepdf: untagged content — backgrounds, decoration, icons, running footers — marked as Artifacts; link annotations get descriptions; XMP metadata with title, language and pdfuaid:part=1; MarkInfo and DisplayDocTitle; bookmarks rebuilt from the headings. |
| Accessibility gates | PDF/UA-1 machine checks on Matterhorn conditions, calibrated against PAC. axe-core (WCAG 2.2 AA) and HTML_CodeSniffer at 1280 px and 320 px. No horizontal scrolling. |
| Fidelity gate | Word-for-word diff between source and output using Python difflib. Every difference has to be explained in the edit log. |
| Regression | Five reference cases, including conversions compared against designer-made PDFs. Thresholds on word identity and baseline deviation. Nothing in the template changes without a green run. |
| Outputs | HTML, PDF/UA, edit log with QA report, plus the reviewed content file and config, so a rerun gives the identical result. |
05 / Decisions that matteredKeep the judgment.
Keep the judgment.
Remove the drift.
Verbatim content
The tool never rewrites. Inconsistencies, broken links and style problems go on a list for the content owner.
Tokens from the source of truth
The design lives in InDesign. The tool reads it instead of copying it, so a house-style update becomes “update tokens, rerun regression” rather than “redo every document”.
Humans at the gates that matter
Plan approval before building, review before output, a DTP specialist at the end.
Fail loudly
A failed hard gate stops the run.
Measured on the reference set.
Reported results from the project’s five reference cases. These describe the tested set, rather than a guarantee for every source document.
- Reference documents of 12 to 20 pages convert with 98 to 99.5% word identity to the source, and every remaining difference is logged and explained.
- The accessibility gates pass with zero errors on the reference set: PDF/UA machine checks and axe-core WCAG 2.2 AA at two widths.
- Output is reproducible: the same input gives the same file.
- Every document comes with its own audit trail: edit log, QA report and reviewed source.
- A house-style change is a token update plus one regression run.
07 / Known limitsA machine pass
A machine pass
is not the last check.
- In text-heavy two-column chapters, Chromium balances columns where InDesign fills them one by one, so a page can differ by a few lines.
- A formal PAC/veraPDF run and a screen reader test are still a manual step before publication.
- Vector illustrations in old PDFs come through as 250 dpi PNG; small source photos stay small.
- IDML export for DTP handover is in development.
- Claude (skills)
- Python
- PyMuPDF
- pikepdf
- Playwright / Chromium
- axe-core
- HTML_CodeSniffer
- InDesign IDML
- HTML/CSS
- PDF/UA (ISO 14289-1)
- WCAG 2.2 AA