Initial commit: add all skills files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

minimax-pdf/design/design.md

@@ -0,0 +1,381 @@
+# 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_image` URL renders as centered hero thumbnail
+- Optional `abstract` field: 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 `magazine` but 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_image` rendered 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:
+
+```css
+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 a `label` and `values` array.
+- Figure auto-numbering: set `"figure": true` (default) or `"figure": false` to 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
+
+- `id` field 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 `title` field defaults to "References". Set `"title": ""` to suppress the heading.
+- A `bibliography` block 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
+- `figure` blocks auto-number; `image` blocks do not — use `figure` for 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 `language` field 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