@nexus-cortex/server 4.26.0

package/.cortex/skills/pdf-documents/sections/04-design-system.md

@@ -0,0 +1,549 @@
+# Design System for Print (Frontend Design Adapted for PDF)
+
+This section adapts frontend design principles to print documents. The same skills that make a web interface distinctive and polished make a PDF document visually compelling. A research report should look as intentionally designed as a landing page. **Generic AI document aesthetics are just as unacceptable as generic AI web aesthetics.**
+
+## Design Thinking — Before Writing ANY HTML
+
+Before coding the document, commit to a bold aesthetic direction:
+
+1. **Purpose**: What is this document? Who reads it?
+2. **Tone**: Pick a clear direction — not "clean and professional" (that's the default, which means no design):
+   - **Editorial / Magazine** — large pull quotes, asymmetric columns, dramatic white space, serif display fonts
+   - **Technical / Engineering** — monospace headings, tight grid, minimal color, high information density
+   - **Luxury / Refined** — generous margins, thin rules, restrained palette (2 colors max), elegant serif
+   - **Bold / Activist** — oversized type, high-contrast colors, full-bleed images, condensed sans-serif
+   - **Academic / Scholarly** — two-column body, footnotes, running headers, traditional serif (Garamond, Caslon)
+   - **Corporate / Clean** — sans-serif, brand colors, sidebar callouts, consistent iconography
+   - **Vintage / Archival** — aged paper tones, decorative borders, ornamental capitals, old-style figures
+   - **Data-Dense / Dashboard** — small type, many tables/charts, color-coded sections, maximum content per page
+3. **Differentiation**: What makes this document visually memorable? Commit to ONE signature element.
+4. **Constraints**: Paper size, print vs. screen-only, color vs. grayscale, binding margin.
+
+**CRITICAL**: The design direction drives EVERY subsequent CSS decision. Don't bolt on aesthetics after writing content — design first, then fill.
+
+---
+
+## Typography System
+
+**NEVER use**: Arial, Inter, Roboto, Calibri, system-ui as the primary font. These are non-decisions. If the document could have been generated by any default template, the typography has failed.
+
+### Font Classification Guide
+
+**Serif** — strokes have finishing "feet." Best for: body text in long-form print.
+
+| Font | Character | Print Size Sweet Spot | Weight Range | Free? |
+|------|-----------|----------------------|-------------|-------|
+| **EB Garamond** | Classical, scholarly, timeless | 10-12pt body | 400-800 | Yes (Google) |
+| **Source Serif Pro** | Modern serif, clean, versatile | 10-12pt body | 200-900 | Yes (Google) |
+| **Playfair Display** | High contrast, dramatic, editorial | 18pt+ display ONLY | 400-900 | Yes (Google) |
+| **Crimson Pro** | Warm, humanist, book-like | 10-12pt body | 200-900 | Yes (Google) |
+| **Libre Baskerville** | British classical, authoritative | 10-14pt body + display | 400-700 | Yes (Google) |
+| **Cormorant Garamond** | Elegant, high contrast, luxury | 14pt+ display preferred | 300-700 | Yes (Google) |
+| **Merriweather** | Screen-optimised but prints well, wide | 10-12pt body | 300-900 | Yes (Google) |
+| **Lora** | Contemporary, calligraphic roots | 10-12pt body | 400-700 | Yes (Google) |
+| **Spectral** | Designed for screen AND print, large x-height | 9-11pt body | 200-800 | Yes (Google) |
+
+**Sans-Serif** — no finishing strokes. Best for: headings, captions, technical content.
+
+| Font | Character | Print Size Sweet Spot | Weight Range | Free? |
+|------|-----------|----------------------|-------------|-------|
+| **IBM Plex Sans** | Technical, structured, IBM heritage | 9-11pt body, 16pt+ heading | 100-700 | Yes (Google) |
+| **Nunito Sans** | Friendly, rounded, approachable | 10-12pt body | 200-900 | Yes (Google) |
+| **Montserrat** | Geometric, strong, urban | 16pt+ heading preferred | 100-900 | Yes (Google) |
+| **Oswald** | Condensed, bold, impactful | 20pt+ heading ONLY | 200-700 | Yes (Google) |
+| **Barlow** | Slightly condensed, efficient, modern | 9-11pt body | 100-900 | Yes (Google) |
+| **DM Sans** | Geometric, contemporary, clean | 10-12pt body | 100-1000 | Yes (Google) |
+| **Outfit** | Modern geometric, wide weight range | 14pt+ heading, 10pt body | 100-900 | Yes (Google) |
+| **Manrope** | Semi-rounded, tech-forward | 10-12pt body | 200-800 | Yes (Google) |
+
+**Monospace** — fixed-width. Best for: code, data, technical specifications.
+
+| Font | Character | Print Size Sweet Spot | Free? |
+|------|-----------|----------------------|-------|
+| **JetBrains Mono** | Modern, coding-optimised, ligatures | 8-10pt code, 16pt+ heading | Yes (Google) |
+| **Space Mono** | Retro-futuristic, editorial | 8-10pt code, 14pt+ heading | Yes (Google) |
+| **IBM Plex Mono** | Neutral, technical, wide | 8-10pt code/tables | Yes (Google) |
+| **Fira Code** | Ligatures, developer-favourite | 8-10pt code | Yes (Google) |
+| **Source Code Pro** | Adobe, clean, readable | 8-10pt code | Yes (Google) |
+
+**Display / Decorative** — titles and hero text ONLY. Never body text.
+
+| Font | Character | Use At | Free? |
+|------|-----------|--------|-------|
+| **Abril Fatface** | Ultra-bold serif, poster style | 28pt+ titles only | Yes (Google) |
+| **Bebas Neue** | All-caps, condensed, loud | 24pt+ titles only | Yes (Google) |
+| **Righteous** | Retro, rounded, playful | 20pt+ titles only | Yes (Google) |
+| **Archivo Black** | Heavy grotesque, powerful | 20pt+ titles only | Yes (Google) |
+| **Yeseva One** | Decorative serif, ornamental | 28pt+ titles only | Yes (Google) |
+
+### Font Selection Decision Framework
+
+```
+STEP 1: What is the document's reading context?
+  Long-form reading (>5 pages)     → Serif body (EB Garamond, Source Serif Pro, Crimson Pro)
+  Short-form / scannable (1-3 pg)  → Sans-serif body (IBM Plex Sans, Barlow, DM Sans)
+  Technical / data-heavy           → Sans-serif + monospace for data
+  Code documentation               → Monospace body, sans-serif headings
+
+STEP 2: What tone?
+  Authority / tradition   → classical serifs (Garamond, Baskerville)
+  Innovation / tech       → geometric sans (Montserrat, DM Sans)
+  Warmth / approachability → humanist sans (Nunito Sans) or soft serif (Lora)
+  Urgency / impact        → condensed sans (Oswald, Barlow Condensed)
+  Elegance / luxury       → high-contrast serif (Cormorant Garamond, Playfair Display)
+
+STEP 3: Pair display + body
+  RULE: Maximum contrast between display and body font.
+  - Serif display + sans-serif body (classic editorial)
+  - Sans-serif display + serif body (modern contrast)
+  - Heavy weight display + light weight body (same family OK)
+  NEVER: Two decorative fonts. Two very similar sans-serifs. Same weight for both.
+
+STEP 4: Verify at target print size
+  - Body readable at 10-11pt in a full paragraph?
+  - Headings have enough visual weight?
+  - Captions legible at 8-9pt?
+  - Numbers align in columns? (use tabular-nums)
+```
+
+### Font Weight Usage Guide
+
+```css
+:root {
+  --weight-light: 300;       /* large display text, pull quotes */
+  --weight-regular: 400;     /* body text, default */
+  --weight-medium: 500;      /* subtitles, navigation, table headers */
+  --weight-semibold: 600;    /* h3, emphasis, sidebar headings */
+  --weight-bold: 700;        /* h1, h2, strong emphasis */
+  --weight-heavy: 800;       /* cover title, hero text */
+  --weight-black: 900;       /* poster titles, decorative ONLY */
+}
+/* PRINT RULE: avoid 100-200 weights at body size (too thin to print cleanly) */
+/* PRINT RULE: avoid 900 weight below 20pt (fills in at small sizes) */
+/* PRINT RULE: use 400-600 range for body text — most readable */
+```
+
+### Line Height and Letter Spacing for Print
+
+```css
+/* Line height (print-optimised — wider than screen) */
+body { line-height: 1.55-1.7; }
+h1   { line-height: 1.1-1.2; }
+h2   { line-height: 1.2-1.3; }
+caption, figcaption { line-height: 1.4; }
+table td { line-height: 1.3; }
+blockquote { line-height: 1.6-1.8; }
+
+/* Letter spacing */
+body { letter-spacing: normal; }                 /* NEVER touch body */
+h1   { letter-spacing: -0.02em; }               /* large text: tighten */
+.all-caps { letter-spacing: 0.12em; text-transform: uppercase; } /* caps MUST be tracked */
+table th { letter-spacing: 0.03em; }
+/* NEVER: letter-space body text. It destroys word shapes. */
+/* ALWAYS: letter-space ALL CAPS text. Caps without tracking looks cramped. */
+```
+
+### Print-Optimised Font Pairing Patterns
+
+| Direction | Display Font | Body Font | Why It Works |
+|-----------|-------------|-----------|-------------|
+| Editorial | Playfair Display | Source Serif Pro | High contrast display + readable body |
+| Technical | JetBrains Mono | IBM Plex Sans | Monospace authority + clean body |
+| Luxury | Cormorant Garamond | Lato Light | Elegant + readable light weight |
+| Bold | Oswald | Nunito Sans | Condensed impact + friendly body |
+| Academic | EB Garamond | EB Garamond | Single family, weight contrast |
+| Corporate | Montserrat | Open Sans | Geometric headers + neutral body |
+| Vintage | Libre Baskerville | Crimson Pro | Period-appropriate pairing |
+| Data-Dense | Space Mono | Inter Tight | Tabular monospace + compact body |
+| Government | Libre Baskerville | Spectral | Authoritative + high legibility |
+| Medical | DM Sans | Source Serif Pro | Clean modern + readable long-form |
+| Creative | Abril Fatface | Barlow | Ultra-bold impact + efficient body |
+| Financial | Montserrat | IBM Plex Sans + IBM Plex Mono | Geometric + tabular data |
+
+### Font Libraries and Sources
+
+| Library | Fonts Available | License | How to Use |
+|---------|----------------|---------|------------|
+| **Google Fonts** | 1,700+ families | Open source (SIL OFL / Apache) | `@import url('https://fonts.googleapis.com/css2?family=...')` |
+| **Adobe Fonts** | 25,000+ families | Creative Cloud subscription | Web font embed code |
+| **Font Squirrel** | 1,000+ families | 100% free commercial | Download .woff2, self-host |
+| **Fontsource** | 1,700+ (mirrors Google) | Open source | `npm install @fontsource/font-name` |
+| **Bunny Fonts** | 1,400+ (Google mirror) | Privacy-first, GDPR-safe | `fonts.bunny.net/css?family=...` |
+| **The League of Moveable Type** | ~20 curated | Open source | Download, high quality |
+| **Velvetyne Type Foundry** | 40+ display | Libre / open source | Download, highly creative |
+| **UNCUT.wtf** | 150+ curated | Various open | Download, curated quality |
+
+**Platform fonts:**
+
+| Platform | Notable Families |
+|----------|-----------------|
+| **macOS / iOS** | San Francisco, New York, SF Mono, Helvetica Neue, Avenir, Futura, Gill Sans, Garamond, Baskerville, Optima |
+| **Windows** | Segoe UI, Cambria, Calibri, Consolas, Georgia, Palatino Linotype, Book Antiqua, Century |
+| **Linux** | DejaVu, Liberation (metric-compatible), Noto (100+ languages), Ubuntu, Cantarell |
+
+**Apple font → open alternative mapping:**
+
+| Apple Font | Open Alternative |
+|-----------|-----------------|
+| San Francisco | **Inter** or **DM Sans** |
+| New York | **Source Serif Pro** |
+| SF Mono | **JetBrains Mono** |
+| Helvetica Neue | **Inter** or **Noto Sans** |
+| Avenir | **Nunito Sans** or **Outfit** |
+| Futura | **Jost** |
+| Didot | **Playfair Display** |
+
+**Loading fonts for PDF generation:**
+```html
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700;900&family=Source+Serif+Pro:wght@400;600&display=swap');
+</style>
+<!-- IMPORTANT: only load weights you actually use -->
+
+<!-- Offline: download .woff2 and self-host -->
+<style>
+  @font-face {
+    font-family: 'EB Garamond';
+    src: url('./fonts/EBGaramond-Regular.woff2') format('woff2');
+    font-weight: 400; font-style: normal; font-display: swap;
+  }
+</style>
+```
+
+### Type Scale for Print (Modular Scale — 1.25 ratio)
+
+```css
+:root {
+  --type-xs: 8pt;      /* footnotes, fine print */
+  --type-sm: 9pt;      /* captions, table cells */
+  --type-base: 11pt;   /* body text — MINIMUM for comfortable reading */
+  --type-md: 13pt;     /* h4, lead paragraphs */
+  --type-lg: 16pt;     /* h3 */
+  --type-xl: 20pt;     /* h2 */
+  --type-2xl: 26pt;    /* h1 */
+  --type-3xl: 32pt;    /* cover title */
+  --type-hero: 48pt;   /* poster / banner hero */
+}
+
+body      { font-size: var(--type-base); line-height: 1.65; }
+h1        { font-size: var(--type-2xl);  line-height: 1.15; letter-spacing: -0.02em; }
+h2        { font-size: var(--type-xl);   line-height: 1.25; letter-spacing: -0.01em; }
+h3        { font-size: var(--type-lg);   line-height: 1.3; }
+figcaption{ font-size: var(--type-sm);   line-height: 1.4; }
+.footnote { font-size: var(--type-xs);   line-height: 1.4; }
+```
+
+### Modern CSS Typography Features for Print
+
+```css
+h1, h2, h3 { text-wrap: balance; }    /* no awkward single-word last lines */
+p { text-wrap: pretty; }               /* prettier paragraph wrapping */
+body { font-optical-sizing: auto; }    /* variable font optical sizing */
+table { font-variant-numeric: tabular-nums; } /* aligned number columns */
+.prose { font-variant-numeric: oldstyle-nums; } /* traditional figures for body */
+p.justified {
+  text-align: justify; hyphens: auto;
+  hyphenate-limit-chars: 6 3 2;
+}
+body { font-kerning: normal; }
+```
+
+---
+
+## Color System
+
+### The OKLCH Hue Wheel (degrees)
+
+```
+      0° / 360° = Red       90° = Yellow-Green    180° = Cyan       270° = Blue-Violet
+     30° = Orange          120° = Green           210° = Sky Blue    300° = Purple
+     60° = Yellow          150° = Teal            250° = Blue        330° = Pink
+```
+
+### Color Harmony Strategies
+
+**Monochromatic** — one hue, vary lightness and chroma. Safest, most cohesive. For: professional reports, legal documents.
+```css
+:root {
+  --color-dark:  oklch(0.25 0.08 250);   /* headings */
+  --color-mid:   oklch(0.45 0.12 250);   /* accents */
+  --color-light: oklch(0.85 0.04 250);   /* backgrounds */
+  --color-pale:  oklch(0.95 0.02 250);   /* table stripes */
+}
+```
+
+**Complementary** — two hues 180° apart. Maximum contrast. For: bold reports, marketing.
+```css
+:root {
+  --color-primary: oklch(0.30 0.10 250);   /* navy */
+  --color-accent:  oklch(0.60 0.18 30);    /* warm orange */
+}
+/* RULE: dominant at 80%+ area, accent at <20%. */
+```
+
+**Split-Complementary** — one hue + two flanking its complement (±30°). For: editorial, branded reports.
+```css
+:root {
+  --color-primary:  oklch(0.30 0.10 250);
+  --color-accent-1: oklch(0.55 0.18 15);
+  --color-accent-2: oklch(0.60 0.15 45);
+}
+```
+
+**Analogous** — 2-3 hues within 60°. Harmonious, calm. For: nature, wellness, understated.
+```css
+:root {
+  --color-primary: oklch(0.35 0.10 210);
+  --color-mid:     oklch(0.45 0.12 180);
+  --color-accent:  oklch(0.50 0.14 150);
+}
+```
+
+**Triadic** — three hues 120° apart. Vibrant. For: infographics, data viz.
+```css
+:root {
+  --color-1: oklch(0.50 0.12 10);
+  --color-2: oklch(0.50 0.12 130);
+  --color-3: oklch(0.50 0.12 250);
+}
+/* Keep chroma low (0.08-0.15) for print triads. */
+```
+
+**Neutral + Single Accent** — grayscale + one color. Most sophisticated. For: luxury, executive summaries.
+```css
+:root {
+  --color-text:    oklch(0.20 0.01 0);
+  --color-muted:   oklch(0.50 0.01 0);
+  --color-surface: oklch(0.97 0.005 0);
+  --color-accent:  oklch(0.55 0.20 15);    /* ONE bold accent */
+}
+```
+
+### Accent Color by Subject
+
+| Subject | Recommended Hue | OKLCH Example |
+|---------|----------------|---------------|
+| Finance | Navy or Forest Green | `oklch(0.40 0.12 250)` or `oklch(0.40 0.12 145)` |
+| Medical | Teal or Calming Blue | `oklch(0.50 0.14 180)` |
+| Legal | Burgundy or Navy | `oklch(0.40 0.10 15)` |
+| Technology | Electric Blue or Violet | `oklch(0.55 0.18 260)` |
+| Environment | Green or Earth Tones | `oklch(0.45 0.14 140)` |
+| Education | Warm Blue or Amber | `oklch(0.45 0.12 230)` |
+| Creative | Magenta or Deep Purple | `oklch(0.50 0.18 320)` |
+| Maritime | Deep Navy or Sky Blue | `oklch(0.30 0.10 250)` |
+
+### OKLCH in CSS
+
+```css
+:root {
+  --color-primary: oklch(0.45 0.15 250);
+  --color-accent: oklch(0.55 0.20 15);
+  --color-neutral: oklch(0.20 0.02 250);
+
+  /* Derived variants */
+  --color-primary-light: color-mix(in oklch, var(--color-primary), white 70%);
+  --color-primary-muted: color-mix(in oklch, var(--color-primary), white 85%);
+  --color-accent-light: color-mix(in oklch, var(--color-accent), white 75%);
+
+  /* Print-safe grays */
+  --color-text: oklch(0.20 0.01 250);
+  --color-text-muted: oklch(0.45 0.01 250);
+  --color-border: oklch(0.80 0.01 250);
+  --color-surface: oklch(0.97 0.005 90);
+
+  /* Semantic mapping */
+  --color-heading: var(--color-primary);
+  --color-table-header: var(--color-primary);
+  --color-table-stripe: var(--color-primary-light);
+  --color-callout-border: var(--color-accent);
+}
+```
+
+**Chart palette (perceptually equidistant):**
+```css
+:root {
+  --chart-1: oklch(0.55 0.15 15);    /* red */
+  --chart-2: oklch(0.55 0.15 75);    /* yellow-green */
+  --chart-3: oklch(0.55 0.15 145);   /* teal */
+  --chart-4: oklch(0.55 0.15 210);   /* sky blue */
+  --chart-5: oklch(0.55 0.15 270);   /* violet */
+  --chart-6: oklch(0.55 0.15 330);   /* pink */
+}
+/* Holding L and C constant while rotating H gives equal visual weight — critical for fair data viz. */
+```
+
+### Print Color Palettes by Direction
+
+| Direction | Primary | Accent | Surface | Text |
+|-----------|---------|--------|---------|------|
+| Editorial | `oklch(0.25 0.05 250)` | `oklch(0.55 0.20 15)` | `oklch(0.98 0.005 90)` | `oklch(0.20 0.01 250)` |
+| Technical | `oklch(0.30 0.10 250)` | `oklch(0.60 0.15 145)` | `oklch(0.99 0 0)` | `oklch(0.15 0 0)` |
+| Luxury | `oklch(0.25 0.04 50)` | `oklch(0.65 0.12 80)` | `oklch(0.97 0.01 80)` | `oklch(0.25 0.02 50)` |
+| Bold | `oklch(0.15 0 0)` | `oklch(0.60 0.25 30)` | `oklch(0.99 0 0)` | `oklch(0.15 0 0)` |
+| Academic | `oklch(0.30 0.08 250)` | `oklch(0.45 0.10 30)` | `oklch(0.97 0.005 70)` | `oklch(0.20 0.01 0)` |
+| Vintage | `oklch(0.35 0.06 50)` | `oklch(0.50 0.12 30)` | `oklch(0.93 0.02 70)` | `oklch(0.30 0.04 50)` |
+
+---
+
+## Spacing System (4pt Base Unit)
+
+```css
+:root {
+  --space-1: 2pt;    --space-2: 4pt;    --space-3: 8pt;    --space-4: 12pt;
+  --space-5: 16pt;   --space-6: 24pt;   --space-7: 32pt;   --space-8: 48pt;
+  --space-9: 64pt;
+}
+p { margin-bottom: var(--space-3); }
+h2 { margin-top: var(--space-6); margin-bottom: var(--space-4); }
+h3 { margin-top: var(--space-5); margin-bottom: var(--space-3); }
+table { margin: var(--space-5) 0; }
+figure { margin: var(--space-5) 0; }
+blockquote { padding: var(--space-4) var(--space-5); }
+```
+
+---
+
+## Visual Texture and Atmosphere
+
+```css
+/* Textured cover (CSS gradients — no images) */
+.cover {
+  background:
+    radial-gradient(circle at 20% 80%, var(--color-primary-light) 0%, transparent 50%),
+    radial-gradient(circle at 80% 20%, var(--color-accent-light) 0%, transparent 40%),
+    var(--color-surface);
+}
+
+/* Decorative section rules */
+h2::after {
+  content: ''; display: block; width: 60px; height: 3px;
+  background: var(--color-accent); margin-top: var(--space-2); border-radius: 2px;
+}
+
+/* Pull quotes */
+.pull-quote {
+  font-size: var(--type-lg); font-style: italic;
+  border-left: 4px solid var(--color-accent); padding-left: var(--space-5);
+  margin: var(--space-6) 0; color: var(--color-primary);
+}
+
+/* Drop caps */
+.chapter-opening::first-letter {
+  float: left; font-size: 4em; line-height: 0.8; padding-right: 8pt;
+  font-weight: 700; color: var(--color-primary);
+}
+
+/* Sidebar callouts */
+.callout {
+  background: var(--color-sidebar-bg);
+  border-left: 4px solid var(--color-accent);
+  border-radius: 0 6px 6px 0;
+  padding: var(--space-4) var(--space-5); margin: var(--space-5) 0;
+}
+
+/* Styled tables */
+thead th {
+  background: var(--color-table-header); color: white;
+  padding: var(--space-3) var(--space-4); font-weight: 600;
+}
+tbody tr:nth-child(even) { background: var(--color-table-stripe); }
+```
+
+---
+
+## Layout Patterns
+
+```css
+/* Two-column with full-width headings */
+.content { column-count: 2; column-gap: 8mm; column-rule: 0.5pt solid var(--color-border); }
+.content h2 { column-span: all; }
+
+/* Sidebar layout */
+.section-with-sidebar {
+  display: grid; grid-template-columns: 2fr 1fr; gap: var(--space-5);
+}
+
+/* Full-bleed image */
+.full-bleed {
+  margin-left: calc(-1 * var(--page-margin));
+  margin-right: calc(-1 * var(--page-margin));
+  width: calc(100% + 2 * var(--page-margin));
+}
+
+/* Asymmetric editorial */
+.hero-section { display: grid; grid-template-columns: 1fr 2fr; gap: var(--space-6); align-items: center; }
+```
+
+---
+
+## Complete Starter Template
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>Document Title</title>
+<style>
+  @import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700;900&family=Source+Serif+Pro:wght@400;600&display=swap');
+
+  :root {
+    --font-display: 'Playfair Display', Georgia, serif;
+    --font-body: 'Source Serif Pro', Georgia, serif;
+    --font-mono: 'JetBrains Mono', 'Courier New', monospace;
+    --type-base: 11pt; --type-lg: 16pt; --type-xl: 20pt;
+    --type-2xl: 26pt; --type-hero: 42pt; --type-sm: 9pt; --type-xs: 8pt;
+    --color-primary: oklch(0.30 0.08 250);
+    --color-accent: oklch(0.55 0.20 15);
+    --color-text: oklch(0.20 0.01 250);
+    --color-text-muted: oklch(0.45 0.01 250);
+    --color-surface: oklch(0.97 0.005 90);
+    --color-border: oklch(0.80 0.01 250);
+    --color-primary-light: color-mix(in oklch, var(--color-primary), white 85%);
+    --sp-1: 2pt; --sp-2: 4pt; --sp-3: 8pt; --sp-4: 12pt;
+    --sp-5: 16pt; --sp-6: 24pt; --sp-7: 32pt; --sp-8: 48pt;
+    --page-margin: 20mm;
+  }
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: var(--font-body); font-size: var(--type-base);
+    color: var(--color-text); background: var(--color-surface);
+    line-height: 1.65; max-width: 800px; margin: 0 auto; padding: 40px 50px;
+  }
+  p { margin-bottom: var(--sp-3); text-align: justify; text-wrap: pretty; }
+  h1, h2, h3, h4 { font-family: var(--font-display); color: var(--color-primary); text-wrap: balance; }
+  h1 { font-size: var(--type-2xl); margin: var(--sp-7) 0 var(--sp-5); }
+  h2 { font-size: var(--type-xl); margin: var(--sp-6) 0 var(--sp-4);
+       border-bottom: 2px solid var(--color-accent); padding-bottom: var(--sp-2); }
+  table { width: 100%; border-collapse: collapse; margin: var(--sp-5) 0;
+          font-size: var(--type-sm); font-variant-numeric: tabular-nums; }
+  thead th { background: var(--color-primary); color: #fff; padding: var(--sp-3) var(--sp-4); }
+  tbody td { padding: var(--sp-3) var(--sp-4); border-bottom: 1px solid var(--color-border); }
+  tbody tr:nth-child(even) { background: var(--color-primary-light); }
+  figure { margin: var(--sp-5) 0; text-align: center; }
+  figcaption { font-size: var(--type-sm); color: var(--color-text-muted); margin-top: var(--sp-2); font-style: italic; }
+  .callout { background: var(--color-primary-light); border-left: 4px solid var(--color-accent);
+             padding: var(--sp-4) var(--sp-5); margin: var(--sp-5) 0; border-radius: 0 6px 6px 0; }
+
+  @page { size: A4; margin: var(--page-margin); }
+  @page :first { margin-top: 40mm; }
+  @media print {
+    body { background: white; padding: 0; max-width: none; }
+    h1, h2, h3, h4 { break-after: avoid; }
+    table, figure, .chart-container, .callout { break-inside: avoid; }
+    tr { break-inside: avoid; }
+    thead { display: table-header-group; }
+    p { widows: 3; orphans: 3; }
+    .cover { break-after: page; }
+    a { color: var(--color-text); text-decoration: none; }
+  }
+</style>
+</head>
+<body>
+<div class="cover"><!-- Cover page --></div>
+<!-- Document sections -->
+</body>
+</html>
+```
+
+**Modify the design tokens aggressively** — changing `--font-display`, `--color-primary`, and `--color-accent` transforms the entire document's personality.

package/.cortex/skills/pdf-documents/sections/05-css-print-rules.md

@@ -0,0 +1,135 @@
+# CSS Print Rules — The Complete Toolkit
+
+## Base Template (copy-paste starting point)
+
+```css
+/* ── Print Reset ─────────────────────────────────────────── */
+@media print {
+  body {
+    background: white;
+    color: black;
+    font-size: 11pt;           /* pt not px for print */
+    line-height: 1.5;
+    max-width: none;
+    padding: 0;
+    margin: 0;
+  }
+
+  /* Hide screen-only elements */
+  .no-print, .screen-only, nav, .toolbar { display: none !important; }
+
+  /* Links: show URL for informational, hide for navigation */
+  a[href^="http"]::after { content: " (" attr(href) ")"; font-size: 9pt; color: #666; }
+  a[href^="#"]::after { content: none; }
+  a { color: black; text-decoration: none; }
+}
+
+/* ── Page Configuration ──────────────────────────────────── */
+@page {
+  size: A4 portrait;
+  margin: 20mm 15mm 25mm 15mm;  /* top right bottom left */
+
+  /* Running header/footer (WeasyPrint + Prince; NOT Chromium) */
+  @top-center { content: "Document Title"; font-size: 9pt; color: #888; }
+  @bottom-right { content: "Page " counter(page) " of " counter(pages); font-size: 8pt; }
+}
+
+/* First page: no header, larger top margin for cover */
+@page :first {
+  margin-top: 40mm;
+  @top-center { content: none; }
+}
+```
+
+## Page Break Control (CRITICAL for quality output)
+
+```css
+/* ── GOLDEN RULES ────────────────────────────────────────── */
+
+/* 1. NEVER let headings orphan at page bottom */
+h1, h2, h3, h4 {
+  break-after: avoid;      /* don't break right after a heading */
+  page-break-after: avoid; /* legacy fallback */
+}
+
+/* 2. Keep tables, charts, figures together */
+table, figure, .chart-container, svg {
+  break-inside: avoid;
+  page-break-inside: avoid;
+}
+
+/* 3. Force page breaks where you WANT them */
+.page-break { break-before: page; page-break-before: always; }
+.cover { break-after: page; page-break-after: always; }
+
+/* 4. Avoid widows and orphans (single lines stranded) */
+p {
+  widows: 3;   /* min lines at top of new page */
+  orphans: 3;  /* min lines at bottom before break */
+}
+
+/* 5. For LONG sections that MUST break, remove avoid */
+/* LESSON LEARNED: break-inside:avoid on a section taller than
+   one page creates a BLANK page before it. Only use avoid on
+   elements shorter than one full page. */
+.timeline-item { break-inside: avoid; }  /* individual items OK */
+.timeline { /* NO break-inside:avoid — section is multi-page */ }
+
+/* 6. Table rows: keep header visible after break */
+thead { display: table-header-group; }  /* repeat header on each page */
+tfoot { display: table-footer-group; }
+tr { break-inside: avoid; page-break-inside: avoid; }
+```
+
+## Common Print Pitfalls and Fixes
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| **Blank page before section** | `break-inside: avoid` on element taller than page | Remove `avoid` from container; apply to children |
+| **Table split mid-row** | Missing `break-inside: avoid` on `<tr>` | Add `tr { break-inside: avoid; }` |
+| **Heading alone at page bottom** | No `break-after: avoid` on `<h2>` | Add heading break rules |
+| **Background colors missing** | Chromium strips backgrounds by default | Use `--print-background` flag or `color-adjust: exact` |
+| **SVG chart cut in half** | SVG inside a div without `break-inside: avoid` | Wrap SVG in `.chart-container { break-inside: avoid; }` |
+| **Margins too small for binding** | Equal margins all sides | Use asymmetric: `@page :left { margin-left: 25mm; }` |
+| **Dark backgrounds waste ink** | Designed for screen | Use `@media print` to flip to light backgrounds |
+| **Font size too small** | Using `px` (screen) not `pt` (print) | `1pt = 1/72 inch`. Use 10-12pt body, 8-9pt captions |
+| **Images overflow page** | Fixed-width images | `img { max-width: 100%; height: auto; }` |
+| **Code blocks cut off** | Long lines + `overflow: hidden` | `pre { white-space: pre-wrap; word-wrap: break-word; }` |
+
+## Named Pages (Mixed Layouts in One Document)
+
+```css
+/* Define named page types */
+@page cover-page { size: A4; margin: 0; }
+@page content-page { size: A4; margin: 20mm 15mm 25mm 15mm; }
+@page landscape-page { size: A4 landscape; margin: 15mm; }
+
+/* Assign sections to page types */
+.cover { page: cover-page; break-after: page; }
+.content { page: content-page; }
+.wide-table { page: landscape-page; break-before: page; break-after: page; }
+```
+
+## Chromium-Specific Print Flags
+
+```bash
+# Print with backgrounds (colors, gradients)
+chromium --headless --no-sandbox --disable-gpu \
+  --print-to-pdf=output.pdf \
+  --print-to-pdf-no-header \
+  --run-all-compositor-stages-before-draw \
+  input.html
+
+# Note: --print-background is implied by --print-to-pdf in modern Chromium
+# The CSS property `color-adjust: exact` forces background printing per-element
+```
+
+```css
+/* Force background printing for specific elements */
+.colored-header {
+  background: oklch(0.30 0.08 250);
+  color: white;
+  -webkit-print-color-adjust: exact;
+  print-color-adjust: exact;
+}
+```