pdf-design-skill

name

pdf-design-skill

description

Generate beautifully designed PDF documents — reports, guides, plans, audits, kits — in one of five named visual styles. Use this skill whenever the user asks for a designed PDF, a styled document, a report or guide "in the editorial / soft / noir / blueprint / modern style," or any polished multi-page PDF deliverable, even if they just say "make it look good" or "design this properly." Supports tables, charts, to-do lists, simple infographics, and rule-based spot illustrations. Not for filling PDF forms or extracting text from PDFs.

pdf-design-skill — designed PDF documents in five styles

Turns content into a designed, multi-page PDF in one of five visual styles. The styles are complete identities, not themes: each has its own type system, palette, components, and illustration grammar. The output should look like a designer laid it out, not like a styled Word export.

The styles

Style	Feel	Use when
editorial	Warm paper, vermilion display type, powder-blue section pages, elegant serif italics. Magazine energy.	Guides, manifestos, lookbooks, anything with a voice
soft	White, pale-green rounded cards, lime highlighter labels, clean grotesque headings. Calm and functional.	Plans, worksheets, checklists, client docs, professional reports
noir	Charcoal grid, lime accents, Playfair headlines with one lime italic word, mono labels. Studio-dark.	Audits, playbooks, creator kits, anything with edge
blueprint	One royal blue, typewriter display type, engineer's dot grid, hand-sketched diagrams. A plan drawn with conviction.	Manifestos, frameworks, workbooks, method guides
modern	Terracotta cover with huge staggered grotesque type; vermilion, yellow and blue arriving as flat shape blocks. Loud and graphic.	Guides, ebooks, manifestos, personal-brand docs, punchy reports

If the user doesn't name a style, prompt them to pick one at the start of the conversation (see intake below). Use the content's temperature to lead with a recommendation: warm/expressive → editorial, neutral/practical → soft, bold/opinionated → noir, method/framework-driven → blueprint, punchy/motivational → modern.

Working with the user

This skill will be used by people who aren't designers and may not know what to provide. Run a short intake before building anything.

HARD GATE — nothing renders until intake is answered. Do not write template HTML or render any PDF until the user has explicitly answered the intake items below. Research (fetching a URL they gave, reading their files) may happen first, but the intake questions still get asked — put any unanswered ones in ONE combined message to keep friction low. Never pick a style for the user: recommending one is good, but the user confirms before you build. A request that "seems complete enough" is not permission to skip the questions — that is exactly the case where output disappoints, because the user never got to choose.

1. Style — always the first message. As soon as the skill triggers, prompt the user to pick their style before anything else, listing all five with their one-line vibes from the table above. If a multiple-choice question tool is available (e.g. AskUserQuestion), use it with the five styles as options; otherwise list them in chat. If their request already hints at content, recommend one ("your content feels like noir — bold, opinionated") and make it the first option. Skip the prompt only when they named a style themselves in their own words — a style you inferred does not count, no matter how confident the inference.
2. Content — if they haven't given it, ask for it. If they only have bullet points, offer to draft the copy and say so plainly.
3. Wording — ask explicitly: "Want me to polish the wording, or use your text exactly as written?" As-is → typography fixes only (curly quotes, dashes), flag typos rather than fixing them. Polish → tighten and clarify, but keep their voice, facts, and claims — never invent content — and show the rewrite at the draft checkpoint so they can see what changed.
4. Author line — name or handle for the footer of every page.
5. Images — ask once: "Do you want photos or images in the doc? If yes, drop them into this chat and I'll place them where they fit." If they say yes, wait for the uploads before building. Never ask twice; never generate images.

Draft checkpoint (docs over ~5 pages): render the cover + one representative content page first, share that 2-page PDF, and confirm the direction before building the rest. Fixing taste at page 2 is cheap; at page 12 it's a rebuild.

Contact-sheet preview: there is no live preview panel, so make the chat work like one. After every render — draft checkpoint, full build, and each edit round — build a contact sheet (render pages at low res with pdftoppm -png -r 40, tile them into one image with PIL, 3–4 per row with page numbers) and share it alongside the PDF. Users can scan every page at a glance and point at what to change ("page 3, the chart") without opening the file.

Edit loop: always keep the .html source next to the rendered PDF. When the user asks for changes ("shorter title", "donut instead of bars", "swap page 3 and 4"), edit the source and re-render — never rebuild from scratch. Share the updated PDF and contact sheet after every edit round.

After delivering, offer the edit menu in one short line so users know what's cheap to ask for: reword or retitle anything · swap a chart type · move, merge, or delete pages · replace images · or re-flow the whole document into a different style. Style switching is inexpensive (content and CSS are separate), so offer it explicitly if the user seemed unsure of their style pick.

Workflow

1. Content first. Get the final content before designing (see intake above). Honor the wording choice from intake: as-is means verbatim — typography fixes only (curly quotes, en/em dashes), flag factual or grammar issues rather than silently fixing them; polish means tighten in their voice without inventing facts.
2. Read the style reference for the chosen style: references/style-editorial.md, references/style-soft.md, references/style-noir.md, references/style-blueprint.md, or references/style-modern.md. It has the full token table, component rules, and illustration grammar.
3. Run scripts/setup_fonts.sh once per session (installs WeasyPrint and builds all font instances for all five styles).
4. Copy the style's template from assets/ (editorial.html, soft.html, noir.html, blueprint.html, modern.html) and replace the content. The template demonstrates every component with correct spacing — edit content, not CSS, unless a new component is truly needed.
5. Render: python3 -m weasyprint input.html "Title.pdf"
6. Verify visually — non-negotiable. Convert every page (pdftoppm -png -r 60), read each image, and check: no overflow, no orphaned headings at page bottoms, footers present, page numbers sequential, charts labeled, page balance (a page that's mostly empty looks unfinished — merge it with a neighbor).

Component contract (all styles support these)

• Data table — column headers + hairline rows. Keep to ≤4 columns on letter width; split wider data into two tables.
• Charts — inline SVG only (WeasyPrint runs no JS). Four types: horizontal bars, vertical bars, donut, simple line. Construction rules that separate designed charts from rough ones: scale bars to the max value with the largest bar at ~75% of chart width; bar gap 60–80% of bar height; label every bar with its value at the bar end; one accent-colored "key" series (the largest or most important), the rest neutral; add 2–3 faint dotted gridlines with small value labels when values aren't self-evident; align category labels on a common left edge. If data doesn't fit these four types, use a table instead — never invent a chart type.
• To-do list — open and done states, optional muted parenthetical notes.
• Infographic patterns — exactly four: stat row (2–3 big numbers), numbered steps, timeline, spot illustration. Resist inventing new patterns; constraint is what keeps output looking designed.
• Callout / card — for evidence, caveats, summaries.
• Cover, TOC (for 8+ pages), section openers, closing page.

Spot illustrations

Illustrations are drawn as SVG following each style's grammar. They are opt-in, not default — most pages should have none.

When to draw one. Only when the page's text makes one clear conceptual move (a filter, a decision, growth, consolidation) AND the page has room to give the drawing air. Skip pages that already carry a chart or table — they have their visual. Target density: roughly one illustration per 2–3 pages; a 5-page document might have one or two, and zero is a valid answer for data-heavy documents.

Select before you draw. assets/illustrations/ holds a curated library of verified SVGs, four per style, named <style>-<pattern>.svg (editorial: filter/signal/path/growth · soft: grouping/filter/nest/path · noir: signal/filter/orbit/stack · blueprint: system/spark/filter/stack · modern: balance/nest/stack/tip). Default to picking the library file whose metaphor matches the text — you may scale it or swap caption, but keep its geometry. Draw a fresh illustration ONLY when no library pattern fits the cognitive move, following the workflow below and the quality gate.

The workflow matters more than the drawing:

1. Read the section the illustration accompanies. Find the cognitive move — the tension, transformation, comparison, filter, or growth the text describes.
2. Choose one metaphor for it. One idea per graphic. If you need two metaphors, you need two graphics (or zero).
3. Pick the metaphor pattern that fits the move — each style reference lists six (filter, layers, path-with-fork, signal-from-noise, stack, orbit) with construction notes. The template's example SVG is one example, not the default: if every illustration in a document is "shape → arrow → shape," that's a failure.
4. Draw it using only the style's allowed vocabulary (shapes, stroke weights, fills — see the style reference). Quality bar: 4–8 elements with deliberate size variation (small/medium/large reads as designed; five same-size shapes reads as clip-art), one focal accent element, everything else quiet, at least 40% empty space. A short caption in the style's caption treatment.
5. If no honest metaphor exists, skip the illustration. A page without one beats a decorative one.
6. Scatter, don't clump. Illustrations spread across the document — at most one per page, in varied positions: tucked into an opener's empty corner, beside a timeline column, above a closing quote, on a statement page. Never stack them on one "illustrations page," and never give one its own heading (no "Spot illustration" or "The shape of the plan" labels) — an illustration accompanies content with only its caption; a heading turns it into a section and makes it feel bolted on.

Geometry hygiene (this is what separates "designed" from "rough"):

• Shapes that should touch must touch exactly — compute the tangent point; a 3px gap or accidental overlap reads as sloppy. Shapes that shouldn't touch need clear space between them (≥ half the smaller shape's width).
• Compose on a coarse grid: centers and edges on multiples of 8–10 SVG units, sizes from a small scale (e.g. radii 6 / 10 / 16 / 24), never arbitrary values like r="13.7".
• One stroke width per graphic (the style's specified one). Mixed stroke weights inside a single illustration read as errors, not hierarchy — use size and fill for hierarchy.
• Keep every element inside the viewBox with breathing room; nothing within 8 units of the edge, and the caption never crowds the drawing.
• Balance the composition's bounding box: if all mass sits in one corner with dead space elsewhere, re-center or crop the viewBox.

The illustration check — after the full-document render, re-render each page that has an illustration at higher resolution (pdftoppm -png -r 130 -f N -l N) and look at the illustration specifically. Ask: do contact points actually touch? Does it read as one deliberate composition or random scatter? Would you post this crop on its own? If it fails, redraw it once; if it still fails, delete it and let the page breathe — a missing illustration is invisible, a rough one is the first thing readers see.

Images

Never generate or fetch images. If the user provides images, read each one and assign it to the slot whose content matches (cover hero, section divider, inline) — the templates mark slots with IMAGE SLOT comments. With no images, use the style's fallback: editorial gets full-bleed accent-color statement pages, soft and noir simply flow without image blocks.

Conventions

• 5–12 pages is the working range. US Letter.
• Footer on every page: author/brand left, page number right (set from user info — never hardcode a name).
• No overclaiming in content you're asked to draft: hedged, precise language, and any stat needs a source the reader can check.
• Name the file like a deliverable: "<Document Title>.pdf".

Pipeline quick reference

bash scripts/setup_fonts.sh                       # once per session
python3 -m weasyprint doc.html "Title.pdf"        # render
pdftoppm -png -r 60 "Title.pdf" pg                # page images for visual check

Read every pg-*.png before calling it done. Rendering "success" is not the bar — a page with overflowing text renders successfully.