# SkillPatch skill: research-poster Build a conference research poster from a paper. Use when a request says "make a poster", "conference poster", "poster from this paper", "academic poster", "research poster", "print-ready poster", "poster PDF", "A0 poster", "A1 poster", "36x48 poster", "poster for KDD/NeurIPS/ICML/ACL/CVPR/CHI", "poster session", "my poster board is NxM", "turn this paper into a poster", or supplies a paper PDF/arXiv link/DOI plus board or print dimensions. Also use for revising an existing poster — "make the poster bigger/smaller", "fit my board", "change the poster colour", "the text is too small", "make the poster match our brand", "validate the poster against the paper". Do NOT use for slide decks or talks (use research-deck), or for writing the paper itself. You (the agent) were given this URL and asked to use this skill. This is a **public** skill — no SkillPatch account, API key, or prior setup is required. Two ways to use it: **1. Use it right now** — the skill's complete file tree (SKILL.md + all reference files) is inlined below; read `SKILL.md` first, then follow it, consulting the other files as it directs. **2. Install the exact package onto disk** (recommended if you can run a shell — this reproduces the skill byte-for-byte, including any binary assets that can't be inlined): ```bash mkdir -p .claude/skills/research-poster curl -sSL https://skillpatch.dev/install_skill/research-poster | tar -xz -C .claude/skills/ ``` (`.claude/skills/` is Claude Code's convention; use whatever directory your agent loads skills from.) --- ## Skill files (7) - `SKILL.md` - `assets/poster-template.html` - `references/content.md` - `references/layout.md` - `scripts/check.py` - `scripts/layout.py` - `scripts/palette.py` ### `SKILL.md` ````markdown --- name: research-poster description: Build a conference research poster from a paper. Use when a request says "make a poster", "conference poster", "poster from this paper", "academic poster", "research poster", "print-ready poster", "poster PDF", "A0 poster", "A1 poster", "36x48 poster", "poster for KDD/NeurIPS/ICML/ACL/CVPR/CHI", "poster session", "my poster board is NxM", "turn this paper into a poster", or supplies a paper PDF/arXiv link/DOI plus board or print dimensions. Also use for revising an existing poster — "make the poster bigger/smaller", "fit my board", "change the poster colour", "the text is too small", "make the poster match our brand", "validate the poster against the paper". Do NOT use for slide decks or talks (use research-deck), or for writing the paper itself. --- # Research poster Turn a paper into a print-ready poster: one HTML file plus a PDF at exact physical dimensions. HTML is the right tool here because poster geometry is arithmetic — millimetre column widths, row heights that must sum to the page — and CSS with `mm` units plus `@page` gives exact control that a slide editor does not. Chrome renders it to a PDF whose page box is the physical sheet. ## The one thing that goes wrong Content is clipped by `overflow:hidden`, so an over-full block does not look broken — it looks slightly empty, and prints that way. Never judge fit by eye; run `scripts/check.py`, which measures every block in a real browser and separates *clipped* (content lost — fix it) from *tight* (padding squeezed, nothing lost — cosmetic). ## Workflow ### 1. Read the paper completely Read every page, including appendices — the best concrete example for the poster is usually in an appendix. If given a URL, fetch it; if a PDF path, read all pages. Then build a **fact sheet** of every quantity with its table/page number, before writing any markup. See `references/content.md` for the format and the two habits that prevent most errors (record every denominator; mark which numbers you derived). ### 2. Ask the user — one round, four questions Ask these together in a single `AskUserQuestion` call, skipping any the user already answered. These four genuinely change the output and cannot be inferred: 1. **Print size.** Offer: the paper's venue norm (A0 portrait) · a stated board slot ("I'll give dimensions") · a standard alternative (A1, 36×48 in). If they give a board slot, run `scripts/layout.py --slot WxH` and use its suggestion. 2. **Colour theme.** Offer: derive from a logo file they have · a specific brand hex · a named preset (deep rose, indigo, teal, forest, slate). Mention that a logo yields the most on-brand result. 3. **Logos and assets.** Which of these exist: author/institution logo, venue logo, a QR code image (or should one be generated for the repo/DOI). 4. **Venue details.** Full conference name, dates, city, poster/session number, DOI, repo URL, licence — whatever they have. Note anything missing will be left as a visible placeholder. If the user has already supplied something (a logo in the folder, a stated size), use it and do not ask again. Prefer acting on what is present over interrogating. ### 3. Derive the palette ```bash python scripts/palette.py --from-image logo.png # or --brand "#RRGGBB" ``` Emits a `:root` block and audits every text-on-background pair. Two things it enforces that are easy to get wrong: brand colours chosen for logos are usually too light for text (so `deep` and `mid` are darkened along the hue), and contrast must be computed rather than judged — a mid-tone on a pale tint can look fine at 4.4:1 and fail. **Use `brand` for fills, bars and dots only, never for body text.** To check any pair later: `python scripts/palette.py --check "#FG" "#BG"`. ### 4. Solve the geometry ```bash python scripts/layout.py --page 1000x850 --margin 22 --gutter 10 --cols 12 \ --header 126 --footer 30 --rows 170,108,136,186 ``` Prints the column width, every span width to use verbatim in CSS, the reading measure per span (which spans take prose vs tables only), and whether the vertical schedule sums exactly to the page. Use `--rows auto:N` to have it distribute the remaining height. Do not skip this and estimate. A schedule that overshoots by a few millimetres clips the last row silently. ### 5. Plan the blocks, then write the HTML Nine numbered blocks is the default. `references/content.md` gives what belongs in each, the word budget per block, and what to cut; `references/layout.md` gives block plans per aspect ratio, the type scale with its floors, and how to rebuild paper figures that will not survive enlargement. Copy `assets/poster-template.html` and replace the `{{PLACEHOLDERS}}`. It renders as-is, so it can be checked before content exists. Three structural points carried in the template: - **Numbered badges carry the reading order.** A grid without them has no obvious path. - **The core contribution belongs in a full-width band at the optical middle** — the most-looked-at region, with room to render a taxonomy as cards or a wide diagram rather than a cramped column. - **Put a visible border around the whole poster.** Boards are often shared; without it the poster blends into a neighbour's. ### 6. Render and check — iterate until clean ```bash python scripts/check.py poster.html --expect 1000x850 --pages 1 --selector ".blk" \ --raster /tmp/pv --contact-sheet /tmp/sheet.png ``` Verifies page size and count, reports clipping per block, and can rasterise for a look. Exit code is non-zero while anything is clipped, so it gates the loop. When a block is clipped, prefer **cutting words** over shrinking type — the type floors in `references/layout.md` exist because body text below 17 pt is not read at poster distance. Then view the contact sheet to check the composition reads, not just that it fits. ### 7. Validate every claim against the paper Walk each block and check each number against the fact sheet. `references/content.md` lists the specific failure modes to look for — overstated qualifiers, editorialised conclusions, mixed denominators, and paper prose that contradicts its own tables. Where they disagree, follow the table and tell the user which prose conflicts, so they are not ambushed at the board. Report plainly: what was verified, what was corrected, what remains uncertain. ### 8. Hand over State the export recipe (Print → Save as PDF, **Margins: None**, **Background graphics ON** — without it every fill disappears), confirm the verified page geometry, and flag any asset below 150 dpi at final size (`pdfimages -list poster.pdf`). Then offer the booth material in `references/content.md`: a 20-second hook, a badge-by-badge walkthrough, and likely hard questions with answers. ## Files - `scripts/layout.py` — grid solver: sheet size from a board slot, span widths, reading measure, vertical schedule - `scripts/palette.py` — palette from a brand colour or logo, plus WCAG contrast audit - `scripts/check.py` — render, assert page geometry, detect clipping, rasterise - `assets/poster-template.html` — working skeleton with the component set - `references/layout.md` — sizes, type scale, block plans, figure rebuilds, print and travel - `references/content.md` — fact sheet, per-block content and word budget, cuts, validation, booth prep ```` ### `assets/poster-template.html` ``` {{SHORT TITLE}}

{{PAPER TITLE}}

{{Author One · Author Two · Author Three}}
{{VENUE}}  ·  {{CITY}}  ·  {{DATES}}  ·  Poster #{{NUM}}
{{Code + data}}
{{N1}}{{label}}
{{N2}}{{label}}
{{N3}}{{label}}
{{N4}}{{label}}
{{N5}}{{label}}
{{N6}}{{label}}
1

Takeaways

  • {{Every bullet carries a number: NN% …}}
  • {{…}}
2

The problem{{one-line subtitle}}

{{…}}

{{a concrete example query or case}}
3

Method / data

{{raw}}{{stage}}
{{N}}{{final stage}} ★
4

What we measure

{{metric family}}

{{…}}

5

{{Pipeline / architecture}}

6

{{Core contribution}}

1
{{Name}}
{{one-sentence description}}
“{{the real query}}”
Observed failure — {{what actually went wrong}}
{{lo–hi%}}{{of what}}
2
{{Name}}
{{…}}
“{{…}}”
Observed failure — {{…}}
{{lo–hi%}}{{of what}}
7

{{Headline result}}

{{Model}}{{Metric}}{{Key metric}}
{{…}}{{…}}{{…}}
{{the sentence you want repeated back to you}}
8

{{Comparison}}{{units, n}}

{{…}}{{…}}
{{…}}{{…}}
9

{{Limits & future work}}

  • {{…}}
``` ### `references/content.md` ````markdown # Turning a paper into nine blocks 1. [The fact sheet](#the-fact-sheet-do-this-first) 2. [What goes in each block](#what-goes-in-each-block) 3. [What to cut](#what-to-cut) 4. [Claim validation](#claim-validation) 5. [Booth preparation](#booth-preparation) ## The fact sheet (do this first) Before writing any HTML, extract every quantity from the paper into a scratch file with its table or page number. The poster's credibility rests entirely on these, and a number transcribed from memory halfway through drafting is how errors get in. ``` FACT SHEET headline quantities : 198 queries · 11 categories · 5 models · 4 metrics · 7 failure types Table 3 (p.8817) : metric definitions, verbatim Table 4 (p.8817) : 5 models × 4 metrics — full grid Table 7 (p.8819) : exact/derived/fabricated %, sums to ~100 per row Table 9 (p.8820) : proportion of RESPONSES per failure category <- note the denominator derived by me : depth spread 8.35-7.25 = 1.10 ; relevance 9.58-9.17 = 0.41 ``` Two habits that prevent the most common errors: - **Record the denominator with every percentage.** "% of claims" and "% of responses" look identical on a poster and cannot share an axis. Label the group when both appear. - **Mark which numbers you computed** (ranges, spreads, min/max across models) versus which are printed in the paper. Derived numbers are fine and often the most interesting thing on the poster — they just need to be right, and you need to know which is which when questioned. ## What goes in each block Total body text across all nine blocks: **≈ 850 words at A0, ≈ 650 for a smaller sheet.** This is far less than feels natural. Enforce it by cutting, not by shrinking type. | # | Block | Content | Words | |---|---|---|---| | ① | **Takeaways** | 4–5 bullets, **every one containing a number**. The only block most visitors read. | ~90 | | ② | **The problem** | Why the setting is hard — 2–4 named challenges, plus one concrete example, plus a one-line statement of the gap. | ~85 | | ③ | **Method / data** | Construction or setup. A funnel if there are stage counts; a category chart if there is a distribution. | ~75 | | ④ | **What we measure** | Metric definitions verbatim from the paper, and how they are computed. Readers need this *before* the results. | ~70 | | ⑤ | **System / pipeline** | One left-to-right figure. Almost pure diagram. | ~40 | | ⑥ | **Core contribution** ★ | The paper's actual novelty, full-width, given the most room. Plus one worked example and one validation number. | ~130 | | ⑦ | **Headline result** | The single most important comparison, with the sentence you want repeated back. | ~60 | | ⑧ | **Detail / per-condition** | Secondary results table plus one-line verdicts per row. | ~70 | | ⑨ | **Limits & future work** | Interventions or extensions, honest limitations. | ~60 | Plus an unnumbered **at-a-glance strip** of 5–6 large numerals in the header — the quantities that define the work, readable from 3 m. **Write block titles as claims, not labels.** "Facts are fine. Framing isn't." stops people; "Results" does not. The exception is method blocks, where a plain label aids scanning. ## What to cut | Cut | Why | |---|---| | Related work | Compress the entire section to one bold sentence naming the gap, in ② | | The bibliography | A poster carries zero citations; the QR carries all of them | | Most appendix examples | Keep **one**, at full strength. It becomes what people repeat | | Full metric-definition tables | Fold into ④ as inline definitions | | Any figure that needs a caption to be understood | Redraw it or drop it | | Hedging and repetition | Say each thing once | Expect the first draft to run 2–3× the word budget. Cut to fit rather than reducing type size — below the type floors the poster stops working at distance. ## Claim validation After the poster renders, verify every claim against the paper before declaring it done. Walk each block and check each number against the fact sheet, then look specifically for these, which are the failure modes that actually occur: - **Overstated qualifiers.** Writing "fully-cited table" where the paper says "a table sourced from multiple tools" invents a property. Match the paper's hedging. - **Editorialised conclusions.** "X is solved" when the paper says "X stays below 6%". Prefer the paper's own summary sentence — it is usually both safer and sharper. - **Denominator mixing.** Two rates on one axis with different bases. - **Arithmetic you performed.** Recompute spreads, ranges, min/max. - **Prose that contradicts a table.** Papers do contain these. Follow the **table**, and tell the author which prose disagrees so they are not ambushed at the board. Report the result plainly: what was verified, what was corrected, and anything in the paper itself that looks inconsistent. ## Booth preparation Offer these once the poster is built — they cost little and are what the presenter actually needs on the day: - **A 20-second hook.** One spoken paragraph: setting, the surprising finding, the number. - **A badge-by-badge 3-minute walk**, naming which blocks to skip. - **Five likely hard questions with answers**, drawn from the paper's real limitations — sample size, single-run results, judge reliability, generalisation beyond the domain, anything the paper itself flags as future work. Presenters are rarely ambushed by the poster; they are ambushed by the limitations. ```` ### `references/layout.md` ````markdown # Poster layout reference 1. [Choosing the sheet size](#choosing-the-sheet-size) 2. [Type scale](#type-scale) 3. [Block plans by aspect ratio](#block-plans-by-aspect-ratio) 4. [Figure rules](#figure-rules) 5. [Print and travel](#print-and-travel) ## Choosing the sheet size Run `scripts/layout.py --slot WxH --inset 33` and use what it suggests. Two rules behind it: - **Print a little smaller than the allotted space.** Visible clearance on each side reads as deliberate; a poster butted to the edges reads as a mistake, and boards are rarely square to the millimetre. - **Mount flush to the top of the slot, not centred.** Poster boards sit on stands, so the bottom band ends up below comfortable reading height. Give away the dead space at the bottom. Common cases: | Situation | Sheet | |---|---| | No constraint given | A0 portrait, 841 × 1189 mm — fits nearly every board | | A stated board slot | `layout.py --slot` output | | Shop wants a standard size | A0 841 × 1189, A1 594 × 841, B1 707 × 1000 | | Slot is near-square | Landscape at ~1.15–1.2:1 — see the four-column plan below | **1000 mm is a standard roll width**, so a custom height on a 1000 mm roll usually costs the same as a standard size. Ask. ## Type scale Anchored to A0 viewed at 1–2 m. For a smaller sheet, scale by the ratio of the sheet's long edge to 1189 mm, then round — but never below the floors. | Element | A0 | Floor | |---|---|---| | Title | 76 pt bold | 56 pt | | Authors | 30 pt · affiliations 22 pt | 20 pt | | Section title | 46 pt bold | 28 pt | | Badge numeral | 42 pt in a 52 mm circle | 22 pt / 19 mm | | Body | 22 pt | **17 pt — hard floor** | | Table body | 20 pt | 14 pt | | Caption / footer | 18 pt | 11 pt | Two things matter more than the exact numbers: - **Body text below 17 pt stops being read at poster distance.** If it doesn't fit, cut words. - **Line length beats font size.** `layout.py` prints the character count per span. Prose belongs in spans measuring 45–75 characters; past ~95 characters use tables, charts, or one-line bullets only. A 4-column block at A0 measures ~93 characters — too long for paragraphs, fine for a results table. ## Block plans by aspect ratio Nine numbered blocks is a good default: enough to cover a paper, few enough to stay scannable. Badges carry the reading order, so the grid does not have to be strictly linear. **Portrait (0.71:1, e.g. A0).** Four columns for prose rows, two full-width bands: ``` HEADER (logos · title · authors · QR) + number strip ① takeaways | ② problem | ③ method | ④ metrics (4 × 3 cols = 190mm each) ⑤ PIPELINE — full-width band, drawn left-to-right ⑥ CORE CONTRIBUTION — full-width band ★ ⑦ result (4 cols) | ⑧ comparison (4) | ⑨ future (4) FOOTER ``` At A0 a 3-col span (190 mm) measures ~49 characters at 22 pt and a 4-col span (257 mm) ~66 — both ideal for prose. **Avoid putting prose in a span wider than 4 columns**: an 8-col block at A0 is 524 mm ≈ 135 characters, which the eye cannot track back. If a wide block must carry prose, split it into internal sub-columns. **Landscape / near-square (1.15–1.25:1).** Four equal columns with two full-width bands as a horizontal spine — this is what makes landscape pay off: ``` HEADER + number strip ① takeaways | ② problem | ③ method | ④ metrics (4 × 3 cols) ⑤ PIPELINE — full-width band, drawn left-to-right ⑥ CORE CONTRIBUTION — full-width band ★ ⑦ result (4) | ⑧ comparison (4) | ⑨ future (4) FOOTER ``` **Where the core contribution goes.** Whatever the paper's headline contribution is — a taxonomy, an architecture, a theorem, a dataset — put it in a **full-width band at the optical middle**. That is the most-looked-at region, and a band gives room to render it as 7-ish cards or a wide diagram rather than a cramped column. ## Figure rules Paper figures are drawn for a single column at 300 dpi and almost never survive enlargement. Assume each needs rebuilding: | Paper figure | Poster treatment | |---|---| | Bar chart with rotated tick labels | Rebuild as **horizontal** bars, values labelled at the ends, no axis | | Heatmap in viridis/jet | Recolour to a single-hue ramp monotonic in lightness, **print every cell value** | | Vertical flow diagram | Redraw **horizontally** for a landscape band; inline SVG with `viewBox` units = mm | | Multi-stage table (pipeline counts) | Convert to a tapering funnel — the numbers become the graphic | | Grouped bars of signed deltas | Emphasise the zero line, direct-label values, add `+`/`−` glyphs so it does not rely on hue | | Dense table (5 × 7 or larger) | Keep as a table, or small-multiple bars; highlight the column carrying the argument | **Inline SVG beats a raster.** Set `viewBox="0 0 W H"` with W/H in mm and give the element `width:Wmm`, so coordinates read as physical millimetres and font sizes are `mm × 2.835 = pt`. Two SVG traps that cost real debugging time: - **Paint order is document order.** A `` written before a `` that overlaps it is hidden by the rect's fill. Draw containers first, labels after. - **A reused paper PNG is usually too coarse.** Check with `pdfimages -list out.pdf` — anything under 150 dpi at final size will print soft. Re-export as vector, or regenerate at ≥ 300 dpi. ## Two flexbox traps that erase content without clipping `check.py` catches a block whose content exceeds the block. It cannot catch either of these, because in both cases the content still *fits* — it has just been silently destroyed or displaced inside a fixed-height child. Both are worth knowing by shape: - **A fixed-height item in an over-full column flexbox shrinks to nothing.** `height:3.6mm` on a bar or rule is only a *flex basis*; the default `flex-shrink:1` compresses it, while a sibling with `flex:1` and `min-height:auto` refuses to shrink below its text. The bar collapses to zero height and disappears while the card looks perfectly normal. Put `flex:none` on every fixed-size item in a column flexbox — bars, tracks, rules, badges, footers. - **`overflow` is visible on a fixed-height child, so its overrun paints over the next element.** A card sized `height:100%` inside a fixed-height `.cards` row does not clip; it bleeds into whatever follows, and the parent block reports no overflow. Measure each child directly (compare its `scrollHeight` to its box) rather than trusting the block-level pass. Symptom worth recognising: if one item in a row sits a millimetre or two lower than its neighbours, that item is over-full and pushing past its padding box — not misaligned. ## Print and travel - Export **PDF/X-1a** if the shop asks; otherwise plain PDF with fonts embedded is fine. Verify with `pdffonts out.pdf` — every face should say `yes` under `emb`. - Keep content ≥ 25 mm from the trim edge; add 3 mm bleed only if the shop trims. - **Matte fabric over paper** for air travel: it folds into a carry-on, where a tube gets gate-checked. Paper needs the tube. - **Proof at 30–35 % on A3** and read it from 1 m. Anything you squint at is too small. Do this at least five days out. - Bring pins **and** velcro **and** binder clips; supplied hardware runs out. - RGB is normally fine — most shops convert. Ask whether they want CMYK. ```` ### `scripts/check.py` ``` #!/usr/bin/env python3 """Render an HTML poster/deck to PDF and report the three failures that actually bite. Visual inspection misses content that is clipped by `overflow:hidden` -- the block simply looks a bit empty. This finds it by running the page in a real browser and comparing each container's scrollHeight to its clientHeight, so overflow is reported as a number instead of being spotted (or not) by eye. Usage python check.py page.html # render + audit python check.py page.html --expect 1000x850 --pages 1 # assert geometry python check.py page.html --selector ".slide" --pages 23 python check.py page.html --raster out/ --dpi 60 # also write PNGs python check.py page.html --contact-sheet sheet.png # grid of all pages Exit code is 1 if any assertion fails or any container overflows, so it can gate a loop. """ import argparse import json import os import re import shutil import subprocess import sys import tempfile CHROME_CANDIDATES = [ "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "/Applications/Chromium.app/Contents/MacOS/Chromium", "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", "google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "microsoft-edge", ] # Two different conditions look identical to a naive scrollHeight check, so the audit # separates them by comparing the overflow against the container's own bottom padding: # # overflow <= padding-bottom -> TIGHT. The designed breathing room is being eaten, # but no glyph is lost. Cosmetic; often fine. # overflow > padding-bottom -> CLIPPED. Real content is cut off by overflow:hidden, # and because it is clipped rather than reflowed, the # block just looks slightly empty. This is the one that # silently ships broken posters and decks. AUDIT_JS = """ """ def find_chrome(): for c in CHROME_CANDIDATES: if os.path.sep in c: if os.path.exists(c): return c elif shutil.which(c): return shutil.which(c) sys.exit("No Chrome/Chromium/Edge found. Install one, or pass --chrome .") def run(cmd, **kw): return subprocess.run(cmd, capture_output=True, text=True, **kw) def audit_overflow(chrome, html_path, selector): """Copy the HTML with an audit script appended, load it, read results from . Works on any HTML without the file needing to cooperate: --dump-dom executes scripts and prints the resulting DOM, so a title we set from JS comes back to us. """ src = open(html_path, encoding="utf-8").read() js = AUDIT_JS % json.dumps(selector) # Splice by index rather than re.sub: the JS contains regex escapes like \s+, which # Python would try to interpret as escapes in a replacement template. m = re.search(r"</body\s*>", src, re.I) patched = (src[:m.start()] + js + src[m.start():]) if m else (src + js) d = tempfile.mkdtemp() # Keep the copy beside the original so relative asset paths (logos, QR codes) resolve. tmp = os.path.join(os.path.dirname(os.path.abspath(html_path)), ".__check_tmp__.html") open(tmp, "w", encoding="utf-8").write(patched) try: r = run([chrome, "--headless", "--disable-gpu", "--no-sandbox", "--virtual-time-budget=8000", "--dump-dom", "file://" + os.path.abspath(tmp)]) m = re.search(r"__AUDIT__(\{.*?\})", r.stdout, re.S) if not m: return None return json.loads(m.group(1)) finally: for p in (tmp,): if os.path.exists(p): os.remove(p) shutil.rmtree(d, ignore_errors=True) def pdf_geometry(pdf): r = run(["pdfinfo", pdf]) if r.returncode != 0: return None, None pages = size = None for line in r.stdout.splitlines(): if line.startswith("Pages:"): pages = int(line.split()[1]) elif line.startswith("Page size:"): nums = re.findall(r"[\d.]+", line) if len(nums) >= 2: size = (float(nums[0]) / 72 * 25.4, float(nums[1]) / 72 * 25.4) # pt -> mm return pages, size def main(): ap = argparse.ArgumentParser() ap.add_argument("html") ap.add_argument("--pdf", help="output PDF path (default: alongside the HTML)") ap.add_argument("--selector", default=".slide, .blk, .page", help="containers to audit for overflow") ap.add_argument("--expect", help="expected page size WxH in mm, e.g. 1000x850") ap.add_argument("--pages", type=int, help="expected page count") ap.add_argument("--tol", type=float, default=1.0, help="page-size tolerance in mm") ap.add_argument("--raster", help="directory to write page PNGs into") ap.add_argument("--dpi", type=int, default=60) ap.add_argument("--contact-sheet", help="write a grid image of all pages here") ap.add_argument("--cols", type=int, default=4, help="columns in the contact sheet") ap.add_argument("--chrome", help="explicit browser binary") a = ap.parse_args() chrome = a.chrome or find_chrome() html = os.path.abspath(a.html) pdf = os.path.abspath(a.pdf) if a.pdf else os.path.splitext(html)[0] + ".pdf" fails = [] r = run([chrome, "--headless", "--disable-gpu", "--no-sandbox", "--no-pdf-header-footer", "--virtual-time-budget=8000", "--print-to-pdf=" + pdf, "file://" + html]) if not os.path.exists(pdf): sys.exit("Render failed.\n" + r.stderr[-2000:]) print("rendered %s (%.0f KB)" % (os.path.basename(pdf), os.path.getsize(pdf) / 1024)) pages, size = pdf_geometry(pdf) if pages is not None: print("pages %d" % pages) if a.pages and pages != a.pages: fails.append("expected %d pages, got %d" % (a.pages, pages)) if size: print("page size %.1f x %.1f mm" % size) if a.expect: try: ew, eh = (float(v) for v in a.expect.lower().split("x")) if abs(size[0] - ew) > a.tol or abs(size[1] - eh) > a.tol: fails.append("expected %gx%g mm, got %.1fx%.1f mm" % (ew, eh, size[0], size[1])) except ValueError: fails.append("could not parse --expect %r (use WxH, e.g. 1000x850)" % a.expect) audit = audit_overflow(chrome, html, a.selector) if audit is None: print("overflow (audit did not report -- check the --selector matches something)") else: print("audited %d container(s) matching %r" % (audit["count"], a.selector)) if audit["count"] == 0: fails.append("selector %r matched nothing -- pass the right --selector" % a.selector) clipped = [o for o in audit["over"] if o["clipped"]] tight = [o for o in audit["over"] if not o["clipped"]] if clipped: print("\nCLIPPED -- real content is cut off (fix these):") for o in clipped: print(" #%-3d %-38s %.1fmm past a %.1fmm bottom pad%s" % (o["n"], o["label"][:38], o["v"], o["pad"], (" +%.1fmm too wide" % o["h"]) if o["h"] > 0 else "")) fails.append("%d container(s) clipped" % len(clipped)) if tight: print("\nTIGHT -- bottom padding squeezed, no content lost (cosmetic):") for o in tight: print(" #%-3d %-38s %.1fmm into a %.1fmm bottom pad%s" % (o["n"], o["label"][:38], o["v"], o["pad"], (" +%.1fmm too wide" % o["h"]) if o["h"] > 0 else "")) if not audit["over"]: print("overflow none") if a.raster or a.contact_sheet: outdir = a.raster or tempfile.mkdtemp() os.makedirs(outdir, exist_ok=True) if shutil.which("pdftoppm"): run(["pdftoppm", "-png", "-r", str(a.dpi), pdf, os.path.join(outdir, "p")]) pngs = sorted(f for f in os.listdir(outdir) if f.endswith(".png")) print("raster %d PNG(s) in %s" % (len(pngs), outdir)) if a.contact_sheet and pngs: try: from PIL import Image ims = [Image.open(os.path.join(outdir, f)) for f in pngs] w, h = ims[0].size cols = min(a.cols, len(ims)) rows = (len(ims) + cols - 1) // cols g = 14 sheet = Image.new("RGB", (w * cols + g * (cols + 1), h * rows + g * (rows + 1)), (60, 50, 58)) for k, im in enumerate(ims): rr, cc = divmod(k, cols) sheet.paste(im, (g + cc * (w + g), g + rr * (h + g))) sheet.thumbnail((1800, 1800)) sheet.save(a.contact_sheet) print("sheet %s" % a.contact_sheet) except ImportError: print("sheet skipped (pip install pillow)") else: print("raster skipped (no pdftoppm; install poppler)") print() if fails: for f in fails: print("FAIL: " + f) sys.exit(1) print("OK") if __name__ == "__main__": main() ``` ### `scripts/layout.py` ``` #!/usr/bin/env python3 """Solve poster grid geometry so the numbers in the CSS are exact. Poster layouts fail in a specific, boring way: the row heights are eyeballed, they sum to more than the available height, and the last row is quietly clipped by `overflow:hidden`. This computes the arithmetic once so the CSS can be written with confidence, and reports the residual so a mismatch is visible before anything is rendered. Usage # size the sheet for a board slot, then solve the grid python layout.py --slot 1067x914 --inset 33 # full solve: 12 columns, header/footer, four content rows python layout.py --page 1000x850 --margin 22 --gutter 10 --cols 12 \ --header 126 --footer 30 --rows 170,108,136,186 # let it distribute the remaining height across 4 rows python layout.py --page 1000x850 --margin 22 --gutter 10 --cols 12 \ --header 126 --footer 30 --rows auto:4 """ import argparse import sys def wh(s, what): try: w, h = (float(v) for v in s.lower().replace("mm", "").split("x")) return w, h except ValueError: sys.exit("Could not parse %s %r -- use WxH in mm, e.g. 1000x850" % (what, s)) def main(): ap = argparse.ArgumentParser() ap.add_argument("--slot", help="board space available, WxH mm -- suggests a sheet size") ap.add_argument("--inset", type=float, default=33, help="clearance to leave on each side inside --slot (mm)") ap.add_argument("--page", help="sheet size WxH mm") ap.add_argument("--margin", type=float, default=22) ap.add_argument("--gutter", type=float, default=10) ap.add_argument("--cols", type=int, default=12) ap.add_argument("--header", type=float, default=0) ap.add_argument("--footer", type=float, default=0) ap.add_argument("--rows", help="comma-separated row heights in mm, or auto:N") ap.add_argument("--body-pt", type=float, default=19, help="body text size, for the measure table") a = ap.parse_args() if a.slot: sw, sh = wh(a.slot, "--slot") pw, ph = sw - 2 * a.inset, sh - 2 * a.inset # Round down to a tidy 10mm multiple: print shops quote round sizes, and it keeps # the grid arithmetic clean. rw, rh = int(pw // 10) * 10, int(ph // 10) * 10 print("slot %g x %g mm (%.2f x %.2f in)" % (sw, sh, sw / 25.4, sh / 25.4)) print("suggested sheet %g x %g mm (%.2f x %.2f in)" % (rw, rh, rw / 25.4, rh / 25.4)) print("clearance %.1f mm each side, %.1f mm top and bottom" % ((sw - rw) / 2, (sh - rh) / 2)) print("aspect %.3f:1 (%s)" % (rw / rh, "landscape" if rw > rh else "portrait" if rh > rw else "square")) print("\nMount flush to the TOP of the slot, not centred: on a short stand-mounted") print("board the bottom edge sits below comfortable reading height.") if not a.page: print("\nRe-run with --page %gx%g to solve the grid." % (rw, rh)) return if not a.page: sys.exit("Pass --page WxH (and optionally --slot to size it first).") pw, ph = wh(a.page, "--page") live_w = pw - 2 * a.margin live_h = ph - 2 * a.margin col = (live_w - (a.cols - 1) * a.gutter) / a.cols print("\npage %g x %g mm" % (pw, ph)) print("live area %.1f x %.1f mm (margin %g)" % (live_w, live_h, a.margin)) print("column %.2f mm (%d cols, %g gutter)" % (col, a.cols, a.gutter)) print("\nspan widths -- use these verbatim in the CSS") for n in range(1, a.cols + 1): w = n * col + (n - 1) * a.gutter note = "" if n == a.cols: note = " full width" elif abs(w - live_w / 2) < 0.6: note = " half" elif abs(w - live_w / 3) < 0.6: note = " third" elif abs(w - live_w / 4) < 0.6: note = " quarter" print(" %2d cols %8.2f mm%s" % (n, w, note)) # Average character advance for a humanist sans is ~0.5em, so mm/char = pt * 0.5 / 2.835. # 45-75 characters is the comfortable measure; past ~90 the eye loses the line return. adv = a.body_pt * 0.5 / 2.835 print("\nreading measure at %gpt body (~%.2f mm/char, aim 45-75 chars)" % (a.body_pt, adv)) for n in range(1, a.cols + 1): w = n * col + (n - 1) * a.gutter chars = w / adv if chars < 28: continue if chars < 45: verdict = "tight but readable" elif chars <= 75: verdict = "ideal -- prose belongs here" elif chars <= 95: verdict = "long -- keep to bullets" else: verdict = "too long -- tables/figures only, no running prose" print(" %2d cols %8.2f mm ~%3.0f chars %s" % (n, w, chars, verdict)) if not a.rows: print("\nAdd --rows to solve the vertical schedule.") return n_rows = None if a.rows.startswith("auto:"): n_rows = int(a.rows.split(":")[1]) rows = None else: rows = [float(v) for v in a.rows.split(",")] n_rows = len(rows) blocks = [("header", a.header)] if a.header else [] blocks += [("row %d" % (i + 1), None) for i in range(n_rows)] if a.footer: blocks += [("footer", a.footer)] n_gaps = len(blocks) - 1 fixed = a.header + a.footer avail = live_h - fixed - n_gaps * a.gutter if rows is None: each = avail / n_rows rows = [round(each, 1)] * n_rows rows[-1] = round(avail - sum(rows[:-1]), 1) # absorb rounding in the last row print("\ndistributing %.1f mm across %d rows" % (avail, n_rows)) print("\nvertical schedule") total = a.margin print(" %-10s %7.1f mm" % ("top margin", a.margin)) if a.header: print(" %-10s %7.1f mm" % ("header", a.header)) total += a.header for i, r in enumerate(rows): total += a.gutter print(" %-10s %7.1f mm" % ("gap", a.gutter)) print(" %-10s %7.1f mm" % ("row %d" % (i + 1), r)) total += r if a.footer: total += a.gutter print(" %-10s %7.1f mm" % ("gap", a.gutter)) print(" %-10s %7.1f mm" % ("footer", a.footer)) total += a.footer total += a.margin print(" %-10s %7.1f mm" % ("bottom mgn", a.margin)) print(" %s" % ("-" * 20)) print(" %-10s %7.1f mm (page is %g)" % ("TOTAL", total, ph)) resid = ph - total print() if abs(resid) < 0.15: print("EXACT -- the schedule fills the page.") elif resid > 0: print("%.1f mm SLACK -- add it to the row carrying the most content." % resid) else: print("%.1f mm OVER -- the last row will be clipped. Reduce a row by this much." % -resid) sys.exit(1) if __name__ == "__main__": main() ``` ### `scripts/palette.py` ``` #!/usr/bin/env python3 """Derive a poster/deck palette from one brand colour, and check WCAG contrast. Two jobs that are easy to get wrong by eye: 1. Brand colours are usually chosen for logos on white, so they are often too light to carry heading or body text. Deriving a darkened "deep" and "mid" from the brand hue gives text-safe anchors while keeping the identity. 2. Contrast has to be computed, not judged. A mid-tone rose on a pale tint can look perfectly readable and still sit at 4.4:1 -- under the 4.5:1 threshold for body text. Usage python palette.py --brand "#FD698D" # derive a full palette + audit it python palette.py --from-image logo.png # sample the brand colour first python palette.py --check "#1E7A5A" "#DCEFE7" # one pair, contrast + verdict """ import argparse import colorsys import sys def hex2rgb(h): h = h.strip().lstrip("#") if len(h) == 3: h = "".join(c * 2 for c in h) if len(h) != 6: sys.exit("Bad hex colour: %r (expected #RRGGBB)" % h) return tuple(int(h[i:i + 2], 16) for i in (0, 2, 4)) def rgb2hex(rgb): return "#%02X%02X%02X" % tuple(max(0, min(255, int(round(c)))) for c in rgb) def _lin(c): c /= 255.0 return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4 def luminance(rgb): r, g, b = (_lin(c) for c in rgb) return 0.2126 * r + 0.7152 * g + 0.0722 * b def contrast(fg, bg): """WCAG 2.x contrast ratio between two hex colours.""" a, b = luminance(hex2rgb(fg)), luminance(hex2rgb(bg)) hi, lo = max(a, b), min(a, b) return (hi + 0.05) / (lo + 0.05) def adjust(hex_colour, dl=0.0, ds=0.0): """Shift lightness / saturation in HLS, keeping hue -- stays on-brand.""" r, g, b = (c / 255.0 for c in hex2rgb(hex_colour)) h, l, s = colorsys.rgb_to_hls(r, g, b) l = max(0.0, min(1.0, l + dl)) s = max(0.0, min(1.0, s + ds)) return rgb2hex([c * 255 for c in colorsys.hls_to_rgb(h, l, s)]) def mix(hex_a, hex_b, t): """Blend toward hex_b by fraction t. Used for tints, because additive lightness clamps to pure white when the brand colour is already light.""" a, b = hex2rgb(hex_a), hex2rgb(hex_b) return rgb2hex([a[i] + (b[i] - a[i]) * t for i in range(3)]) def darken_to_contrast(hex_colour, bg="#FFFFFF", target=7.0): """Darken along the brand hue until it reaches `target` contrast on `bg`. Saturation is eased down slightly as lightness drops: holding full saturation while darkening a vivid brand hue produces a harsh, neon result that reads as a different brand. Bleeding a little saturation keeps the darkened anchor recognisable. """ out = hex_colour for _ in range(120): if contrast(out, bg) >= target: return out nxt = adjust(out, dl=-0.01, ds=-0.006) if nxt == out: break out = nxt return out def derive(brand): """Full palette. `deep` carries headings, `mid` sub-heads, brand is fills only.""" return { "deep": darken_to_contrast(brand, "#FFFFFF", 7.0), # headings, bands, badges "mid": darken_to_contrast(brand, "#FFFFFF", 4.6), # sub-heads, rules, bars "brand": brand.upper(), # fills, dots -- NOT text "tint": mix(brand, "#FFFFFF", 0.86), # callouts, table zebra "tint2": mix(brand, "#FFFFFF", 0.94), # faintest panel ground "ink": "#1A1418", "slate": "#5A5560", "line": mix(adjust(brand, ds=-0.62), "#FFFFFF", 0.74), # hairline borders "green": "#17604A", "red": "#B3261E", } def audit(p): """Check every pair the templates actually use for text.""" pairs = [ ("deep on white", p["deep"], "#FFFFFF", 4.5), ("mid on white", p["mid"], "#FFFFFF", 4.5), ("ink on white", p["ink"], "#FFFFFF", 4.5), ("slate on white", p["slate"], "#FFFFFF", 4.5), ("deep on tint", p["deep"], p["tint"], 4.5), ("ink on tint2", p["ink"], p["tint2"], 4.5), ("white on deep", "#FFFFFF", p["deep"], 4.5), ("white on mid", "#FFFFFF", p["mid"], 4.5), ("green on white", p["green"], "#FFFFFF", 4.5), ("red on white", p["red"], "#FFFFFF", 4.5), ("brand on white (fills only -- expected to fail for text)", p["brand"], "#FFFFFF", 4.5), ] print("\ncontrast audit") worst = None for name, fg, bg, need in pairs: r = contrast(fg, bg) ok = r >= need tag = "ok " if ok else "LOW" print(" %s %-58s %5.2f:1" % (tag, name, r)) if "fills only" not in name and (worst is None or r < worst[1]): worst = (name, r) if worst: print("\n lowest text pair: %s at %.2f:1" % worst) print("\n Body text needs 4.5:1; text >=18pt regular or >=14pt bold needs 3:1.") print(" Never set body text in `brand` -- it is a fill colour.") def main(): ap = argparse.ArgumentParser() ap.add_argument("--brand", help="brand hex, e.g. '#FD698D'") ap.add_argument("--from-image", help="sample the dominant non-transparent colour from a PNG") ap.add_argument("--check", nargs=2, metavar=("FG", "BG"), help="contrast for one pair") ap.add_argument("--css", action="store_true", help="emit only the CSS :root block") a = ap.parse_args() if a.check: r = contrast(*a.check) print("%s on %s -> %.2f:1 (%s body, %s large)" % (a.check[0], a.check[1], r, "PASS" if r >= 4.5 else "FAIL", "PASS" if r >= 3.0 else "FAIL")) return brand = a.brand if a.from_image: try: from PIL import Image from collections import Counter im = Image.open(a.from_image).convert("RGBA") c = Counter(px[:3] for px in im.getdata() if px[3] > 200 and px[:3] != (255, 255, 255)) if not c: sys.exit("No opaque non-white pixels found in %s" % a.from_image) brand = rgb2hex(c.most_common(1)[0][0]) print("sampled brand colour from %s -> %s" % (a.from_image, brand)) except ImportError: sys.exit("Sampling needs Pillow (pip install pillow), or pass --brand directly.") if not brand: sys.exit("Pass --brand '#RRGGBB', --from-image logo.png, or --check FG BG.") p = derive(brand) print("\n:root{") for k, v in p.items(): print(" --%-6s %s;" % (k + ":", v)) print("}") if not a.css: audit(p) if __name__ == "__main__": main() ```