chenruishuo/posterly/posterly

posterly — HTML/CSS Academic Poster Workflow

A poster is one HTML file styled for an exact print canvas, rendered to PDF via Playwright + Chromium. Iterate by measuring, not eyeballing — the screen preview lies; only emulate_media("print") at the correct viewport tells the truth.

Mental model

   HTML (with @page { size: W H })
     │
     ▼  print-emulate Chromium at W×96 × H×96 px viewport
     │
     ▼  data-measure-role tags identify columns/hero/footer-strip
     │
     ├──→ tools/poster_check.py measure  (HARD GATE — spread < 5 px,
     │                                    gap-to-strip ∈ [30,50] px,
     │                                    intercard gap ∈ [12,50] px,
     │                                    poster bbox aligns to page
     │                                    within ±2 px)
     ├──→ tools/poster_check.py preflight  (LaTeX residue, math `<`, missing imgs)
     ├──→ tools/render_preview.py  (PDF + thumbnail)
     └──→ tools/poster_check.py verify-final  (PDF page count / dims / size)

The skill is venue- and lab-neutral by default. Compose a design direction from templates/DESIGN-AXES.md (Step 2.5), scaffold from the nearest template in templates/README.md, edit :root design tokens to match the locked direction, fill TODO placeholders with your paper's content.

Canvas constants

<a id="python-environment"></a>

Python environment

Invoke Python by the full path of a dedicated, non-base environment. /absolute/path/to/dedicated-env/bin/python is a placeholder: replace it with the verified absolute interpreter path of the current machine's dedicated non-base environment for Posterly tools and Python snippets. Install missing Python dependencies with /absolute/path/to/dedicated-env/bin/python -m pip install ..., and run Playwright installation with the same interpreter's -m playwright. Never use bare python, python3, or pip, rely on conda activate, or install into base. A missing module must be resolved in the dedicated environment, not by falling back to base.

Tool help, diagnostics, and exported examples may use portable shorthand; before executing those commands, expand it to that full path. run_gates.py already launches its Python children through sys.executable, preserving the selected interpreter. Keep all existing command arguments, installation approval boundaries, and validation obligations.

Reading contract and execution boundaries

Before performing each stage, you must read and execute its linked applicable sections, including substeps, exceptions, examples, manual checks, and prerequisites. Read the required sections, not every referenced file in full. Mandatory instructions and checks remain mandatory; optional helpers remain optional. The routes below do not replace those instructions.

Paths: Markdown links are relative to the containing file. Command and inline paths such as tools/, templates/, assets/, specimens/, README, and <skill> are relative to the skill root (the directory containing SKILL.md); poster working paths retain their working-directory meaning.

<a id="task-modes"></a>

Choose the task path before starting.

• New poster or overall redesign: follow the complete design workflow below, including Step 2.5's 2–3 rendered candidates and design lock. Reuse supplied answers under the confirmation policy.
• Local edit to an existing poster: when the requested text, number, or asset changes preserve the canvas size/orientation and the accepted design direction, edit the existing working HTML directly. Reuse its current design, tokens, and recorded decisions; do not recompose or render 2–3 design candidates, ask for another design selection, or copy a fresh gallery scaffold over the poster. Read the relevant Step 3 authoring/component contracts and writing guidance for the edit, and Step 2 requirements for affected assets. Routine reflow/spacing repairs within the same direction remain local edits and still follow the existing style/fix rules.

Both paths retain source/venue verification, Step 3 authoring/copy/theorem obligations, the mandatory Step 3.5 content audit on the filled or updated poster, Step 4–6 checks and visual inspection, and Step 7 final-file verification/export. Existing unchanged-version preflight/polish reuse remains available; changing text, numbers, assets, or layout invalidates the corresponding old results. Step 6.5 cross-model final review remains strongly recommended. The local-edit path changes design preparation, not those quality requirements.

If the requested work requires a different canvas or design direction, follow the existing confirmation policy before applying the change and use the complete design workflow. Follow the confirmation, non-interactive, identity, system-extension, and upstream-feedback rules in the linked stages.

<a id="confirmation-policy"></a>

Reuse supplied answers and existing confirmations. For the same poster and unchanged decision, directly use information the user has already supplied or confirmed in the conversation or project notes: dimensions/orientation, palette, logos, QR target, density/block count, source paths, and content preferences. Explicit “none”, “no preference”, and “you choose” are answers within their stated scope, not missing information. Ask only about missing items or unresolved conflicts; do not repeat a question merely because another workflow stage mentions it. Record answers and keep required source/venue checks: reusing an answer does not waive verification. Do not transfer a choice from a different poster without evidence that it applies here.

Changes to locked choices still need confirmation. Before applying a proposed change to the locked canvas size/orientation or design direction, obtain confirmation for that change; an explicit user instruction authorizing that exact change already supplies it and must not be asked again. The existing non-interactive design-direction exception remains as documented. Reusing one preference does not authorize a different system extension, crop/waiver decision, or external action; retain those original approval boundaries and any approval already granted for the same action.

Read the universal pitfalls before authoring; read layout-specific pitfalls and all applicable visual rules before authoring/inspecting affected content. These contain preventive and manual obligations even when automated checks pass. During a fix, consult the relevant rule rather than reloading unrelated cases.

Style rules 4 and 5 are opt-in requirements. Enforce the two-hue-family limit (rule 4) and gradient restrictions (rule 5) only when the respective rule is explicitly enabled for the current poster. Otherwise ignore the corresponding requirements, including rules repeated as component anti-patterns or recommended catalog conventions; do not reduce palette breadth or remove gradients to satisfy a disabled rule. Other requirements remain in force. Keep tool flags consistent with that choice; see the style-rule switch contract.

Step 0 / Step 0.5 / Step 1 — Venue, discovery, and source content

At each stage, read and follow venue, discovery, and content. Apply the confirmation policy to missing or conflicting inputs; verify sources even when answers are already supplied.

For palette work, read palette derivation, including seed-independent rules when the user supplies colors and the theme mechanisms in that file.

Step 2 — Image preprocessing

Read and follow image preprocessing for the figures, QR codes, and logos used. Read Gate A before figure placement and Gate E before logo placement.

Read and execute the real-figure provenance contract only when adopting it. Otherwise asset verification is NOT_RUN, not verified; ordinary image-processing and fidelity requirements still apply.

Step 2.5 — Compose, show, and lock the design (new posters / redesigns)

For new posters or redesigns, read and follow design direction and DESIGN-AXES: compose and render 2–3 candidates, then lock the selection. Apply the documented batch and non-interactive rules. Local edits keep the accepted direction.

Before preparing fonts or tokens, read direction item 4. Always write design_tokens.json at design lock and pass it on every gate run.

Step 3 — Scaffold, content, and identity

For new scaffolds, read and follow scaffolding, template contracts, and gallery. Local edits apply the Step 3 authoring contracts to the existing HTML without copying a fresh scaffold. Both paths must follow identity and the COMPONENTS entries for every component used.

Before scaffolding, read the style gate; run it right after the scaffold and on every layout change within its documented scope.

Read and follow WRITING, perform its pre-loop sweep and Step 3's theorem/equation check. Do not try to make an unfilled scaffold pass filled-poster gates.

Step 3.5 — Content audit

After filling or updating the poster, and before Step 4, read and execute the mandatory content audit and applicable review checkpoints. Proceed only after every finding is fixed or explicitly recorded as a user-acknowledged tradeoff.

Step 4 — Budgeted layout loop

Before the first loop, read and follow measurement, enhanced gates, runner, style gate, and fix discipline.

Use the complete run_gates.py sequence after each layout change under the documented template/fallback scope. Apply unchanged-version result reuse only when its conditions hold. Follow the hard thresholds and exit-3 circuit breaker; do not reset the budget just to continue grinding or bypass system-extension approval. Consult tool contracts for the commands used.

Step 5 / Step 6 — Render, inspect, and polish