@hegemonart/get-design-done 1.34.2 → 1.34.4

package/connections/lazyweb.md

@@ -0,0 +1,124 @@
+# Lazyweb MCP — Connection Specification
+
+This file is the connection specification for Lazyweb within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+Lazyweb is a **free, MCP-native visual-reference library** (250k+ real app screens). In the discover stage it is the **cost-aware default**: because it requires no paid subscription, GDD tries it **first**, before any paid reference source (Mobbin/Refero). Pitched for pricing pages, onboarding flows, "improve this existing screen" comparisons, and UI benchmarking against shipped products.
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- No account or subscription required — the free tier authorizes read-only UI reference search.
+- A Lazyweb MCP bearer token (free) saved locally.
+
+**Install (Claude Code):** *copy-command — never auto-run, because it writes a credential to disk (user-consent step).*
+
+```
+# 1. save the free bearer token (chmod 600 — local config only, never commit)
+mkdir -p ~/.lazyweb && printf '%s' "<your-token>" > ~/.lazyweb/lazyweb_mcp_token && chmod 600 ~/.lazyweb/lazyweb_mcp_token
+# 2. install the plugin
+claude plugin marketplace add https://github.com/aboul3ata/lazyweb-skill
+claude plugin install lazyweb@lazyweb
+```
+
+**Cursor / Codex / generic MCP:** register the Streamable-HTTP MCP endpoint `https://www.lazyweb.com/mcp` with the bearer token per the host's MCP-config format (follow Lazyweb's install docs for the exact block). Restart the session after install.
+
+**Verification:**
+
+```
+ToolSearch({ query: "lazyweb", max_results: 10 })
+```
+
+Expect `lazyweb_search` + `lazyweb_health`. If empty, the MCP is not registered — complete the install and restart.
+
+---
+
+## When to use
+
+In the **discover** stage, **try Lazyweb first** (it's free). Strong for:
+
+- Pricing pages, plan/billing layouts
+- Onboarding + activation flows
+- "Improve this existing screen" / redesign comparisons
+- UI benchmarking against real, shipped products
+
+## Tools available (verify via ToolSearch on first use)
+
+- **`lazyweb_search` `{ query, limit }`** — semantic search across Lazyweb's indexed app-screen corpus.
+- **`lazyweb_health`** — connection/health probe.
+
+Names may vary between versions — treat the ToolSearch result as authoritative; do not hardcode.
+
+## Search strategy
+
+Run **at least 2 queries per task** — one structural, one aesthetic (same discipline as Refero):
+
+- **Structural** (what it IS): "pricing page three tiers", "onboarding checklist", "empty state dashboard", "settings billing".
+- **Aesthetic** (how it should FEEL): "warm editorial SaaS", "neutral Swiss dashboard", "dark fintech".
+
+## Workflow
+
+```
+1. lazyweb_search "pricing page three tiers"     # structural
+2. lazyweb_search "warm editorial consumer app"  # aesthetic
+3. pick 3-7 that match the brief; save URLs + notes into the discover reference pack
+4. proceed to the plan stage with the pack
+```
+
+## Citing references in output
+
+Always name the reference: cite as `L-01: [title] — source: lazyweb — borrow: [what you took]`. Never claim originality; show the user the logic so they can push back precisely.
+
+## STATE.md integration
+
+Every stage that probes Lazyweb writes the result to `.design/STATE.md` under `<connections>`:
+
+```xml
+<connections>
+lazyweb: available
+</connections>
+```
+
+| Value | Meaning |
+|-------|---------|
+| `available` | ToolSearch returned non-empty results for `lazyweb` |
+| `unavailable` | Lazyweb tools present but a live call errored |
+| `not_configured` | ToolSearch returned empty — MCP not registered |
+
+**Probe pattern (ToolSearch-only — no tool call, no token cost):**
+
+```
+ToolSearch({ query: "lazyweb", max_results: 5 })
+  → Empty result     → lazyweb: not_configured
+  → Non-empty result → lazyweb: available
+```
+
+**Which stages probe Lazyweb:** the discover stage only (via `agents/design-context-builder.md`). Scan, plan, design, and verify do not use it.
+
+---
+
+## Fallback chain (cost-aware — try free before paid)
+
+The discover stage resolves reference sources in this order:
+
+1. **Lazyweb (Tier 1 — FREE)** — always tried first. Use when `lazyweb: available`.
+2. **Mobbin / Refero (Tier 2 — PAID)** — fall here when Lazyweb is unavailable OR you need their depth; use whichever is bound AND has an active subscription (if both, Mobbin then Refero).
+3. **Pinterest (Tier 3)** — headless scrape, occasionally flaky.
+4. **awesome-design-md (Tier 4)** — `~/.claude/libs/awesome-design-md/design-md/` structured DESIGN.md tokens.
+5. **WebFetch (Tier 5)** — last resort.
+
+Lazyweb never *replaces* the paid corpora — it's the free first attempt; fall through for breadth/flow-depth. Never proceed without references — that's the point of discover.
+
+## Anti-pattern + token handling
+
+- Don't dump a huge set of references into the response (noise) — pick 3–7 matching the brief.
+- Don't use it to justify a pre-decided direction (pull first, then decide).
+- **Token handling**: the free tier authorizes no-billing UI reference reads ONLY — never purchases, paid spend, private user data, or destructive actions. The bearer token is local-config-only (`~/.lazyweb/lazyweb_mcp_token`); never commit it to git history.
+
+## If Lazyweb's API changes
+
+Keep this file current. If tool names or the endpoint shift, update the examples here and adjust the routing in `skills/discover/SKILL.md` + `agents/design-context-builder.md`.

package/connections/mobbin.md

@@ -0,0 +1,119 @@
+# Mobbin MCP — Connection Specification
+
+This file is the connection specification for Mobbin within the get-design-done pipeline. It lives in `connections/` alongside other connection specs. See `connections/connections.md` for the full connection index and capability matrix.
+
+---
+
+Mobbin is a **curated mobile + web product reference library** (600k+ screens, 130k+ user flows from 1,600+ shipped apps) — the de-facto standard for **flow-level** mobile references. In the discover stage it is a **Tier-2 (paid) source**: GDD tries free Lazyweb first, then falls to Mobbin or Refero depending on which the user has an active subscription for. Mobbin's edge is editorial discipline + flow-level metadata + verified-product depth, especially for mobile (iOS/Android).
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- An active Mobbin subscription (the MCP is included with a paid plan).
+
+**Install (Claude Code):** *auto-run-safe — `claude mcp add` is a stateless MCP registration with zero credential filesystem-write; OAuth is handled by Mobbin in a browser on the first tool call.*
+
+```
+claude mcp add mobbin --transport http https://api.mobbin.com/mcp
+```
+
+On the first `mobbin` tool call, Mobbin opens a browser sign-in (OAuth) — no token is written to disk by GDD.
+
+**Cursor / Codex / generic MCP:** register the HTTP MCP endpoint `https://api.mobbin.com/mcp` per the host's MCP-config format; sign in via the OAuth prompt on first use. Restart the session after install.
+
+**Verification:**
+
+```
+ToolSearch({ query: "mobbin", max_results: 10 })
+```
+
+Expect Mobbin search/browse tools. If empty, the MCP is not registered — run the add command and restart.
+
+---
+
+## When to use
+
+In the **discover** stage, fall to Mobbin (after free Lazyweb) when you have a subscription and need:
+
+- **Mobile** UI references (iOS / Android platform conventions)
+- **Flow-level** references (multi-screen journeys) vs single screens
+- Industry-specific patterns — "how do fintech apps do KYC", "social app notification permission priming"
+- Verified, curated, real-product screens
+
+## Tools available (verify via ToolSearch on first use)
+
+Mobbin exposes search / browse tools (apps, screens, flows, collections) under its MCP. Names may vary between versions — treat the ToolSearch result as authoritative; do not hardcode.
+
+## Search strategy
+
+Run structural + aesthetic + **flow-level** queries (Mobbin's differentiator is flows):
+
+- **Structural / flow**: "onboarding fintech", "checkout commerce", "paywall subscription", "empty state messaging".
+- **Platform**: "iOS settings", "Android bottom sheet".
+- **Industry**: "KYC verification flow", "ride-hailing trip tracking".
+
+## Workflow
+
+```
+1. mobbin search "paywall subscription"    # flow/structural
+2. mobbin search "calm editorial fintech"  # aesthetic
+3. pick 3-5 references (NOT whole flow sets) matching the brief; save into the reference pack
+4. proceed to the plan stage with the pack
+```
+
+## Citing references in output
+
+Always name the reference: cite as `M-01: [title] — source: mobbin — borrow: [what you took]`. Show the structure you borrowed (e.g., "takes Revolut's KYC step sequencing").
+
+## STATE.md integration
+
+Every stage that probes Mobbin writes the result to `.design/STATE.md` under `<connections>`:
+
+```xml
+<connections>
+mobbin: available
+</connections>
+```
+
+| Value | Meaning |
+|-------|---------|
+| `available` | ToolSearch returned non-empty results for `mobbin` |
+| `unavailable` | Mobbin tools present but a live call errored (e.g., not signed in / no subscription) |
+| `not_configured` | ToolSearch returned empty — MCP not registered |
+
+**Probe pattern (ToolSearch-only — no tool call, no API cost):**
+
+```
+ToolSearch({ query: "mobbin", max_results: 5 })
+  → Empty result     → mobbin: not_configured
+  → Non-empty result → mobbin: available
+```
+
+**Which stages probe Mobbin:** the discover stage only (via `agents/design-context-builder.md`). Scan, plan, design, and verify do not use it.
+
+---
+
+## Fallback chain (cost-aware — try free before paid)
+
+The discover stage resolves reference sources in this order:
+
+1. **Lazyweb (Tier 1 — FREE)** — always tried first.
+2. **Mobbin / Refero (Tier 2 — PAID)** — Mobbin and Refero are peers here; use whichever is bound AND has an active subscription. If both are available, **Mobbin** for mobile/flow-level depth, **Refero** for broad screen-level coverage.
+3. **Pinterest (Tier 3)** — headless scrape, occasionally flaky.
+4. **awesome-design-md (Tier 4)** — structured DESIGN.md tokens.
+5. **WebFetch (Tier 5)** — last resort.
+
+Never proceed without references — that's the point of discover.
+
+## Anti-pattern
+
+- **Don't dump entire flow sets** into the response — pick 3–5 references that match the brief.
+- Don't use Mobbin for desktop-heavy work where Refero/Lazyweb are stronger (Mobbin's depth is mobile + flows).
+- Don't use it to justify a pre-decided direction (pull first, then decide).
+
+## If Mobbin's API changes
+
+Keep this file current. If tool names or the endpoint shift, update the examples here and adjust the routing in `skills/discover/SKILL.md` + `agents/design-context-builder.md`.

package/connections/print-renderer.md

@@ -0,0 +1,113 @@
+# Print-Renderer — Connection Specification
+
+This file is the connection specification for the print-render within the get-design-done pipeline. It lives in `connections/` alongside the other connection specs (the closest analog is `connections/preview.md`, the headless-Chrome visual-truth connection). See the connection index for the full connection capability matrix (the print-renderer row is added at the 34.3 closeout).
+
+---
+
+The print-render is the **verify stage's RENDERED proof for the `print` project type**. It renders the `pdf-executor`'s **Paged.js-compatible print HTML/CSS** to a **paginated PDF / page image** — the print analog of `preview.md`'s browser screenshots. Its pipeline role: after the `pdf-executor` generates the print HTML/CSS (validated by the static checker), the verify stage uses the print-render — **when available** — to surface print breakage the static validator cannot see (actual pagination, bleed placement, font embedding in the PDF, raster resolution), and narrates the result in plain English.
+
+**Key relationship to the static validator:** the print-render is the *rendered* complement to the *static* checker `scripts/lib/print/validate-print-css.cjs`. The static validator deterministically checks constraint **classes** (`@page` present, bleed/crop-marks signal, CMYK awareness, font-embed, 300dpi — `PR-PAGE/BLEED/CMYK/FONT/DPI`); the print-render checks the **rendered output** — what actually paginates and rasterizes. The print-render is **optional** — its absence is a quality reduction, not a blocking error (D-03).
+
+---
+
+## Setup
+
+**Prerequisites:**
+
+- **PRIMARY — Paged.js via headless Chrome:** the same headless-Chrome family `preview.md` uses. Paged.js consumes the `@page`/bleed print CSS and paginates in headless Chrome, producing a paginated PDF. No bundled dependency is required to *probe*; the render is opt-in — like the Preview MCP, prefer a built-in / no-external-package path where possible, and where a tool IS needed it is opt-in (never installed by the pipeline).
+- **ALTERNATIVE — PDFKit for Chrome-less runtimes:** where no headless Chrome is available, PDFKit constructs the page box programmatically (`new PDFDocument({ size, margins })`), embeds fonts (`doc.registerFont(...)`), and places the bleed. This is the documented Chrome-less render path.
+
+Per **D-02 / D-10** there is **NO bundled `pdfkit`/`paged`/`puppeteer`/`playwright` dependency** and **no live render in the default `npm test`** — the print-render is an optional, opt-in enhancement the maintainer wires up in the verify stage when a renderer is present.
+
+**Verification:**
+
+```bash
+command -v chromium 2>/dev/null || command -v chrome 2>/dev/null || command -v node 2>/dev/null
+```
+
+---
+
+## Why the print-render is useful
+
+Print rendering breakage is invisible to both code review and the static validator. A print stylesheet can pass every static class-check (`validatePrintCss` returns `ok: true`) and still render broken: a table splits badly across a page boundary because a `break-inside: avoid` was missing, the bleed box does not actually extend past the trim, an `@font-face` fails to embed and the RIP substitutes a metrically-different face (reflowing the layout), a raster image that *claimed* 300dpi is upscaled and pixelates.
+
+The static validator checks constraint **classes**; it cannot render. The print-render renders the **actual** document to a paginated PDF / page image, so pagination, bleed placement, font embedding, and raster resolution surface as visible output rather than a press reject weeks later.
+
+---
+
+## When to use the print-render
+
+**Verify stage:** After the `pdf-executor` generates the print HTML/CSS, run the print-render — when available — to capture a paginated PDF / page proof and check for rendered breakage. The verify stage narrates the delta and notes it in `DESIGN-VERIFICATION.md`.
+
+The print-render is **not** used at generation time. The `pdf-executor` needs no headless Chrome, no Paged.js runtime, no PDFKit, and no network to produce the print HTML/CSS — generation is gated by the static validator only (D-04/D-10).
+
+---
+
+## Availability Probe
+
+The print-render is consumed via a CLI/binary presence check (headless Chrome / PDFKit), not ToolSearch.
+
+**Step PR1 — renderer presence:**
+
+```bash
+command -v chromium 2>/dev/null || command -v chrome 2>/dev/null
+```
+
+- A headless-Chrome binary (for Paged.js) OR a PDFKit-capable runtime is found → proceed to Step PR2
+- Neither → `print-renderer: not_configured` (skip all print-render steps)
+
+**Step PR2 — render capability check:**
+
+- A renderer is present and invokable → `print-renderer: available`
+- Present but not invokable (missing flag, sandbox error) → `print-renderer: unavailable`
+
+**Write the print-renderer status to `.design/STATE.md` `<connections>` immediately after probing** — the three-value schema `preview.md` uses (`available` / `unavailable` / `not_configured`).
+
+---
+
+## Fallback Behavior
+
+When the print-render is `not_configured` or `unavailable`, the verify stage degrades gracefully — no error is raised.
+
+**verify stage (`skills/verify/SKILL.md` + `agents/design-verifier.md`):**
+
+- `print-renderer: unavailable` → skip the rendered PDF/page proof; **degrade** to the static validator `scripts/lib/print/validate-print-css.cjs` (the `PR-PAGE/BLEED/CMYK/FONT/DPI` class-checks), then a **code-only** structural audit of the print HTML/CSS; note in `DESIGN-VERIFICATION.md`: "Print render-test skipped — no headless Chrome / PDFKit; verified via the static print-CSS validator + a code-only structural audit."
+- `print-renderer: not_configured` → same as unavailable; note: "Print render-test skipped — print-render not configured; verified via the static validator + a code-only audit. (Alternative: PDFKit on a Chrome-less runtime.)"
+
+**Graceful degradation required:** the pipeline must continue when the print-render is unavailable. Missing rendered-PDF data is a **quality reduction, not a blocking error** (D-03 — the print-render is an enhancement, never hard-required, mirroring the 34.1 simulator / 34.2 Litmus connections). The static validator is always available and is the deterministic floor; the print-render is the rendered ceiling on top of it. Neither stage appends a `<blocker>` for a missing print-render connection. If a `must_have` explicitly requires rendered-PDF evidence, THEN append a blocker.
+
+---
+
+## STATE.md Integration
+
+Every stage that probes the print-render writes the result to `.design/STATE.md` under the `<connections>` section:
+
+```xml
+<connections>
+figma: available
+preview: available
+print-renderer: not_configured
+</connections>
+```
+
+**Status values:**
+
+| Value | Meaning |
+|---|---|
+| `available` | A headless-Chrome (Paged.js) or PDFKit renderer is present AND invokable |
+| `unavailable` | A renderer binary is present but the render call errored (missing flag, sandbox) |
+| `not_configured` | No headless Chrome and no PDFKit runtime — the print-render is not set up |
+
+The verify stage re-probes at stage entry (renderer availability can change between sessions). If STATE.md already carries a `print-renderer:` status from a prior stage in the SAME session, that status can be trusted for the rest of that session.
+
+---
+
+## Caveats and Pitfalls
+
+1. **The print-render is an enhancement, not a requirement.** Its absence degrades to the static validator + a code-only audit and never blocks the pipeline (D-03). Do not gate a print build on a rendered PDF.
+
+2. **Physical-unit / DPI gotchas.** The page is a physical object — `mm`/`pt`/`in` have fixed physical sizes, `px` does not across RIPs. A render at the wrong DPI (72/96 screen vs 300 print) misrepresents raster sharpness; render at the document's declared output resolution. Bleed (~3mm) and crop marks live in the trim waste — confirm the rendered PDF actually carries them.
+
+3. **No bundled render dependency.** Do NOT add `pdfkit`/`paged`/`puppeteer`/`playwright` to `package.json` to make this connection work — the render is opt-in and the maintainer supplies the renderer. The default `npm test` stays hermetic (D-10).
+
+4. **Do NOT edit the connection index here.** The print-renderer's Active-Connections entry and Capability-Matrix row are added by the 34.3 closeout plan, not by this spec (the 34.1/34.2 disjointness pattern).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.34.2",
+  "version": "1.34.4",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/print-design.md

@@ -0,0 +1,223 @@
+# Print Design — Constraint Catalogue
+
+This reference is the **print/PDF constraint catalogue**: the hard print-production rules a
+print-ready document MUST honor. Print is a *constrained* output surface — the screen-RGB
+HTML/CSS the web executor emits has no `@page` box model, no bleed/crop marks, no CMYK
+color space, no font embedding, and no 300dpi raster guidance, so it cannot be sent to a
+press as-is. This file is the **authority** that the `pdf-executor` (Phase 34.3-02) generates
+against and the design-verifier's print branch (34.3-03) audits against; neither re-derives
+these rules. The deterministic subset of this catalogue is checked by
+[`scripts/lib/print/validate-print-css.cjs`](../scripts/lib/print/validate-print-css.cjs),
+whose emitted `rule` ids are the constraint-ids defined below (the spec is the authority).
+
+It is the print sibling of the other non-web output references. The files have distinct jobs
+and must not be confused:
+
+| File | Job |
+| --- | --- |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge for native/web screens. |
+| `reference/native-platforms.md` (Phase 34.1) | The native **token bridge** — maps canonical CSS tokens to SwiftUI / Jetpack Compose / Flutter with a precision contract. *Token-identity* knowledge for native generators. |
+| `reference/email-design.md` (Phase 34.2) | The email **constraint catalogue** — table layout, inline styles, MSO comments, dark-mode `color-scheme`. *Structural* knowledge an email template implements. |
+| `reference/print-design.md` (Phase 34.3, this file) | The print **constraint catalogue** — the `@page` box model, bleed + crop marks, CMYK awareness, font embedding, and 300dpi raster fallback. *Production* knowledge a print/PDF document implements. |
+
+Per **D-02** there is **no bundled `pdfkit` / `paged` / `puppeteer` / `playwright`
+dependency**: the `pdf-executor` generates **Paged.js-compatible print HTML/CSS** as its
+canonical artifact, and the PDF is rendered by the agent's contract or the *optional*
+print-render connection, never by a build step. Per **D-03** print verify is this
+catalogue's *static* validator plus an *optional* Paged.js-headless-Chrome / PDFKit
+render-test connection that degrades to the static validator when absent. Per **D-10** the
+static checks are deterministic (same CSS/HTML string → same result), with no network and
+no PDF runtime, so the default `npm test` stays green on any machine.
+
+Each constraint carries a **rule-id** (`PR-<CLASS>-NN`). Section 8 marks exactly which ids
+the static validator asserts versus which are render-tested guidance only.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references*; Phase 23 shipped the token engine; Phase 34.1 added
+native generators; Phase 34.2 added the email catalogue. Print/PDF is the last untouched
+product surface, and its constraints are unlike screen, native, and email alike: a physical
+trim with bleed and registration marks, a *subtractive* CMYK color space instead of additive
+screen RGB, a print RIP with **no web fonts** (fonts must be embedded or outlined), and a
+300dpi raster floor (vs the screen's 72/96dpi). Instead of each print document being authored
+from memory, the constraints live once here (the catalogue) and once in the validator (the
+statically-checkable subset), and the executor + verifier consume them. This file is the
+single SC#9-print authority.
+
+The catalogue is **prose + tables**, not an implementation. Illustrative snippets are kept to
+2–3 lines. The implementation is `validate-print-css.cjs`.
+
+---
+
+## 2. The print box model — `@page`
+
+Print uses the CSS **`@page`** rule to define the page box: its `size` (a named page such as
+`A4` / `Letter`, or an explicit `WIDTH HEIGHT` with physical units), its `margin`, and its
+`marks` (`crop` / `cross`). Screen CSS has no page box at all — content flows in one
+continuous viewport — so a print stylesheet that omits `@page` has no defined page geometry
+and cannot paginate predictably. Paged.js consumes the `@page` CSS to paginate in headless
+Chrome; PDFKit instead constructs the page box programmatically (`new PDFDocument({ size,
+margins })`).
+
+| Rule-id | Constraint |
+| --- | --- |
+| **PR-PAGE-01** | A print stylesheet MUST declare an `@page` rule — the print box model. Its absence means no defined page geometry. *(Statically checkable: absence of an `@page` rule is flagged.)* |
+| PR-PAGE-02 | The `@page` rule SHOULD set `size` (named `A4`/`Letter` or explicit physical `WIDTH HEIGHT`) and `margin`; use `@page :first` / `:left` / `:right` for cover/spread-specific geometry. |
+| PR-PAGE-03 | Control pagination with `break-before` / `break-after` / `break-inside: avoid` (and the legacy `page-break-*`) so headings, tables, and figures do not split badly across page boundaries. |
+
+```css
+@page { size: A4; margin: 12mm; marks: crop cross; bleed: 3mm; }
+```
+
+---
+
+## 3. Bleed + crop marks
+
+Print is **trimmed** to a bleed box: any color or image that should reach the physical edge
+must extend ~**3mm past the trim line** (the *bleed*), so that slight cutting variance never
+exposes a white paper edge. **Crop/registration marks** tell the printer (and the trimming
+guillotine) exactly where to cut, and align the CMYK separations on press. Screen CSS has no
+notion of either. The CSS print idioms are the `bleed:` descriptor and `marks: crop` (and/or
+`cross`) on `@page`; Paged.js supports both. A safe area is kept *inside* the trim so no
+critical content sits in the cut-tolerance band.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **PR-BLEED-01** | A print document targeting edge-to-edge output MUST signal a bleed box / crop marks — a CSS `bleed:` declaration, a `marks: crop\|cross` declaration, or a documented bleed/crop-marks convention. *(Statically checkable: total absence of any bleed/marks signal is flagged.)* |
+| PR-BLEED-02 | Bleed is conventionally **3mm** (≈0.125in); registration marks sit in the trim waste outside the bleed box so they are removed when the sheet is cut. |
+| PR-BLEED-03 | Keep a **safe area** inside the trim (≈3–5mm) — critical text and logos stay inside it so cut tolerance never clips them. |
+
+---
+
+## 4. CMYK awareness
+
+Print is **subtractive CMYK** (cyan/magenta/yellow/key-black ink on paper), not the additive
+screen **RGB** the web executor emits. Pure-RGB output risks visible color shift on press:
+bright RGB blues/greens fall outside the CMYK gamut and reproduce duller, and an untagged
+document leaves the RIP to guess a conversion. A print artifact must therefore signal CMYK
+awareness — a `cmyk()` color, a `color-profile` / `@color-profile` reference (an ICC/CMYK
+target profile), or an explicit documented CMYK-target note. Exact ICC-profile correctness
+and on-press gamut matching are **render-tested**, not statically assertable (see §8).
+
+| Rule-id | Constraint |
+| --- | --- |
+| **PR-CMYK-01** | A print document MUST show CMYK awareness — a `cmyk()` color value, a `color-profile` / `@color-profile` reference, or a documented CMYK-target note. *(Statically checkable: total absence of any CMYK-awareness signal — pure screen-RGB only — is flagged.)* |
+| PR-CMYK-02 | Prefer named spot/`cmyk()` values for brand colors that must match on press; flag wide-gamut RGB (`display-p3`, neon RGB) that will not survive CMYK conversion. |
+| PR-CMYK-03 | Rich black (e.g. `C30 M30 Y30 K100`) for large solid areas; pure `K100` for small text to avoid registration fringing. *(ICC correctness is render-tested — §8.)* |
+
+```css
+:root { color-profile: url(./CoatedFOGRA39.icc); }   /* CMYK target */
+.brand { color: cmyk(0% 80% 95% 0%); }
+```
+
+---
+
+## 5. Font embedding
+
+Print **RIPs have no web fonts** and no system-font-stack fallback chain — whatever font is
+referenced must be **embedded** in the document (`@font-face` with an embedded `src:`) or the
+text must be **outlined to vector**. A bare `font-family: Arial, sans-serif` system-font-stack
+assumption is a print bug: the RIP may substitute a metrically-different face (reflowing the
+layout) or fail to render the glyphs at all. PDFKit embeds fonts via `doc.registerFont(…)`;
+Paged.js relies on `@font-face` declarations resolved before pagination.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **PR-FONT-01** | Fonts MUST be embedded or outlined — an `@font-face` rule with an embedded `src:`, or a documented font-embed/outline note. A bare system-font-stack assumption (no embed) is a print bug. *(Statically checkable: absence of any font-embed signal is flagged.)* |
+| PR-FONT-02 | Embed only the weights/styles actually used (subset where possible) to keep the PDF small; ensure the license permits embedding. |
+| PR-FONT-03 | Outline display/headline type to vector when exact rendering matters more than text selectability; keep body copy as embedded text for accessibility and reflow. |
+
+```css
+@font-face { font-family: "Brand"; src: url(./Brand.woff2) format("woff2"); }
+```
+
+---
+
+## 6. 300dpi raster fallback
+
+Raster/image assets need **300dpi** at final print size or they pixelate — screen assets are
+authored at 72/96dpi, which is ~3–4× too coarse for press. **Vector is preferred** wherever
+possible (logos, icons, rules) because it is resolution-independent; where raster is
+unavoidable (photography), it must carry a 300dpi guarantee. The CSS signals are
+`image-resolution: 300dpi` (or `from-image`), a `min-resolution` media query, or a documented
+300dpi note.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **PR-DPI-01** | Raster assets MUST carry a 300dpi raster-fallback signal — an `image-resolution:` declaration (`300dpi` / `from-image`), a `min-resolution` query, or a documented 300dpi note. *(Statically checkable: absence of any 300dpi signal is flagged.)* |
+| PR-DPI-02 | Prefer vector (SVG/PDF) for logos, icons, and line art so they stay crisp at any output size; reserve raster for continuous-tone photography. |
+| PR-DPI-03 | Size raster assets so their *effective* resolution at the placed dimensions is ≥300dpi; upscaling a 72dpi screen asset does not add real detail. |
+
+---
+
+## 7. Print color + units
+
+Print prefers **physical units** (`mm` / `cm` / `pt` / `in`) over screen `px`, because the
+page is a physical object — `px` has no fixed physical size across RIPs. Print-safe color,
+overprint, and knockout are production concerns the executor should honor; most are
+**render-tested guidance** (see §8), not statically asserted by the validator.
+
+| Rule-id | Constraint |
+| --- | --- |
+| PR-UNIT-01 | Use physical units (`mm`/`cm`/`pt`/`in`) for page geometry, margins, and bleed; reserve `px` for screen. *(Guidance.)* |
+| PR-COLOR-01 | **Overprint vs knockout** — small black text overprints (prints on top) to avoid registration gaps; light-on-dark knocks out. *(Render-tested — §8.)* |
+| PR-COLOR-02 | **Trap/registration** — adjacent CMYK separations are trapped (slightly overlapped) so misregistration on press shows no white gap. *(Render-tested — §8.)* |
+| PR-COLOR-03 | **True vector tessellation** — complex vector fills/gradients must tessellate without seams in the RIP. *(Render-tested — §8.)* |
+
+---
+
+## 8. Statically-checkable vs render-tested
+
+This table is the **contract** the validator's `rule` ids map to. The five rule-ids below are
+the deterministic subset that `scripts/lib/print/validate-print-css.cjs` asserts via
+regex/string analysis of the supplied print CSS/HTML string. Every other rule-id in this
+catalogue is **render-tested guidance** — verified by the optional Paged.js-headless-Chrome /
+PDFKit render-test connection (34.3-02), never asserted by the static validator.
+
+| Rule-id | Check | Statically checked by the validator? | How verified otherwise |
+| --- | --- | --- | --- |
+| **PR-PAGE-01** | An `@page` rule is present (the print box model) | **YES** — absence flagged | — |
+| **PR-BLEED-01** | A bleed box / crop-marks signal is present (`bleed:` / `marks:` / a documented bleed-marks note) | **YES** — total absence flagged | — |
+| **PR-CMYK-01** | A CMYK-awareness signal is present (`cmyk(` / `color-profile` / `@color-profile` / a CMYK note) | **YES** — total absence (pure RGB) flagged | — |
+| **PR-FONT-01** | A font-embed signal is present (`@font-face` with `src:` / a font-embed/outline note) | **YES** — absence flagged | — |
+| **PR-DPI-01** | A 300dpi raster-fallback signal is present (`image-resolution:` / `min-resolution` / a 300dpi note) | **YES** — absence flagged | — |
+| PR-PAGE-02..03 | `size`/`margin` set, sensible page breaks | No | Render test (paginated output) |
+| PR-BLEED-02..03 | 3mm bleed value, marks in trim waste, safe area | No | Render test (preflight) |
+| PR-CMYK-02..03 | In-gamut brand colors, rich-black vs K100, **ICC-profile correctness** | No | Render test (press proof / ICC) |
+| PR-FONT-02..03 | Subsetted/licensed embeds, vector outlining | No | Render test (PDF inspect) |
+| PR-DPI-02..03 | Vector-preferred, effective ≥300dpi at placed size | No | Render test (preflight) |
+| PR-UNIT-01, PR-COLOR-01..03 | Physical units, **overprint/knockout**, **trap/registration**, **true vector tessellation** | No | Render test (press / RIP) |
+
+Notes on the five statically-checked rules:
+
+- **Each check is a presence/absence test.** The validator flags the *total absence* of a
+  catalogued signal class in the supplied string; the presence of **any one** accepted signal
+  for a class satisfies it. The checks are independent, so a document can satisfy four classes
+  and trip exactly one.
+- **CMYK awareness is satisfied by any of three signals.** A `cmyk()` color, a
+  `color-profile` / `@color-profile` reference, **or** a documented `/* CMYK … */` note each
+  satisfy PR-CMYK-01 on their own — a fully RGB document with an explicit CMYK-target note
+  still passes (the note records the production intent the RIP needs).
+- **Render-tested rules are out of the static validator's scope by design.** Overprint
+  behavior, ICC-profile correctness, trap/registration, and true vector tessellation require
+  an actual PDF RIP / rendering engine — they are catalogued here as executor guidance and
+  verified by the optional print-render connection, never asserted statically (D-03 / D-10).
+
+---
+
+## 9. Cross-references
+
+- [`reference/email-design.md`](./email-design.md) — the email-constraint sibling
+  (table layout, inline styles, MSO comments, dark mode). The non-web siblings share the
+  catalogue-plus-static-validator shape.
+- [`reference/native-platforms.md`](./native-platforms.md) — the native token-bridge sibling
+  (SwiftUI / Compose / Flutter). The other non-web output surface.
+- [`reference/platforms.md`](./platforms.md) — the interaction-conventions sibling.
+- [`scripts/lib/print/validate-print-css.cjs`](../scripts/lib/print/validate-print-css.cjs)
+  — the deterministic static validator that asserts the §8 subset; its `rule` ids are the
+  constraint-ids defined here.
+- [`reference/registry.json`](./registry.json) — this catalogue is registered as the
+  `print-design` entry (type `heuristic`, phase `34.3`) so the registry round-trip test
+  (`test/suite/reference-registry.test.cjs`) stays green (D-05, the 34.1-01 / 34.2-01 lesson).

package/reference/registry.json

@@ -902,6 +902,13 @@
       "type": "heuristic",
       "phase": 34.2,
       "description": "Phase 34.2 email-constraint catalogue — table-based layout (not flexbox/grid/position), inline styles (not a <style> block), MSO conditional comments for Outlook, dark-mode color-scheme/prefers-color-scheme handling, ~600px max-width, image/alt rules, and top-20-client quirks; the authority the email-executor generates against and the design-verifier email branch audits against, and the rule-id source for scripts/lib/email/validate-email-html.cjs."
+    },
+    {
+      "name": "print-design",
+      "path": "reference/print-design.md",
+      "type": "heuristic",
+      "phase": 34.3,
+      "description": "Phase 34.3 print-constraint catalogue — @page size/margin/marks (the print box model), bleed box + crop/registration marks, CMYK color-space awareness (subtractive, not screen RGB), font embedding/outlining (print RIPs have no web fonts), and 300dpi raster-fallback guidance; the authority the pdf-executor generates against and the design-verifier print branch audits against, and the rule-id source for scripts/lib/print/validate-print-css.cjs."
     }
   ]
 }