@pareto4/pp-core 1.7.0 → 1.8.0

package/pareto-skills/pp-brand/SKILL.md

@@ -0,0 +1,644 @@
+---
+name: pp-brand
+description: Apply The Pareto Project brand to any deliverable. Use this skill whenever creating or reviewing content, presentations, documents, web artifacts, or application UX for Pareto. Trigger phrases include "make a presentation", "write a proposal", "create a page", "build a dashboard", "write copy", "make slides", "design a screen", "draft an email", "create a report", or any request to produce a client-facing or public deliverable for Pareto. Also triggers on "on-brand", "Pareto style", or requests to check/improve content for Pareto brand alignment. The brand includes the Pareto Crew — six animated AI-agent characters, one per delivery phase (Discovery, Plan, Build, Validate, Deploy, Run), used to communicate the 80/20 execution model.
+---
+
+# The Pareto Project — Brand Skill
+
+## What this skill does
+
+Ensures every Pareto deliverable — written, visual, or interactive — is consistent, credible, and on-brand. Covers three output modes and five formats. Includes the **Pareto Crew** — six animated agent characters, one per delivery phase, used to personify the 80/20 AI-execution model. The crew has **no character names** — the pipeline phase is the identity — and their **eyes track the cursor**.
+
+**Visual references (ship alongside the skill):**
+- `assets/pareto-brand-preview.html` — Full brand identity preview (colors, type, components, crew)
+- `assets/crew/*.svg` — Static SVG exports of each phase agent
+- `assets/crew/ParetoAgent.tsx` — Drop-in React component (Next.js / React 19)
+- `assets/crew/ParetoAgent.inline.html` — Vanilla-HTML copy-paste snippet
+
+---
+
+## Output Modes
+
+| Mode | Trigger | What to do |
+|------|---------|-----------|
+| **Generate** | "Create / write / build / make" | Load brand reference → apply format rules → produce output |
+| **Check** | "Review / check / is this on-brand" | Score against brand dimensions → show what works / what to fix |
+| **Improve** | "Fix / improve / rewrite" | Identify top issues → rewrite with before/after → explain changes |
+
+---
+
+## Pareto Brand Identity
+
+### Who is Pareto
+
+The Pareto Project is an **AI-First software delivery company**. We redesigned the software development lifecycle so AI agents execute ~80% of the work and humans own the 20% that matters: defining the problem, validating the outcome, taking responsibility.
+
+The brand is **technical, confident, optimistic**. Serious about craft, approachable in voice. Where 21south is clinical, Pareto is warmer — it has a cast of characters. Where most AI-tooling brands are abstract, Pareto is specific: every delivery phase has its own agent.
+
+### Brand Character
+
+| Dimension | Pareto Optimum |
+|-----------|----------------|
+| Visual style | **Confident minimalism** — sharp right angles, generous whitespace, one bold accent |
+| Tone | **Direct and human** — plain English, first-principles, no buzzwords |
+| Complexity | **Technical** — we explain the mechanism, not just the benefit |
+| Focus | **Outcome-first** — economics, speed, quality; receipts over promises |
+| Mascot | **The Crew** — six agents, one per delivery phase, no names |
+
+### Core Design Principles
+
+1. **Pareto Blue is the signal** — one accent color does all interactive lifting. No rainbow palettes.
+2. **Right angles, not pillows** — 3–4px radius maximum. Cards, buttons, inputs share the same sharp edge.
+3. **Type is the design** — strong hierarchy with Inter + JetBrains Mono. No decorative shapes to prop up layouts.
+4. **Mono for metadata, sans for content** — JetBrains Mono labels, eyebrows, kickers, numbers. Inter for everything the reader reads.
+5. **The crew has roles, not just faces** — every agent owns one pipeline phase (no names — the phase is the identity). Don't use them decoratively.
+6. **Evidence over superlatives** — "build time: 1 month" beats "blazingly fast." Numbers first.
+
+---
+
+## Colors
+
+### Primary Colors
+
+| Name | Hex | RGB | Use |
+|------|-----|-----|-----|
+| **Pareto Blue** | `#2251FF` | 34/81/255 | Primary brand, CTAs, active states, links, accents |
+| **Pareto Blue Steel** | `#146FF4` | 20/111/244 | Hover states, secondary fills |
+| **Night** | `#051C2C` | 5/28/44 | Dark sections, headings on light bg |
+| **Ink** | `#0A1330` | 10/19/48 | Mascot face details (eyes, mouth) |
+| **White** | `#ffffff` | 255/255/255 | Primary light surface |
+| **Fog** | `#F5F7FA` | 245/247/250 | Alt surface, card bg on light |
+| **Slate** | `#6B7A99` | 107/122/153 | Body text on light bg |
+| **Border** | `#E0E5EE` | 224/229/238 | Hairlines, card edges |
+
+### Crew Accent Palette
+
+Six accent colors — **one per phase agent**. Never use outside crew contexts. These are *phase identifiers*, not UI tokens. The crew has no character names — the pipeline phase is the identity.
+
+| Agent | Mode | Body color | Antenna dot | Accessory |
+|-------|------|------------|-------------|-----------|
+| **Discovery** | Human-led | `#F6B437` Amber | `#2251FF` Pareto Blue | Magnifying glass |
+| **Plan** | AI-led | `#146FF4` Steel | `#F6B437` Amber | Blueprint |
+| **Build** | AI-led | `#2251FF` Pareto Blue | `#F6B437` Amber | Hard hat |
+| **Validate** | Human-led | `#3ECF8E` Mint | `#F6B437` Amber | Checklist |
+| **Deploy** | AI-led | `#FF6B4A` Coral | `#F6B437` Amber | Rocket |
+| **Run** | AI-led | `#A884FF` Violet | `#F6B437` Amber | Gauge |
+
+The **hero** agent (single-mascot / hero placements) is Pareto Blue with no phase accessory. Human-led phases (Discovery, Validate) carry blue mode labels; AI-led phases carry green (`#1D9E75`).
+
+### Semantic
+
+| Name | Hex | Use |
+|------|-----|-----|
+| Success | `#00A878` | Confirmations, passing tests |
+| Warning | `#F3A738` | Advisories |
+| Error | `#E04E2F` | Destructive, failures |
+
+**Rules:**
+- Pareto Blue dominates. One accent across the entire interface.
+- Crew accents appear **only** with crew mascots or agent-role labels. Never as generic UI chrome.
+- Never combine more than one crew accent in the same card — that's a mascot lineup, not a palette.
+- Gradients: avoid. If unavoidable, Pareto Blue → Night only.
+
+---
+
+## Typography
+
+### Fonts
+
+- **Inter** (sans) — UI, body, headings. Weights 300 / 400 / 500 / 600 / 700 / 800.
+- **JetBrains Mono** — eyebrows, labels, metadata, numerics, code. Weights 400 / 500.
+
+Loaded via `next/font/google` in the Next.js site; exposed as `--font-sans` / `--font-mono`.
+
+| Role | Font | Weight | Size | Use |
+|------|------|--------|------|-----|
+| Display / Hero | Inter | 800 | clamp(2rem, 3.8vw, 3.4rem) | Hero claim |
+| H1 | Inter | 800 | 2.4rem | Page title |
+| H2 | Inter | 700 | 1.8–2.4rem | Section title |
+| H3 | Inter | 700 | 1.1rem | Card title |
+| Body (P) | Inter | 400 | 1rem | Body copy |
+| Caption | Inter | 400 | 0.84rem | Descriptions |
+| Eyebrow / Kicker | JetBrains Mono | 400–500 | 0.75rem, 0.18em tracking, uppercase | Section markers |
+| Label / Tag | JetBrains Mono | 500 | 0.7rem, 0.14em tracking, uppercase | Status, metadata |
+| Numeric | Inter | 800 | 2rem | Stat values |
+
+**Settings:**
+- Letter-spacing on headings: `-0.025em` (display), `-0.02em` (h2), `-0.01em` (h3).
+- Line-height: 1.08 (display), 1.1 (h2), 1.25 (h3), 1.65 (body).
+- Heading color on light: `#051C2C`. Body on light: `#6B7A99`.
+- Heading color on dark: `#ffffff`. Body on dark: `rgba(255,255,255,0.55)`.
+
+---
+
+## Voice & Tone
+
+### Character
+
+Pareto communicates in **English** (Dutch for NL-market materials on request). Direct, first-principles, human. We explain mechanisms, not just benefits.
+
+### Six principles
+
+1. **First-principles** — Explain *why*, not just *what*. "We redesigned the SDLC because AI changed the economics" beats "leverage AI synergies."
+2. **Specific > abstract** — "Build time: 1 month vs 5 months" beats "faster delivery."
+3. **Plain English** — No jargon unless earned. If a smart 15-year-old wouldn't follow, rewrite.
+4. **Confident, not grandiose** — Affirmative verbs, no superlatives. "Pareto delivers" not "Pareto is the leading AI-first platform."
+5. **Evidence over promise** — Benchmarks, numbers, before/after. Show the receipts.
+6. **Own the trade-offs** — If something is hard, say so. Humans own the 20% *because* AI can't be trusted with it. That's the model, not a caveat.
+
+### Writing Rules
+
+| Do | Don't |
+|----|-------|
+| Active voice | Passive constructions |
+| Specific numbers | Vague quantities ("many", "fast") |
+| Short declarative sentences | Nested clauses |
+| Em-dashes for aside clauses | Parentheses for everything |
+| Name the phase agent ("the Build agent ships code") | Anthropomorphize generically ("the AI") |
+| Em-dash `—` (U+2014) | Hyphen `-` for ranges / asides |
+
+### Vocabulary
+
+**Use:** AI-first, delivery, specification, discovery, agent, pipeline, execute, validate, ship, benchmark, craft, manifest, 80/20.
+
+**Avoid:** synergy, leverage, revolutionary, game-changer, best-in-class, robust, seamless, cutting-edge.
+
+### The Crew — usage rules
+
+- The crew has **no character names** — refer to each agent by its phase: "the Discovery agent", "the Build agent".
+- Agents *do* things. "The Validate agent gates every increment." Not "Validate represents quality."
+- Introduce by phase + what it owns: "the Deploy agent — automated, reversible releases."
+- When referring to the group: "the Pareto Crew", "the six agents", or "our agents."
+- Never use more than 2 agents in a single paragraph. Rotate.
+
+---
+
+## The Pareto Crew — mascot system
+
+### Anatomy
+
+Every agent is built from the same 140×140 viewBox:
+
+- **Body** — rounded rectangle, 28px corner radius, body color fill
+- **Antenna** — 4px stroke line + 5px radius dot above the head
+- **Eyes** — white circles (r=8) with a dark pupil (r=4, `#0A1330`) that **track the cursor** (rAF-throttled; pupils clamp inside the white; disabled under reduced-motion). At rest, offset slightly down-right.
+- **Smile** — quadratic curve, 3px stroke `#0A1330`
+- **Accessory** — phase-specific element: magnifying glass (Discovery), blueprint (Plan), hard hat (Build), checklist (Validate), rocket (Deploy), gauge (Run)
+
+### Animation timings (idle)
+
+| Element | Keyframes | Duration |
+|---------|-----------|----------|
+| Body | bob ±4px | 3.4s ease-in-out |
+| Antenna dot | pulse + opacity | 2.2s ease-in-out |
+| Eyes | blink (scaleY 1 → 0.1) | 5s ease-in-out |
+| Smile | stretch 1.08× | 4s ease-in-out |
+| Role accessory | stage-specific micro-motion | 1.8–3.6s |
+
+When a row of agents appears, **stagger `animation-delay` by 0.3s per agent** (six agents) so they don't sync.
+
+Beyond idle motion, the **pupils track the cursor in real time** (interactive, rAF-throttled) — a separate behaviour from the idle blink.
+
+Respect `prefers-reduced-motion: reduce` — kill all agent animations **and** the eye-tracking when set.
+
+### Sizing rules
+
+| Context | Size |
+|---------|-----:|
+| Hero mascot (single hero agent) | 240–320px |
+| Crew row on landing page | 100–140px |
+| Product companion (peeking) | 60–80px |
+| Agent card (role explainer) | 96–120px |
+| Inline in paragraph | 24–32px |
+| Favicon-scale | Use flat variant, no face |
+
+**Rule:** never render below 24px with a face. Below that, drop to the body silhouette + antenna.
+
+### When to use which agent
+
+Match the agent to the pipeline phase the content is about:
+
+- **Discovery** (Human-led, amber) — research, scoping, problem definition, stakeholder work.
+- **Plan** (AI-led, steel) — backlog, increments, sequencing, dependency mapping.
+- **Build** (AI-led, Pareto Blue) — "we build" contexts, code, the default/hero agent. The face of Pareto.
+- **Validate** (Human-led, mint) — quality, security, testing, sign-off, governance.
+- **Deploy** (AI-led, coral) — release, go-live, launch, deployment notes.
+- **Run** (AI-led, violet) — monitoring, ops, cost, reliability, knowledge base.
+
+### Don'ts
+
+- Don't place the Pareto wordmark on the chest — the agent *is* the brand.
+- Don't give the agents character names — they're identified by their phase.
+- Don't recolor agents — body colors are fixed (one per phase).
+- Don't draw new agents or new accessories without a design review.
+- Don't use the crew as pure decoration. Each appearance should earn its phase.
+
+---
+
+## Format Rules
+
+### 1. VOICE & WRITTEN COPY
+
+**Structure:**
+1. What changed (the market, the tech, the economics)
+2. What we built in response
+3. What the reader gets
+
+**Content types:**
+- **Proposals:** Situation → Mechanism (what we do differently) → Evidence (benchmarks) → Next step
+- **Emails:** Subject = outcome. Body = ask or update. Brief.
+- **Release notes:** New · Changed · Fixed. Max 2 sentences per item. Agent attribution optional ("Shipped by the Deploy agent").
+- **Blog posts:** Lead with a specific claim + a number. Support with a mechanism. End with a callable next step.
+
+**Language:** English by default; Dutch for NL-market deliverables on request.
+
+---
+
+### 2. PRESENTATIONS
+
+**Slide anatomy:**
+- One idea per slide
+- Headline: Inter 700, max 12 words
+- Eyebrow: JetBrains Mono, uppercase, 0.18em tracking, Pareto Blue
+- One visual OR one table OR three bullets — never all three
+
+**Slide modes:**
+
+| Mode | Background | Text | Accent | Use for |
+|------|-----------|------|--------|---------|
+| Night | `#051C2C` + grid overlay | White | `#2251FF` | Section openers, hero, manifest |
+| Fog | `#F5F7FA` | `#051C2C` | `#2251FF` | Data, comparisons, process |
+| White | `#ffffff` | `#051C2C` | `#2251FF` | Detail, quotes, bios |
+
+**Crew appearances:**
+- Opening slide: single hero agent, 240px, centered.
+- Process slide: all six agents in a row mapped to the delivery phases (Discovery → Run).
+- Section dividers: the agent matching the section's phase (e.g., Validate for "Quality").
+
+---
+
+### 3. DOCUMENTS (Word / PDF / Reports)
+
+**Typography:**
+- H1: Inter Bold 28–36pt, `#051C2C`
+- H2: Inter Bold 22pt, `#2251FF`
+- H3: Inter SemiBold 16pt, `#051C2C`
+- Body: Inter Regular 11pt, `#6B7A99`, 1.6 line-height
+- Code/data: JetBrains Mono 10pt
+
+**Tables:**
+- Header: `#051C2C` background, white text, Inter 600
+- Zebra: `#F5F7FA` / `#ffffff`
+- Borders: 1px `#E0E5EE`
+
+**Callouts:**
+- Info: 3px left border `#2251FF`, `#F5F7FA` bg
+- Warning: 3px left border `#F3A738`, `#FFF8E1` bg
+- Success: 3px left border `#00A878`, `#F0FAF4` bg
+
+**Crew appearances in documents:**
+- Cover page: single hero agent top-right, 120px
+- Chapter openers: the agent matching the chapter's phase, 80px
+- Never inline in body copy (too small, becomes noise)
+
+---
+
+### 4. WEB & HTML ARTIFACTS
+
+**CSS design tokens — always use:**
+
+```css
+:root {
+  /* Primary */
+  --blue:        #2251FF;
+  --blue-steel:  #146FF4;
+  --night:       #051C2C;
+  --ink:         #0A1330;
+  --fog:         #F5F7FA;
+  --slate:       #6B7A99;
+  --border:      #E0E5EE;
+
+  /* Crew accents — one per phase */
+  --crew-discovery: #F6B437;
+  --crew-plan:      #146FF4;
+  --crew-build:     #2251FF;
+  --crew-validate:  #3ECF8E;
+  --crew-deploy:    #FF6B4A;
+  --crew-run:       #A884FF;
+  --crew-antenna:   #F6B437;
+
+  /* Semantic */
+  --success: #00A878;
+  --warning: #F3A738;
+  --error:   #E04E2F;
+
+  /* Typography */
+  --font-sans: var(--font-sans, 'Inter'), system-ui, sans-serif;
+  --font-mono: var(--font-mono, 'JetBrains Mono'), monospace;
+
+  /* Shape */
+  --radius: 3px;
+  --radius-md: 4px;
+  --shadow-sm: 0 1px 3px rgba(5,28,44,0.08), 0 4px 16px rgba(5,28,44,0.06);
+  --shadow-md: 0 4px 20px rgba(5,28,44,0.10);
+}
+```
+
+**Layout principles:**
+- Max content width: 1200px, centered
+- Section padding: 96px vertical / 72px horizontal on desktop
+- Base grid unit: 8px
+- Hero sections: minimum `92vh`, radial blue tint + linear-gradient background, faint grid overlay at 72px
+
+**Component patterns:**
+- Buttons: 3px radius, Inter 600
+  - Primary: `#2251FF` fill, white text
+  - Ghost: transparent, `rgba(255,255,255,0.18)` border on dark / `#E0E5EE` on light
+- Cards: white bg, 1px `#E0E5EE`, 4px radius, 32px padding
+- Eyebrow blocks: JetBrains Mono uppercase, Pareto Blue, 16px margin-bottom
+- Status pills: 3px radius, 12% opacity bg, darker text
+- Mascot sit-ins: never on a colored fill that clashes with the agent's body
+
+---
+
+### 5. APPLICATION UX
+
+**Core principles:**
+- Desktop-first; single-column on mobile only where necessary
+- One accent color (Pareto Blue). Status colors appear only as badges / indicators
+- Dashboards use Night or Fog as the dominant surface — never both in the same screen
+- Agents can act as pipeline-stage indicators in build/CI views — show the agent responsible for each step
+
+---
+
+## Integration into the Pareto website (Next.js 16 / React 19)
+
+The crew is already live in production. When porting it elsewhere:
+
+1. **Drop `ParetoAgent.tsx`** into `src/app/components/ParetoAgent.tsx` (from `assets/crew/`). Roles: `hero | discovery | plan | build | validate | deploy | run`. Pupils track the cursor automatically.
+2. **Hero** — `<ParetoAgent role="hero" size={220} />` in the hero content.
+3. **Crew row** — `<ParetoCrewRow />` renders all six agents with phase number, label, human/AI mode, and a one-line function (no names).
+4. **Process page** — `CrewFlowVisual.tsx` maps the six phases (Discovery, Plan, Build, Validate, Deploy, Run); agents can stand in for the stage icons.
+5. **Blog posts** — byline may attribute to a phase agent ("Shipped by the Deploy agent") with a small 32px inline agent.
+
+Always respects `prefers-reduced-motion` (idle animation **and** eye-tracking disabled). No dependencies added to package.json.
+
+---
+
+## Brand Check Scorecard
+
+When reviewing existing content:
+
+| Dimension | Strong | Acceptable | Needs Work |
+|-----------|--------|-----------|------------|
+| **Color** | Pareto Blue dominates, crew accents only with crew | Minor deviations | Rainbow palette, wrong hex |
+| **Typography** | Inter + JetBrains Mono, correct hierarchy | Slight inconsistency | Wrong fonts, missing mono |
+| **Voice** | Specific, first-principles, active, evidence-led | Some passive / vague | Buzzwords, superlatives |
+| **Crew usage** | Role-matched, correct sizing, animations respected | Decorative but not wrong | Random, off-palette, tiny-with-face |
+| **Layout** | Sharp edges, generous whitespace, clear hierarchy | Slightly cramped | Rounded pillows, decorative noise |
+| **Numbers** | Specific benchmarks, with comparisons | Generic stats | No evidence, adjectives only |
+
+**Output format:**
+```
+## Brand Check: [Name]
+
+### What works
+- [Specific example]
+
+### Fix these
+- **[Dimension]**: [Issue] → [Specific fix]
+  Before: "[quote]"
+  After:  "[rewrite]"
+
+### Overall: Strong / Acceptable / Needs Work
+[One-line summary + priority recommendation]
+```
+
+---
+
+## Examples
+
+### Generate: Client update email
+
+**Request:** "Write a project update email about the deployment pipeline work"
+
+```
+Subject: Deployment time: 2 hours → 8 minutes
+
+Hi [Name],
+
+Quick update on the CI/CD automation.
+
+This week we completed the automated deployment pipeline for staging:
+
+- Deploy time: 2 hours → 8 minutes
+- Manual steps: 0 (previously 12 error-prone actions)
+- Quality gates: enforced automatically on every deploy
+
+The pipeline is boring by design. That's what production systems demand.
+
+Next: we extend this to production. I need 30 minutes of your time to approve the gate configuration — I'll send a calendar invite.
+
+One decision needed: automatic rollback on health check failure, or manual?
+- Automatic: faster recovery, less risk
+- Manual: you approve every rollback
+- My recommendation: manual first, automatic after we build confidence
+
+Let me know by Thursday.
+
+[Name]
+```
+
+### Check: Slide headline
+
+**Request:** "Check this slide headline: 'Leveraging our innovative AI-powered platform to synergistically drive digital transformation'"
+
+```
+## Brand Check: Slide headline
+
+### Fix these
+- **Voice**: Buzzword-heavy, no evidence, passive framing
+  Before: "Leveraging our innovative AI-powered platform to synergistically drive digital transformation"
+  After:  "We cut deployment time from 2 hours to 8 minutes — by removing 12 manual steps"
+
+### Overall: Needs Work
+Replace every adjective with a number. Start with the outcome.
+```
+
+### Generate: LinkedIn post
+
+**Request:** "Write a LinkedIn post about quality and speed"
+
+```
+Most teams treat quality and speed as a tradeoff.
+
+They're not. That's a false choice.
+
+When you build quality in from the start — proper CI/CD gates, automated testing, zero manual steps — you eliminate the rework that slows everything down.
+
+We recently rebuilt a client's deployment pipeline from scratch. The result: 2 hours became 8 minutes. Not because we moved faster. Because we eliminated 12 sources of waste.
+
+Quality doesn't slow you down. Poor quality does.
+```
+
+---
+
+## Notes for Claude
+
+- Pareto communicates in **English** by default; Dutch on request for NL-market content.
+- **Never freestyle colors** — use the exact hex values in this document.
+- **Pareto Blue `#2251FF`** is the single dominant accent. Crew accents are *only* for crew.
+- **Inter + JetBrains Mono** — no other fonts. JetBrains Mono *only* for labels, eyebrows, metadata, numerics.
+- **The crew has roles** — six agents, one per phase, no character names. Use the right one for the context (Discovery, Plan, Build, Validate, Deploy, Run). Pupils track the cursor; respect reduced-motion.
+- **Animations always respect `prefers-reduced-motion`** — no exceptions.
+- **Em-dash `—` (U+2014)** for asides, never a hyphen.
+- **Evidence > superlatives** — every claim should have a number or a benchmark.
+- **Sharp edges** — 3–4px radius max across the whole system.
+- **The production integration point** is `gitlab.com/pareto4/website` (Next.js 16, React 19). Components live at `src/app/components/ParetoAgent.tsx` and `src/app/components/ParetoCrewRow.tsx`.
+
+---
+
+## PDF Output — Paginated HTML
+
+### Step 1: Always ask first
+Before building any HTML, ask: **"Is this for PDF output or for use as a website/application?"**
+
+- **For PDF output:** Use the paginated design system described below. Every page is an exact `297mm × 210mm` block. Content is written to fit the grid — never the other way around.
+- **For website/application:** Use the standard fluid layout with `max-width`, section padding, and responsive design. Do NOT apply fixed page dimensions.
+
+---
+
+### Step 2: Design system first — content second
+
+The single most important rule: **define the type scale and spacing system before writing any content.** Never adjust font sizes after the fact to make content fit. If content doesn't fit, cut the content.
+
+#### Fixed type scale (A4 landscape)
+
+| Role | Size | Use |
+|------|------|-----|
+| Display / Hero | 48px | Hero h1 only |
+| H2 | 28px | Section title |
+| H3 | 15px | Card/component title |
+| Body | 13px | All body copy |
+| Small | 11px | Captions, descriptions, notes |
+| Mono/label | 10px | Kickers, tags, metadata |
+| Footer | 9px | Footer only |
+
+**Rule: these sizes are fixed. No inline `font-size` overrides anywhere. Ever.**
+
+#### Fixed spacing scale
+
+Use multiples of 4px: `4 / 6 / 8 / 12 / 16 / 20 / 24 / 32px`. Define as CSS variables and reference them consistently. Never use arbitrary pixel values.
+
+#### Page geometry (A4 landscape)
+
+| Dimension | Value |
+|-----------|-------|
+| Page width | 297mm (1123px at 96dpi) |
+| Page height | 210mm (794px at 96dpi) |
+| Padding | 14mm (53px) each side |
+| Footer height | 10mm (38px) |
+| Content area | 1017 × 650px |
+
+**Content budget:** at 13px body with 1.55 line-height = ~20px per line. Content area gives ~32 lines of body text. Write to this budget.
+
+---
+
+### Step 3: Page shell CSS
+
+```css
+:root {
+  --pad:    53px;   /* 14mm */
+  --footer: 38px;   /* 10mm */
+
+  --t-display: 48px;
+  --t-h2:      28px;
+  --t-h3:      15px;
+  --t-body:    13px;
+  --t-small:   11px;
+  --t-mono:    10px;
+  --t-footer:   9px;
+
+  --sp-4:   4px;  --sp-6:   6px;  --sp-8:   8px;
+  --sp-12: 12px;  --sp-16: 16px;  --sp-20: 20px;
+  --sp-24: 24px;  --sp-32: 32px;
+}
+
+.page {
+  width: 297mm;
+  height: 210mm;
+  overflow: hidden;
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  page-break-after: always;
+  break-after: page;
+}
+
+.content {
+  flex: 1;
+  padding: var(--pad);
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+.footer {
+  height: var(--footer);
+  padding: 0 var(--pad);
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  flex-shrink: 0;
+}
+```
+
+---
+
+### Step 4: Verify before generating
+
+Before running Playwright, check that no page exceeds 794px height:
+
+```javascript
+const heights = page.evaluate(() =>
+  Array.from(document.querySelectorAll('.page')).map((p, i) => ({
+    page: i + 1,
+    h: Math.round(p.getBoundingClientRect().height)
+  }))
+);
+// Every page must be exactly 794px. If any page > 794px, cut content — never resize fonts.
+```
+
+---
+
+### Step 5: Generate PDF with Playwright
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch()
+    page = browser.new_page()
+    page.goto(f"file://{html_path}")
+    page.wait_for_timeout(3000)  # wait for fonts
+    page.pdf(
+        path=pdf_path,
+        format="A4",
+        landscape=True,
+        margin={"top": "0", "right": "0", "bottom": "0", "left": "0"},
+        print_background=True
+    )
+    browser.close()
+```
+
+---
+
+### Rules summary
+
+- **Design system first, content second** — never the reverse
+- **No inline font-size overrides** — all sizes from CSS variables
+- **No inline spacing values** — all spacing from the scale
+- **Content that doesn't fit gets cut** — not resized
+- **Every page exactly 794px** — verify before generating
+- **Footer always present** — logo left, page number right
+- **`print_background: true`** — required for background colors and gradients