High-Quality Flowcharts — Build Print-Ready PDF Diagrams
This skill produces publication-grade PDF diagrams from user descriptions. Every output is a standalone, printable PDF with crisp vector geometry, clean typography, and intentional layout. The user gets three deliverables: the PDF, the HTML+SVG source, and a verification preview.
CRITICAL: You Must Match the Template Style
The skill ships with example PDF templates in templates/. Your output MUST look like them — same design language, same visual quality. Before writing any code:
- Open every template PDF in
templates/ (full-stack.pdf, ux-design.pdf, computer-science.pdf, cpp.pdf, c.pdf). Study each one.
- Extract their design language: note the exact colors, font sizes, node shapes, border radii, connector styles, spacing rhythm, header treatment, and how branches attach to the spine.
- List what you see — write down the specific visual properties you observe. If the templates use thin 1px borders with subtle drop shadows, so must you. If they use rounded rects with
rx="8" and bold 14px labels, match that exactly.
- Only then start coding. Your output must pass a visual consistency check against the templates.
Do NOT invent a new visual style. Replicate the template look. The templates are the ground truth for what "polished" means.
Why This Approach Matters
Raw auto-generated diagrams usually look bad — inconsistent spacing, clipped text, wrong paper size, no visual hierarchy. This skill works differently:
- HTML/CSS handles the document frame (pages, margins, typography, print rules)
- Inline SVG renders the diagram itself (nodes, connectors, labels) — text is searchable, lines are crisp at any zoom
- PDF export via a headless browser or library preserves everything faithfully
The user is asking for something they can print, present, or share. Treat this as a design artifact, not a code exercise.
Core Workflow
Do these steps in order. Each has a specific purpose — don't skip or reorder.
1. Study the Templates (Mandatory)
Read every PDF in templates/. These are your style reference. Note:
- Color palette: exact hex codes used for node fills, borders, text, connectors, headers
- Typography: font family, title size, section header size, body/node text size
- Node styling: border radius
rx values, stroke widths, fill colors, shadow effects
- Connector styling: stroke width, color, dash patterns, arrowhead shape
- Layout rhythm: spacing between nodes, margins from page edge, spine width
- Header area: title placement, subtitle style, any logo or decorative element
After studying them, write down the design tokens you extracted. This is your style guide for the diagram.
2. Understand the Content Structure
Before writing any code, figure out what kind of diagram you're building and what the hierarchy looks like.
- What's the top-level concept? (the central topic or starting point)
- What are the major sections or steps? (the spine or main flow)
- What are the sub-items or branches? (details branching off each major section)
- Are there decisions or conditional paths? (yes/no branches, alternate routes)
Write this out as a structured outline before touching HTML. This prevents mid-construction rewrites.
3. Choose the Right Layout Pattern
Match the content to the best visual structure. Picking the wrong layout produces a confusing diagram.
| Pattern |
When to Use |
Visual Structure |
| Roadmap (Vertical Spine) |
Learning paths, skill trees, curriculum guides, timelines |
Central vertical spine, subtopics branch left/right |
| Process Flow (Horizontal) |
Business workflows, algorithms, step-by-step guides, pipelines |
Left-to-right linear chain with solid arrows |
| Decision Tree (Top-Down) |
Troubleshooting guides, logic branching, yes/no diagnostics |
Diamond decision nodes at top, rectangular actions below, labeled branches |
| Taxonomy Map (Clusters) |
Topic classifications, org charts, category hierarchies, mind maps |
Central hub with grouped clusters radiating outward |
Example: If the user says "show me a learning path for Python", that's a Roadmap. If they say "walk me through deploying a web app", that's a Process Flow. Get this right before you write any SVG.
4. Build the HTML/CSS Shell (The Document Frame)
This creates the printable page. The @page CSS rule is critical — without it the PDF export won't respect paper size.
Apply the design tokens you extracted from the templates. Use the template's exact colors, font sizes, and spacing. The HTML shell below is a starting point — customize it to match the template style.
<!DOCTYPE html>
<html>
<head>
<style>
@page { size: A4 landscape; margin: 0.4in; }
* { margin: 0; padding: 0; box-sizing: border-box; }
body { /* Use font family from templates */ }
.page { /* Use padding/spacing from templates */ }
.title { /* Use font size, weight, color from templates */ }
.subtitle { /* Use font size, color from templates */ }
svg.diagram { width: 100%; height: auto; display: block; }
/* Add the template's exact node, connector, and header styles */
</style>
</head>
<body>
<div class="page">
<div class="title">Diagram Title</div>
<div class="subtitle">Optional subtitle or description</div>
<svg class="diagram" viewBox="0 0 WIDTH HEIGHT" xmlns="http://www.w3.org/2000/svg">
<!-- Diagram elements go here -->
</svg>
</div>
</body>
</html>
Key decisions to make:
- Paper size: A4 (default, most common for printing) or Letter. Prefer landscape for wide diagrams.
- Margins: 0.4in minimum on all sides. Less than that risks content being clipped by printers.
- SVG viewBox: Set this to the logical coordinate space of your diagram. Use a coordinate system where X grows right and Y grows down.
5. Render the Diagram as Inline SVG
This is the core of the output. Every element in the diagram is a named SVG <g> group with clear coordinates.
Coordinate system conventions:
- Work in a unified coordinate space (e.g.,
viewBox="0 0 1200 800" for a full-page diagram)
- Place elements at explicit (x, y) positions — don't rely on auto-layout
- Use a 20px or 40px grid alignment to keep things visually consistent
Node types (match template styling exactly):
- Section headers (spine nodes):
<rect> with rounded corners (rx="8"), bold centered text, colored fill as seen in templates
- Subtopic nodes: Smaller
<rect> with lighter fill, regular weight text, matching template border radius
- Decision diamonds:
<polygon> with four points, question text centered inside, using template color scheme
- End nodes / terminals:
<rect> with rx="20" (pill shape) using template's terminal styling
Connectors:
- Spine lines: Solid or dashed vertical/horizontal
<line> using template's stroke color and width
- Branch connectors: Curved
<path> using cubic bezier (C commands) for smooth curves
- Process arrows:
<path> with marker-end arrowhead, or a separate <polygon> for the arrowhead
- Decision branches: Straight lines from diamond corners with "Yes"/"No" labels
Typography within SVG (match template sizes exactly):
- Section names inside SVG: as seen in templates (typically
font-size="14" to font-size="16", bold)
- Subtopic labels inside SVG: as seen in templates (typically
font-size="12" to font-size="13")
- Connector labels: as seen in templates (typically
font-size="10" to font-size="11")
- Use the template's font family throughout. Keep to sans-serif that renders reliably.
6. Generate the PDF
Use the bundled script — it tries multiple backends automatically:
python scripts/generate_pdf.py output.html output.pdf [--landscape] [--paper-size A4]
The script tries Playwright first (best quality), then WeasyPrint, then pdfkit.
7. Verify the Output
Run the verification script to produce a preview image:
python scripts/verify_pdf.py output.pdf
Open the preview and visually check for:
- Does it match the template style? Compare side by side
- Clipped text — text that overflows its box or reaches the page edge
- Overlapping elements — nodes sitting on top of each other
- Broken connectors — lines that don't connect properly or miss their target
- Missing labels — empty connectors, blank nodes
- Wrong paper orientation — content doesn't fit or looks squished
If you see problems, go back to step 4/5 and fix.
8. Deliver Everything
When the user's request is complete, always deliver these three files:
- The PDF — polished, ready to print or share
- The HTML source — so they can edit it later
- The verification image — proves it rendered correctly
Common Patterns & Sizing Reference
These are defaults. Adjust to match template dimensions if they differ.
Node Sizing
| Element |
Width (px) |
Height (px) |
Notes |
| Spine/section header |
220 |
44 |
Center column, larger |
| Subtopic branch |
180 |
34 |
Side columns |
| Decision diamond |
180 |
180 |
Points at top/bottom/left/right |
| Terminal/end node |
180 |
40 |
Rounded pill shape |
Spacing
- Between spine nodes: 80–100px vertically
- Between branches and spine: 120–150px horizontally
- Between sibling subtopics: 30–40px vertically
- Page margins: 0.4in minimum
Layout Dimensions (A4 Landscape, 1200x800 coordinate space)
- Center spine runs at X=600
- Left branches: X=150 to X=400
- Right branches: X=800 to X=1050
- Y starts at ~120 (below title) and ends at ~750 (before bottom margin)
Troubleshooting
| Problem |
Likely Cause |
Fix |
| PDF has no content (blank) |
The viewBox or SVG dimensions are wrong |
Set explicit viewBox="0 0 W H" and ensure elements are within bounds |
| Text is clipped |
Node too small for text, or margins too tight |
Increase node width by 20-40px first, then font size |
| Connectors don't reach their target |
Source/target coordinates don't match actual element positions |
Use element centers, not edges, for connector endpoints |
| PDF generation hangs or fails |
Missing backend tool |
Install playwright: npx playwright install chromium |
| Colors look wrong in PDF |
CSS custom properties not resolving in SVG |
Use inline fill="#xxxxxx" directly in SVG instead of CSS var() |
| Landscape doesn't work |
@page orientation missing |
Add size: A4 landscape to @page rule |
| Diagram feels cramped |
Too much content for one page |
Increase paper size, use larger viewBox, or split into multiple pages |
| Output doesn't match template style |
You didn't study the templates first |
Go back to step 1 and extract exact design tokens from templates/ |
Reference Files
templates/ — STUDY THESE FIRST. They define the visual style your output must match.references/layout-patterns.md — Visual structure details for each patternreferences/visual-style.md — Color palette and typography tokens (verify against templates)scripts/generate_pdf.py — HTML→PDF conversion (tries multiple backends)scripts/verify_pdf.py — Creates preview image for manual verification
1---2name: nextreme-flowcharts3description: Design and produce polished, publication-grade flowcharts, roadmaps, process diagrams, decision trees, and taxonomy maps using HTML/CSS shells with inline SVG geometry and PDF export. Trigger this skill whenever the user asks for a "flowchart", "roadmap", "process diagram", "decision tree", "org chart", "curriculum guide", "skill tree", "workflow", "yes/no flow", "classification map", or any kind of visual diagram that belongs in a clean printable PDF — even if they don't explicitly say "PDF" or "flowchart". Also trigger when they want to visualize steps, logic, hierarchies, branching decisions, or learning paths. Do NOT trigger for simple code flow comments, quick sketches, or things better done as Mermaid diagrams in a markdown file — this skill is specifically for producing a standalone, print-ready PDF artifact.4license: MIT5---67# High-Quality Flowcharts — Build Print-Ready PDF Diagrams89This skill produces **publication-grade PDF diagrams** from user descriptions. Every output is a standalone, printable PDF with crisp vector geometry, clean typography, and intentional layout. The user gets three deliverables: the **PDF**, the **HTML+SVG source**, and a **verification preview**.1011---1213## CRITICAL: You Must Match the Template Style1415The skill ships with example PDF templates in `templates/`. Your output MUST look like them — same design language, same visual quality. Before writing any code:16171. **Open every template PDF** in `templates/` (full-stack.pdf, ux-design.pdf, computer-science.pdf, cpp.pdf, c.pdf). Study each one.182. **Extract their design language**: note the exact colors, font sizes, node shapes, border radii, connector styles, spacing rhythm, header treatment, and how branches attach to the spine.193. **List what you see** — write down the specific visual properties you observe. If the templates use thin 1px borders with subtle drop shadows, so must you. If they use rounded rects with `rx="8"` and bold 14px labels, match that exactly.204. **Only then** start coding. Your output must pass a visual consistency check against the templates.2122Do NOT invent a new visual style. Replicate the template look. The templates are the ground truth for what "polished" means.2324---2526## Why This Approach Matters2728Raw auto-generated diagrams usually look bad — inconsistent spacing, clipped text, wrong paper size, no visual hierarchy. This skill works differently:2930- **HTML/CSS** handles the document frame (pages, margins, typography, print rules)31- **Inline SVG** renders the diagram itself (nodes, connectors, labels) — text is searchable, lines are crisp at any zoom32- **PDF export** via a headless browser or library preserves everything faithfully3334The user is asking for something they can print, present, or share. Treat this as a design artifact, not a code exercise.3536---3738## Core Workflow3940Do these steps in order. Each has a specific purpose — don't skip or reorder.4142### 1. Study the Templates (Mandatory)4344Read every PDF in `templates/`. These are your style reference. Note:45- **Color palette**: exact hex codes used for node fills, borders, text, connectors, headers46- **Typography**: font family, title size, section header size, body/node text size47- **Node styling**: border radius `rx` values, stroke widths, fill colors, shadow effects48- **Connector styling**: stroke width, color, dash patterns, arrowhead shape49- **Layout rhythm**: spacing between nodes, margins from page edge, spine width50- **Header area**: title placement, subtitle style, any logo or decorative element5152After studying them, write down the design tokens you extracted. This is your style guide for the diagram.5354### 2. Understand the Content Structure5556Before writing any code, figure out what kind of diagram you're building and what the hierarchy looks like.5758- **What's the top-level concept?** (the central topic or starting point)59- **What are the major sections or steps?** (the spine or main flow)60- **What are the sub-items or branches?** (details branching off each major section)61- **Are there decisions or conditional paths?** (yes/no branches, alternate routes)6263Write this out as a structured outline before touching HTML. This prevents mid-construction rewrites.6465### 3. Choose the Right Layout Pattern6667Match the content to the best visual structure. Picking the wrong layout produces a confusing diagram.6869| Pattern | When to Use | Visual Structure |70|---|---|---|71| **Roadmap** (Vertical Spine) | Learning paths, skill trees, curriculum guides, timelines | Central vertical spine, subtopics branch left/right |72| **Process Flow** (Horizontal) | Business workflows, algorithms, step-by-step guides, pipelines | Left-to-right linear chain with solid arrows |73| **Decision Tree** (Top-Down) | Troubleshooting guides, logic branching, yes/no diagnostics | Diamond decision nodes at top, rectangular actions below, labeled branches |74| **Taxonomy Map** (Clusters) | Topic classifications, org charts, category hierarchies, mind maps | Central hub with grouped clusters radiating outward |7576**Example**: If the user says "show me a learning path for Python", that's a **Roadmap**. If they say "walk me through deploying a web app", that's a **Process Flow**. Get this right before you write any SVG.7778### 4. Build the HTML/CSS Shell (The Document Frame)7980This creates the printable page. The `@page` CSS rule is critical — without it the PDF export won't respect paper size.8182Apply the design tokens you extracted from the templates. Use the template's exact colors, font sizes, and spacing. The HTML shell below is a starting point — customize it to match the template style.8384```html85<!DOCTYPE html>86<html>87<head>88<style>89 @page { size: A4 landscape; margin: 0.4in; }90 * { margin: 0; padding: 0; box-sizing: border-box; }91 body { /* Use font family from templates */ }92 .page { /* Use padding/spacing from templates */ }93 .title { /* Use font size, weight, color from templates */ }94 .subtitle { /* Use font size, color from templates */ }95 svg.diagram { width: 100%; height: auto; display: block; }96 /* Add the template's exact node, connector, and header styles */97</style>98</head>99<body>100<div class="page">101 <div class="title">Diagram Title</div>102 <div class="subtitle">Optional subtitle or description</div>103 <svg class="diagram" viewBox="0 0 WIDTH HEIGHT" xmlns="http://www.w3.org/2000/svg">104 <!-- Diagram elements go here -->105 </svg>106</div>107</body>108</html>109```110111**Key decisions to make:**112- **Paper size**: A4 (default, most common for printing) or Letter. Prefer landscape for wide diagrams.113- **Margins**: 0.4in minimum on all sides. Less than that risks content being clipped by printers.114- **SVG viewBox**: Set this to the logical coordinate space of your diagram. Use a coordinate system where X grows right and Y grows down.115116### 5. Render the Diagram as Inline SVG117118This is the core of the output. Every element in the diagram is a named SVG `<g>` group with clear coordinates.119120**Coordinate system conventions:**121- Work in a unified coordinate space (e.g., `viewBox="0 0 1200 800"` for a full-page diagram)122- Place elements at explicit (x, y) positions — don't rely on auto-layout123- Use a 20px or 40px grid alignment to keep things visually consistent124125**Node types (match template styling exactly):**126- **Section headers (spine nodes)**: `<rect>` with rounded corners (`rx="8"`), bold centered text, colored fill as seen in templates127- **Subtopic nodes**: Smaller `<rect>` with lighter fill, regular weight text, matching template border radius128- **Decision diamonds**: `<polygon>` with four points, question text centered inside, using template color scheme129- **End nodes / terminals**: `<rect>` with `rx="20"` (pill shape) using template's terminal styling130131**Connectors:**132- **Spine lines**: Solid or dashed vertical/horizontal `<line>` using template's stroke color and width133- **Branch connectors**: Curved `<path>` using cubic bezier (`C` commands) for smooth curves134- **Process arrows**: `<path>` with marker-end arrowhead, or a separate `<polygon>` for the arrowhead135- **Decision branches**: Straight lines from diamond corners with "Yes"/"No" labels136137**Typography within SVG (match template sizes exactly):**138- Section names inside SVG: as seen in templates (typically `font-size="14"` to `font-size="16"`, bold)139- Subtopic labels inside SVG: as seen in templates (typically `font-size="12"` to `font-size="13"`)140- Connector labels: as seen in templates (typically `font-size="10"` to `font-size="11"`)141- Use the template's font family throughout. Keep to sans-serif that renders reliably.142143### 6. Generate the PDF144145Use the bundled script — it tries multiple backends automatically:146147```bash148python scripts/generate_pdf.py output.html output.pdf [--landscape] [--paper-size A4]149```150151The script tries Playwright first (best quality), then WeasyPrint, then pdfkit.152153### 7. Verify the Output154155Run the verification script to produce a preview image:156157```bash158python scripts/verify_pdf.py output.pdf159```160161Open the preview and visually check for:162- **Does it match the template style?** Compare side by side163- **Clipped text** — text that overflows its box or reaches the page edge164- **Overlapping elements** — nodes sitting on top of each other165- **Broken connectors** — lines that don't connect properly or miss their target166- **Missing labels** — empty connectors, blank nodes167- **Wrong paper orientation** — content doesn't fit or looks squished168169If you see problems, go back to step 4/5 and fix.170171### 8. Deliver Everything172173When the user's request is complete, always deliver these three files:1741751. **The PDF** — polished, ready to print or share1762. **The HTML source** — so they can edit it later1773. **The verification image** — proves it rendered correctly178179---180181## Common Patterns & Sizing Reference182183These are defaults. Adjust to match template dimensions if they differ.184185### Node Sizing186| Element | Width (px) | Height (px) | Notes |187|---|---|---|---|188| Spine/section header | 220 | 44 | Center column, larger |189| Subtopic branch | 180 | 34 | Side columns |190| Decision diamond | 180 | 180 | Points at top/bottom/left/right |191| Terminal/end node | 180 | 40 | Rounded pill shape |192193### Spacing194- Between spine nodes: 80–100px vertically195- Between branches and spine: 120–150px horizontally196- Between sibling subtopics: 30–40px vertically197- Page margins: 0.4in minimum198199### Layout Dimensions (A4 Landscape, 1200x800 coordinate space)200- Center spine runs at X=600201- Left branches: X=150 to X=400202- Right branches: X=800 to X=1050203- Y starts at ~120 (below title) and ends at ~750 (before bottom margin)204205---206207## Troubleshooting208209| Problem | Likely Cause | Fix |210|---|---|---|211| PDF has no content (blank) | The viewBox or SVG dimensions are wrong | Set explicit viewBox="0 0 W H" and ensure elements are within bounds |212| Text is clipped | Node too small for text, or margins too tight | Increase node width by 20-40px first, then font size |213| Connectors don't reach their target | Source/target coordinates don't match actual element positions | Use element centers, not edges, for connector endpoints |214| PDF generation hangs or fails | Missing backend tool | Install playwright: `npx playwright install chromium` |215| Colors look wrong in PDF | CSS custom properties not resolving in SVG | Use inline `fill="#xxxxxx"` directly in SVG instead of CSS var() |216| Landscape doesn't work | @page orientation missing | Add `size: A4 landscape` to @page rule |217| Diagram feels cramped | Too much content for one page | Increase paper size, use larger viewBox, or split into multiple pages |218| Output doesn't match template style | You didn't study the templates first | Go back to step 1 and extract exact design tokens from templates/ |219220---221222## Reference Files223224- `templates/` — **STUDY THESE FIRST.** They define the visual style your output must match.225- `references/layout-patterns.md` — Visual structure details for each pattern226- `references/visual-style.md` — Color palette and typography tokens (verify against templates)227- `scripts/generate_pdf.py` — HTML→PDF conversion (tries multiple backends)228- `scripts/verify_pdf.py` — Creates preview image for manual verification
beast-ofcourse