design.md 17 KB
Design System
The aesthetic layer. Read this before touching any script. This file answers "what should it look like and why."
The one rule
Every design decision must be rooted in the document's content and purpose. Dark teal + cream is not "professional". Serif + beige is not "elegant". A color chosen because it fits the content will always outperform a color chosen because it seems safe.
Palette logic
palette.py takes a short content description and outputs tokens.json.
Here is the reasoning it applies:
Mood → base palette
| Content signal | Mood | Background | Accent | Text |
|---|---|---|---|---|
| Research, science, analysis | Authoritative | #0F1F2E deep ink |
#00B4A6 teal |
#F0EDE6 warm white |
| Business, strategy, finance | Confident | #1C1C2B near-black |
#E8A020 amber |
#F5F2EC cream |
| Creative, portfolio, design | Expressive | #1A0A2E deep violet |
#FF6B6B coral |
#FAF5FF lavender white |
| Education, academic paper | Scholarly | #FAFAF7 warm white |
#2C4A7C navy |
#1A1A2E dark |
| Healthcare, wellness | Calm | #F5F9F8 pale mint |
#2D8B72 forest |
#1E3830 deep green |
| Resume / personal | Clean | #FFFFFF white |
pick from content | #111111 near-black |
| General / unknown | Neutral | #F8F6F1 warm off-white |
#3D3D3D dark gray |
#1A1A1A black |
| Formal publications, annual reports | Magazine | #F2F0EC warm linen |
#1C3557 deep navy |
#0D1A2B near-black |
| Premium/dark reports, tech reviews | Darkroom | #151C27 deep navy |
#4A6FA5 steel blue |
#F0EDE6 warm white |
| Technical docs, developer reports | Terminal | #0D1117 near-black |
#39D353 neon green |
#E6EDF3 cool white |
| Portfolios, creative, photography | Poster | #FFFFFF white |
#0A0A0A near-black |
#0A0A0A near-black |
Accent selection rules
- One accent color only. Using two accents splits visual energy.
- Accent appears on: cover geometric elements, section rules, callout left borders, table header background, page header rule. Nowhere else.
- Accent must contrast with the cover background by at least 4.5:1 (WCAG AA).
- Do not default to blue. Blue is the most overused accent in AI-generated documents.
Color pairing anti-patterns (never use these)
| ❌ Avoid | Why |
|---|---|
| Purple gradient on white | The default AI aesthetic — immediately signals "generated" |
| Navy + gold | Overused corporate cliché |
| All-black background | Prints badly, feels aggressive |
| More than 3 colors in the system | Visual noise |
| Accent on body text | Destroys readability |
Typography system
Font pairing logic
Two typefaces maximum. Always.
| Role | Criteria | Good choices (system-safe) |
|---|---|---|
| Display (cover title, H1) | Distinctive, strong contrast, high weight | Times New Roman, Georgia (serif) |
| Text (body, captions, UI) | Highly readable at 10–11pt | Helvetica, Arial (sans) |
Cover fonts are loaded live via @import url(...) in the cover HTML — Playwright
fetches them at render time, no local caching. Body pages always use system fonts
(Times-Bold / Helvetica) via ReportLab — consistent and offline-safe.
Pairs by mood (cover HTML only — body always uses system fonts):
- Authoritative:
Playfair Display/IBM Plex Sans - Confident:
Syne/Nunito Sans - Expressive:
Fraunces/Inter - Scholarly:
EB Garamond/Source Sans 3 - Clean:
DM Serif Display/DM Sans - Restrained:
Cormorant Garamond/Jost - Bold:
Barlow Condensed/Barlow - Dynamic:
Montserrat/Montserrat - Classical:
Cormorant/Crimson Pro - Editorial:
Bebas Neue/Libre Franklin - Body fallback (always):
Times-Bold/Helvetica(ReportLab system fonts)
Type scale
All sizes in points. This scale is used by palette.py to populate tokens.json.
| Token | Size | Leading | Usage |
|---|---|---|---|
display |
54pt | 1.0 | Cover title |
h1 |
22pt | 1.3 | Section headings |
h2 |
15pt | 1.4 | Subsection headings |
h3 |
11.5pt | 1.5 | Sub-subsection |
body |
10.5pt | 1.6 | Main prose |
caption |
8.5pt | 1.4 | Figure/table captions |
meta |
8pt | 1.3 | Header/footer text |
Spacing system
Margins and rhythm are what separate "looks designed" from "looks printed".
| Token | Value | Notes |
|---|---|---|
margin_outer |
2.8cm | Left/right page margin |
margin_top |
2.8cm | Top page margin |
margin_bottom |
2.5cm | Bottom page margin |
section_gap |
26pt | Space before H1 |
para_gap |
8pt | Space after paragraph |
line_gap |
17pt | Leading for body text |
Never use ReportLab's default margins (too tight). Always set explicitly.
Cover design
The cover is the most important page. It determines whether a reader trusts the document.
Thirteen cover patterns
cover.py selects one based on tokens.json["cover_pattern"].
1. fullbleed — used for: report, general
- Deep background fills 100% of page
- Title: large, left-aligned, upper 60% of page
- Accent: thin horizontal rule + top-right corner strip
- Dot-grid background texture (subtle, 8–10% opacity)
- Footer band: author + date metadata
- Fonts: Playfair Display / IBM Plex Sans
2. split — used for: proposal
- Left 42% panel: solid cover color, title + author
- Right 58%: off-white, dot-grid decoration
- Hard vertical dividing line in accent color
- No gradients — pure flat geometry
- Fonts: Syne / Nunito Sans
3. typographic — used for: resume, academic
- White/off-white background
- Name or title as oversized display type (60–80pt), left-aligned
- First word in accent color, remainder in dark
- Thin rule below title block
- Fonts: DM Serif Display / DM Sans (resume) · EB Garamond / Source Sans 3 (academic)
4. atmospheric — used for: portfolio
- Near-black background
- Soft radial glow in accent color (upper-right quadrant)
- Title centered-left, 2 lines max
- Short rule in accent below title
- Dot-grid texture at low opacity
- Fonts: Fraunces / Inter
5. minimal — used for: minimal
- Near-white background, 8px left accent bar is the only color
- Title in very large, light-weight display type (300 weight)
- Hairline rule, author + date as single muted line
- Nothing else — the bar does all the visual work
- Fonts: Cormorant Garamond / Jost
6. stripe — used for: stripe
- Page cut into three horizontal bands: accent / dark / light
- Top band: category label; middle: oversized title in white; bottom: metadata
- Hard edges, no gradients, no textures — newspaper / brand poster aesthetic
- Fonts: Barlow Condensed / Barlow
7. diagonal — used for: diagonal
- SVG polygon cuts page diagonally: dark upper-left, light lower-right
- Accent-colored edge line traces the diagonal cut
- Title on dark area, metadata on light area
- Fonts: Montserrat / Montserrat
8. frame — used for: frame
- White/cream background with an inset rectangular border (1.2px, 28px from edges)
- Accent strips inside top + bottom of frame; small accent corner squares
- Title centered in the frame space, centered alignment, classical weight
- Formal, timeless — annual reports, legal documents, academic papers
- Fonts: Cormorant / Crimson Pro
9. editorial — used for: editorial
- Ghost first-letter of title fills upper-right at 5% opacity — visual texture
- 5px accent top bar; full-width uppercase title in condensed weight
- Title all-caps, very large (80px), flush-left
- Footer rule + author/date metadata
- Fonts: Bebas Neue / Libre Franklin
10. magazine — used for: magazine
- Warm cream/linen background; fully centered, vertical stack layout
- Org/company name in small spaced caps + 2px accent rule beneath (top anchor)
- Large bold serif title (52px) centered; short accent rule under title
- Italic subtitle; optional
cover_imageURL renders as centered hero thumbnail - Optional
abstractfield: justified text block with bold "Abstract:" label - Author name in accent color (large, bold); date beneath
- Fonts: Playfair Display / EB Garamond
11. darkroom — used for: darkroom
- Same centered stack layout as
magazinebut deep navy background, white text - Org name + rules in semi-transparent white; accent rules desaturated
- Hero image (if provided) gets
grayscale(20%) brightness(0.9)filter - Fonts: Playfair Display / EB Garamond
12. terminal — used for: terminal
- Near-black background; neon green accent; Space Mono monospace throughout
- Grid overlay: faint horizontal + vertical lines at 48px intervals (7% opacity)
- Status label top-left: green dot +
SYSTEM_REPORT // <date> - Title inside a bracket frame (border-left + border-top + pseudo-element corner)
- Subtitle prefixed with
>in accent color - Abstract text left; author block right; status bar at bottom (UTF-8 / Ln 1)
- Fonts: Space Mono / Space Mono
13. poster — used for: poster
- White background; thick 52px left sidebar in accent (typically near-black)
- Title: 96px, 900-weight, all-caps, condensed — the dominant visual element
- Subtitle in typewriter font below title; thin 2px rule as separator
- Author + meta in Courier Prime monospace beneath rule
- Optional
cover_imagerendered as 260×340 grayscale thumbnail, right-aligned - Accent square icon block (lower-right) with white horizontal lines
- Fonts: Barlow Condensed / Courier Prime
Optional token: cover_image
Patterns magazine, darkroom, and poster accept an optional cover_image
token containing an absolute URL or file:// path to an image.
The image renders via <img src="..."> — Playwright fetches it at render time.
If omitted, the image area is simply skipped (layout adjusts gracefully).
Cover CSS requirements (critical for Playwright rendering)
These three rules must appear in every cover HTML file or the output will have white borders / incorrect dimensions:
body { margin: 0; padding: 0; }
html, body { width: 794px; height: 1123px; overflow: hidden; }
No @page rules needed — Playwright handles page size via the pdf() call.
Do NOT use CSS background-image for textures — use inline SVG or <canvas>.
Always use position: absolute + z-index for layered elements.
What always kills a cover
- Centered title on white background with a thin horizontal line underneath
- Gradient from one color to another (reads as PowerPoint, not print design)
- Drop shadows on text
- More than one accent color
- Emoji or icon fonts (fail silently on headless Chromium)
Inner page rules
What "restraint" means in practice
Every design decision should remove something, not add something. The page is done when there is nothing left to remove.
- Accent color appears on section rules only — not on headings, not on bullets
- No card components (bordered boxes with colored headers)
- No rounded corners on anything except callout boxes (4px max)
- No shadows anywhere
- Tables: header row in accent, alternating row tint, no grid lines except outer box
- Callout boxes: left border in accent (4px), very light tint background, no icon
Page header / footer
Header: document title (left, 7.5pt, muted) + accent rule (1.5pt, full width below) Footer: author name (left, 7.5pt, muted) + page number (right, 7.5pt, muted) + light rule above
Quality bar
A PDF passes if a designer would not be embarrassed to hand it to a client. Concretely:
- Cover has a clear visual identity that is not "generic AI output"
- Body text is readable at arm's length without squinting
- Every page looks like it belongs to the same document
- No element bleeds off the edge or overlaps another
- Page numbers are present and correct
- The accent color appears fewer than 8 times per page on average
Block type reference
All body blocks use the same token system — colors and fonts come from tokens.json, never hardcoded.
| Block | Rendering | Design notes |
|---|---|---|
h1 |
22pt heading + full-width accent rule below | KeepTogether with rule — heading never orphaned |
h2 |
15pt heading, dark text | No rule, no accent — visual hierarchy through size only |
h3 |
11.5pt bold, dark text | No accent color — accent on body headings violates the one-accent-location rule |
body |
10.5pt justified, 17pt leading | Supports <b> <i> <font> markup |
bullet |
Body size with • prefix, 14pt indent |
Use for unordered lists |
numbered |
Body size with N. prefix, hanging indent |
Counter auto-resets on any non-numbered block — no manual numbering needed |
callout |
Accent left-border (4px) + light tint background | Max one callout per section — overuse kills impact |
table |
Accent header row, alternating row tint, outer box only | Supports col_widths (fractions, e.g. [0.3, 0.5, 0.2]) for custom column widths |
image |
Scaled to column width, preserving aspect ratio | Use path or src; always provide a caption |
figure |
Same as image, but caption auto-prefixed "Figure N:" | Figure counter increments across all figure, chart, flowchart blocks |
code |
Courier 8.5pt, accent left-border, light tint background | Supports optional language label (rendered above block) |
math |
Formula centered, optional right-aligned equation label | LaTeX syntax; matplotlib mathtext renderer |
chart |
Bar / line / pie chart rendered via matplotlib | Color palette derived from document accent; figure auto-numbered |
flowchart |
Process diagram with labeled arrows | Supports 4 node shapes; back-edges drawn as curved arcs |
bibliography |
Numbered reference list with hanging indent | Heading rendered as h2 + accent rule; items as [N] text |
divider |
Accent-colored 1.2pt rule with padding | Use sparingly — only for major thematic breaks |
caption |
8.5pt muted text, centered | Appears below images/tables via field or explicit block |
pagebreak |
Force page break | — |
spacer |
Vertical whitespace | pt field (default 12) |
Math formula guidance
Input syntax: standard LaTeX math notation — \frac{}{}, \int, \sum, \alpha, ^, _, etc.
Rendering engine: matplotlib mathtext — pure Python, no LaTeX compiler, no browser required.
| Syntax example | Rendered as |
|---|---|
E = mc^2 |
Inline expression |
\frac{\sqrt{\pi}}{2} |
Fraction |
\int_0^\infty e^{-x^2} dx |
Integral |
\sum_{i=1}^{n} x_i |
Summation |
\alpha + \beta = \gamma |
Greek letters |
Limitations: matplotlib mathtext covers most common expressions but not advanced LaTeX environments (align, cases, matrix). Split complex multi-line proofs into multiple math blocks.
Fallback: if matplotlib is not installed, renders as expression in code style. Run make.sh fix to install.
Equation labels: "label": "(1)" — rendered right-aligned beside the formula.
Chart guidance
Rendered entirely in Python — no external chart services, image files, or internet required.
| chart_type | Use case | Required fields |
|---|---|---|
bar |
Comparing discrete categories | labels, datasets |
line |
Trends over time or ordered categories | labels, datasets |
pie |
Part-to-whole composition | labels, datasets[0].values |
- Colors are derived from the document accent for visual consistency — do not set custom colors.
- Multi-series: add multiple objects to
datasets, each with alabelandvaluesarray. - Figure auto-numbering: set
"figure": true(default) or"figure": falseto suppress.
Flowchart guidance
Node shapes:
| shape | Use for |
|---|---|
rect (default) |
Process step |
diamond |
Decision / condition |
oval or terminal |
Start / End |
parallelogram |
Input / Output |
- Nodes are placed in input order (top to bottom). This controls the layout.
- Forward edges draw straight arrows; back-edges (to earlier nodes) draw curved arcs.
- Keep labels short (3–5 words max) — the diagram is A4-column-width at 78% scale.
- Figure auto-numbering applies same as chart.
Bibliography guidance
idfield is the reference label — use numbers ("1", "2") or alphanumeric ("Smith23").- Text should be in a consistent citation style (APA, Chicago, etc.) — the renderer does not enforce style.
- The
titlefield defaults to "References". Set"title": ""to suppress the heading. - A
bibliographyblock always starts with a new section heading + accent rule.
Image / figure guidance
- Preferred formats: PNG, JPEG
- Scaled down if wider than the text column; never scaled up
figureblocks auto-number;imageblocks do not — usefigurefor numbered figures- If the file does not exist at render time, a
[Image not found]placeholder is substituted
Code block guidance
- Preserves whitespace exactly — do not indent code in the JSON value
- Optional
languagefield renders a small language label above the block (e.g.,"language": "python") - No syntax highlighting (by design) — consistent with restraint principle
- Keep lines under ~90 characters for A4 column width