| name | print-svg-style-guide |
| description | Author print-quality SVG figures for books, reports, and exec-facing documents. Ships the canvas + typography grammar (viewBoxes, print-legibility floor with math, type hierarchy, font stack, data-print-role markers, text-fits ladder), a Tailwind-grounded semantic palette (Blue = correct, Red = critique, Green = approval, Amber triple-duty, Grays scaffolding), and four structural composition idioms (BEFORE/AFTER paired panels with badges, numbered critique callouts, family-band abstracts, 5-Visual Rule dashboards). Use when authoring SVG figures for print, when reviewing a figure for print legibility, or when picking colors for a figure whose colors will carry meaning across a book or report. |
| lastReviewed | 2026-07-29T00:00:00.000Z |
Print-quality SVG style guide
Rules for print-quality SVG figures in books, reports, and exec-facing HTML. Distilled from a shipped book — Fabio Correa's The Defensible Decision, 53 figures across 14 chapters at print size 7×10in, figure width 4.39in — via Alex_DDA's dd-book-illustrator skill. Portable to any figure that will land on paper or a PDF.
Complements the big-idea family: big-idea and chart-big-idea decide what the figure ARGUES; this skill decides how it LOOKS. flint-chart's publication config preset pins the Vega-Lite config that emits charts obeying these rules. figure-generator provides the engineering discipline that emits SVGs conforming to this guide.
When to invoke
- Authoring a new SVG figure for a book, report, or exec-facing document
- Reviewing an existing figure for print-legibility, palette consistency, or composition
- Picking canvas dimensions when the target is print + on-screen
- Deciding a color role for a new figure that will co-exist with other figures in the same artifact
- Composing a BEFORE/AFTER paired panel, a numbered critique callout, a family-band abstract, or a dashboard subject to the 5-Visual Rule
Canvas + font stack
Every figure obeys three defaults unless a specific composition need overrides:
| Property | Value | When to override |
|---|
| Font stack | Inter, system-ui, sans-serif | Never in figures. Book body prose can differ (Palatino, etc.) |
| Default viewBox | 0 0 640 480 (4:3) | Standard chapter figure |
| Widescreen viewBox | 0 0 640 380 (~17:10) | Book-map, flow, wide-comparison figures |
| Dashboard viewBox | 0 0 640 415 (varies) | Dashboard-shaped figures |
Reasons to pin at 640 viewBox width: (a) the print-legibility floor math (below) is calibrated to a 640-unit reference; (b) side-by-side figures across chapters read as one voice when they share horizontal dimensions.
Print-legibility floor (gate-enforced)
Figures rendered at 7×10in with figure width 4.39in convert SVG px to print points via:
printPoints = fontSizePx × 4.39 × 72 ÷ viewBoxWidth
At the standard 640-unit viewBox that reduces to px × 0.4939. Floors:
| Class | Floor | Marker |
|---|
| Instructional (anything the reader must read) | 5.8pt | none |
| Note (annotation the reader is meant to read, below body copy) | 2.9pt | data-print-role="note" required. Auto-promoted from micro when the text is ≥40 characters |
| Micro (source notes, attribution, hash stamps, provenance) | 2.9pt | data-print-role="micro" required |
| px | pt at 640 viewBox | Verdict |
|---|
| 9px | 4.44pt | micro only |
| 10px | 4.94pt | fails as instructional |
| 11px | 5.43pt | fails as instructional |
| 12px | 5.93pt | lowest safe instructional |
Rule: minimum instructional px = viewBoxWidth ÷ 54.5. At 640 that is 11.74px, so 12px is the floor. A wider viewBox raises the floor — recompute rather than assuming 12px.
The micro marker is not an escape hatch. It exists for text the reader never needs to read at size (attribution, hash stamps). Marking instructional content micro to clear the gate is gaming it — the reader still cannot read it. The note role's auto-promote (≥40 chars) catches the class where this happens by accident.
When text won't fit at 12px, the answer is never to shrink it
Shrink-vs-overflow is a false choice; both lose. In priority order:
- Cut the text. A figure carrying sentence-length explanation is restating adjacent prose, which fails the earn-a-figure test outright (see
chart-big-idea Step 0.5). Move the sentences to the chapter body and leave labels in the figure.
- Reflow. Split one dense panel into two, or switch to the widescreen viewBox.
- Abbreviate. Fewer axis ticks, shortened value labels, a legend instead of per-point labels.
- Grow the canvas. Last resort — it changes the figure's page footprint.
Anti-pattern figures obey the floor too
A figure whose subject IS bad typography (collapsed hierarchy, unreadable clutter) must still clear 5.8pt. The gate cannot distinguish "deliberately bad" from "accidentally illegible," and neither can the reader.
Demonstrate the failure through RELATIVE properties, never absolute smallness. Typographic hierarchy is about differentiation: L1 through L4 have to differ from each other. Setting title, axis, and data labels all to 12px demonstrates collapsed hierarchy perfectly (everything is the same size) while every word stays legible in print. Setting them all to 10px demonstrates the same collapse and makes the figure unreadable, defeating its own teaching purpose.
| Failure being taught | Wrong way | Right way |
|---|
| Collapsed typographic hierarchy | Everything at 10px | Everything at 12px — identical, therefore undifferentiated |
| Chart clutter | Shrink labels to cram more in | Keep 12px, let density itself read as clutter |
| Illegible data labels | Actually illegible | 12px labels overlapping or colliding |
Type hierarchy
| Role | Style | Notes |
|---|
| Figure title | 18px / 700 / #1f2937 / centered / y≈22-28 | 16px for very tall figures |
| Subtitle | 12px italic / #6b7280 / centered / y≈40-48 | One-line takeaway |
| Source note | 9px / #6b7280 / centered / y≈64 | Only when synthetic dataset needs attribution. Requires data-print-role="micro" |
| Panel title | 13px / 700 / #1f2937 / left / x+12 / y+22 | |
| Panel subtitle | 12px italic / #6b7280 / left | |
| Body / data | 12px / #1f2937 (data) or #6b7280 (axis) | 12px is the instructional minimum |
| Axis tick labels | 12px / #6b7280 | If ticks crowd at 12px, reduce tick COUNT or abbreviate values. Never shrink below 12px |
| KPI number | 14px / 700 / #1e40af inside white card | |
| Category label | 12px / 700 / colored to match family accent | e.g., COMPARISON in #1d4ed8 |
data-print-role markers (how to mark below-floor text safely)
Two roles below the 5.8pt instructional floor:
data-print-role="micro" — attribution, provenance, hash stamps, source notes. Reader never needs to read at size.data-print-role="note" — annotation text the reader IS meant to read, but below body copy. Auto-promoted from micro when the text is ≥40 characters.
Both share the 2.9pt floor. The taxonomy exists because a coverage scanner otherwise cannot distinguish "this is a hash stamp" from "this is a caption the reader is expected to read."
Tailwind-grounded semantic palette
Color carries meaning — pick from this palette rather than introducing new hues. Consistency across chapters is the reader's cross-reference tool.
Relationship to the constellation brand palette. These are the print variants of the Alex ACT semantic role coding — darker Tailwind values (gray-800, blue-800, amber-700) tuned for high-contrast on white paper. The screen variants (ddf4ff pastels for mermaid classDefs, banner emerald #10b981) live in .github/config/brand-palette.json in Alex_ACT_Core. Same semantic roles across both variants (Input / Output / Processing / Decision / Error / Neutral); different lightness for the target surface.
Grays (neutral scaffolding)
| Hex | Tailwind | Use |
|---|
#1f2937 | gray-800 | Headlines, panel titles, primary text |
#374151 | gray-700 | Table headers, secondary text |
#6b7280 | gray-500 | Subtitles, axis labels, muted data, source notes |
#9ca3af | gray-400 | Axis lines, thin separators |
#d1d5db | gray-300 | Panel borders, dividers |
#f3f4f6 | gray-100 | BEFORE panel background (slightly deeper) |
#f9fafb | gray-50 | Default panel background |
#ffffff | white | Card backgrounds inside panels |
#cbd5e1 | slate-300 | De-emphasised bars (compare-with-selected pattern) |
Discipline blues (correct / principled / primary data)
| Hex | Tailwind | Use |
|---|
#1e40af | blue-800 | Primary data, headline KPI, emphasised element |
#1d4ed8 | blue-700 | Category label + emphasis (family names, section headers) |
#2563eb / #3b82f6 / #60a5fa / #93c5fd / #dbeafe | blue-600 → 100 | Sequential gradient (5-tone) for ordered categories |
#eff6ff | blue-50 | Category background (Comparison / principled sections) |
Semantic accents (used sparingly, one per role)
| Hex | Tailwind | Role(s) |
|---|
#b91c1c | red-700 | Critique callouts (numbered circles), REJECTED badge, target / reference lines |
#fee2e2 | red-100 | Rejection-callout background box |
#15803d | green-700 | APPROVED badge (paired with red rejection) |
#7c2d12 | orange-900 ("burgundy") | Additional dark accent for a second critique tone |
#b45309 | amber-700 | (a) Composition chart family label; (b) footer-takeaway strip color at bottom of many figures |
#d97706 / #f59e0b / #fbbf24 | amber-600 → 400 | Composition-family data gradient |
#fef3c7 | amber-50 ("warning yellow") | (a) Composition-family background; (b) warning / caution callout box background |
Semantic discipline
Color carries meaning; role depends on figure context.
- Blue family = correct / principled / primary emphasis
- Red = rejection / critique / must-fix / target-line (never decorative)
- Green = approval / correction shipped
- Amber = triple-duty. Composition chart family in an abstract Chart-family figure; warning callout in any chapter; footer-takeaway strip at the bottom of many figures. Surrounding context disambiguates.
- Burgundy = additional dark accent when a second critique tone is needed
- Grays = defaults, muted, neutral scaffolding
Composition idioms
Four structural idioms that recur across chapters. Each has a fixed shape.
1. BEFORE/AFTER paired panels
Used to show a correction, a decluttering, or a rework. The AFTER panel earns the argument; the BEFORE panel sets the failure state.
- Side-by-side, BEFORE left, AFTER right
- Each panel: same width and height,
stroke="#d1d5db" (gray-300) border, rounded rx="4"
- BEFORE panel background:
#f3f4f6 (gray-100)
- AFTER panel background:
#f9fafb (gray-50) or #eff6ff (blue-50)
- Top-right of BEFORE:
<rect fill="#b91c1c" rx="3"> 80×20 with white "REJECTED" text 12pt/700
- Top-right of AFTER:
<rect fill="#15803d" rx="3"> same shape with white "APPROVED" text
- Panel title 13pt/700 + italic subtitle 12pt underneath
Skeleton:
<rect x="20" y="60" width="290" height="380" fill="#f3f4f6" stroke="#d1d5db" rx="4"/>
<rect x="230" y="68" width="80" height="20" fill="#b91c1c" rx="3"/>
<text x="270" y="83" text-anchor="middle" fill="#ffffff" font-size="12" font-weight="700">REJECTED</text>
<text x="32" y="90" font-size="13" font-weight="700" fill="#1f2937">Before</text>
<text = = = = =>what the reader is asked to diagnose
APPROVED
After
how the argument reads once the fixes land
2. Numbered critique callouts
Used to walk the reader through a sequence of defects in a single flawed artifact. Each number matches a paragraph in the chapter body.
- Red-700 circle radius 10, top-right of each sub-panel or callout region
- White bold number 12pt/700 centered inside
- Sequential numbering 1, 2, 3, 4 matches the prose walkthrough
- Prose in the chapter body references the number, not the visual position
Skeleton:
<circle cx="580" cy="120" r="10" fill="#b91c1c"/>
<text x="580" y="124" text-anchor="middle" fill="#ffffff" font-size="12" font-weight="700">1</text>
Place the circle at the top-right of the region being called out. If two numbers land close together, prefer diagonal spacing (1 at top-right, 2 at bottom-left of the same region) over overlapping.
3. Family-band abstract figures
Used to compare 5 related concepts (chart families, decision moves, verification steps) side-by-side. Each band gets its own accent color matched to the family it represents.
- 5 vertical panels side-by-side, each ~115px wide
- Panel border: 1.5px in family accent color (blue-700, amber-700, purple-700, green-700, red-700)
- Panel background: matching 50-tone (blue-50, amber-50, purple-50, green-50, red-50)
- Category label at top: 12pt/700 in family accent
- Italic question quote: 12pt italic in gray-500 ("Which is larger?", "What share?")
- Canonical example chart at 60-80px tall
- Four label blocks below: "Default failure:", "Cousins:", "Use for:" — each 12pt/700 label then 12pt gray-500 body
Compact skeleton for one band:
<rect x="20" y="80" width="115" height="360" fill="#eff6ff" stroke="#1d4ed8" stroke-width="1.5" rx="4"/>
<text x="30" y="102" font-size="12" font-weight="700" fill="#1d4ed8">COMPARISON</text>
<text x="30" y="120" font-size="12" font-style="italic" fill="#6b7280">"Which is larger?"</text>
<text x="30" y="240" font-size="12" font-weight="700" fill="#1f2937">Default failure:</text>
< = = = =>...
4. 5-Visual Rule dashboards
Used for dashboard-shaped figures. From dashboard-design literature (Wexler / Shaffer / Cotgreave Big Book of Dashboards): 5 or fewer visuals per dashboard, with an obvious visual hierarchy.
- ≤5 visuals per dashboard
- One dominant KPI (largest single visual, top-left, blue-800 emphasis)
- Position → size → color hierarchy (readers scan top-left to bottom-right; big elements before small; bright before muted)
- Blurred-thumbnail test: shrink the figure to thumbnail size and apply Gaussian blur. The dominant KPI should still be identifiable. If the blur destroys the hierarchy, position or size is wrong.
- Mobile-preserved hierarchy: mentally re-flow the dashboard as a single column. The reading order should still make sense.
Anti-patterns
| Don't | Why |
|---|
| Introduce new hues outside the palette above | Consistency across chapters is the reader's cross-reference tool |
| Use red for anything except critique / rejection / target-line | Red carries the "must-fix" signal; decorative red would degrade the signal |
| Use amber outside Composition-family / warning / takeaway | Amber signals family membership or warning throughout; other uses confuse |
| Add drop-shadows, gradients, or decorative flourishes | Publication-appropriate = restraint; the argument does the work, not the graphics |
| Ship a figure without the italic subtitle | The subtitle carries the one-line takeaway that binds the figure to the argument |
| Substitute the font stack | Inter is intentional (open-source, wide numerals, ships on companion sites' CSS) |
| Shrink text below 12px to fit more in | The instructional floor exists for the reader; going below it fails them silently |
Use data-print-role="micro" on instructional content | The taxonomy is not an escape hatch; instructional means the reader has to read it |
| Ship an anti-pattern figure below the floor | The gate cannot distinguish deliberate from accidental illegibility |
| Skip the deuteranopia check on red/green pairings | Roughly 8% of male readers see them the same; color + shape or color + label survive |
Related skills
chart-big-idea — Step 0.5 earn-a-figure gate + Step 4.5 focus discipline. The framing side of the same discipline.flint-chart § Publication config preset — pins the Vega-Lite config block that emits statistical charts obeying this style guide.render-verify § Prose-coupling check — verifies the surrounding prose after the figure ships.figure-generator — the engineering discipline that emits SVGs conforming to this guide (.mjs generators, data-sha256 audit hash, contract tests).markdown-mermaid (Alex ACT Core) — sibling for Mermaid-authored diagrams (different rendering model, shares palette discipline where colors carry meaning).
Would revise if
The floor formula, palette, or composition idioms have failed if any of the following occur within 90 days:
- A figure shipped through this skill's discipline fails a print-legibility audit that this skill was supposed to prevent
- Adopters report the semantic-palette rules are ambiguous ≥3 times in a quarter (color role unclear)
- The
data-print-role="note" auto-promote rule (≥40 chars) misses a class of content it should catch
- The 5-Visual Rule dashboard blurred-thumbnail test is skipped ≥3 times because the tooling is too heavy
Track outcomes at operations/ledgers/curation-log.md in Alex_ACT_Steward.
Adapted from The Defensible Decision (Fabio Correa) via the dd-book-illustrator skill in Alex_DDA. The floor math, palette semantics, and composition idioms are book-tested across 53 shipped figures and 368 pages.
