` is derived from the first slide's highest-level heading (h1 before h2, regardless of order); style/script-only files contribute no slides and are skipped. Override with the `title` build option; falls back to the deck folder name. - A deck renders at a design size — 1920×1080 by default, or whatever it declares (see "Deck configuration" below) — and scales to fit the real window at runtime. Author against that fixed canvas; never against the actual viewport. - Never hand-edit the generated `index.html`. ## Slide numbering **"Slide N" always means the 1-based deck position** — the number the runtime counter shows to presenter and audience. File name prefixes only order files; a file may contain several slides, so a prefix is NOT a slide number. The runtime counter, the URL hash (`#N`), `zerp check` findings, and `zerp slides` all use deck positions. - Before editing "slide N", run `zerp slides .` (add `--json` for tooling): it prints each slide's position, source file, in-file ordinal, and title. Confirm the target by its heading. - Every composed inner `.slide` carries source-tracing attributes: `data-zerp-src` (source file), `data-zerp-src-slide` (`i/n` within that file), `data-zerp-index` (deck position). It is wrapped in a framework-owned `<div data-zerp-slide>` frame; the frame owns visibility and the inner `.slide` owns layout. - Treat `data-zerp-slide`, `data-zerp-slide-active`, and their display rules as reserved framework state. Put custom layout rules on `.slide` or a class on the inner root, not on the frame. - In a running deck, press `s` to toggle a source badge showing the active slide's position and source file. ## Design system — colors Colors come from CSS custom properties (design tokens). The framework ships a dark and a light theme; tokens flip automatically. **Never hardcode hex/rgb colors. Never invent new colors. Pick tokens by meaning.** Neutrals: - `--zerp-bg` page background · `--zerp-surface` cards/panels · `--zerp-border` borders - `--zerp-text` body text · `--zerp-muted` secondary text — use at body size (≥1.25em/20px), or at smaller sizes only with weight 700 - `--zerp-faint` decorative glyphs ONLY (arrows, dividers) — **never use for text** Accent hues (each in 4 roles): `blue green orange purple red amber teal` - `--zerp-<hue>` — colored text on the page/surface (use at body size or larger) - `--zerp-<hue>-solid` + `--zerp-on-solid` — filled backgrounds (badges, fills) and text on them - `--zerp-<hue>-tint` + `--zerp-<hue>-on-tint` — subtle washes (highlight cards/rows) and text on them Semantic aliases: `--zerp-accent` (blue), `--zerp-ok` (green), `--zerp-warn` (amber), `--zerp-danger` (red). Prefer semantic names when the color carries meaning; hue names for categorical coding. ## Typography rules - Body text is 1.25em (~20px). **Never set text below 1em; `.sm` (0.9×) is the only sanctioned shrink.** Prefer trimming content over shrinking text. - `.sm` is for inline spans within body text; on a bare paragraph it lands below the 16px floor and `zerp check` will flag it. - Do not combine `.sm` with `.muted` — small muted text fails contrast. - For a detail line under a heading or bold statement use `.sub` (1em, bold, muted — safe by construction). This is the idiom for the second line of a `.key-thought` and for card sub-text. - Colored text classes are bold by design (emphasis). Do not fight the weight. - Decorative glyphs (arrows, ▲/▼ markers) may be small: mark them `aria-hidden="true"` — screen readers and `zerp check` skip them. Keep the real information in text. - Captions: use `.caption` or `<figcaption>` — already sized and colored safely. - Direct slide children space themselves automatically (14px rhythm). Do not add margins for ordinary spacing; use an inline margin only to deliberately tighten or widen one specific gap. For a width-capped centered block use `.narrow` (or `margin-inline: auto`; a full `margin: 0 auto` kills the automatic rhythm). - Utility classes reliably override component defaults (component "soft defaults" are declared with `:where()`): `h3.accent` recolors a heading, `.value.red` recolors a stat, `p.xl` enlarges a paragraph, `.year.xl` enlarges a timeline year. Say what you mean with classes instead of inline styles. ## Built-in classes Emphasis: `.accent .ok .warn .danger .blue .green .orange .purple .red .amber .teal` (bold colored text) · `.muted` · `.mono` · `.lg .xl .sm .sub` · `.raised` (elevation shadow for images/cards) Layout: `.cols-2 .cols-3 .cols-4` (equal grids) · `.row` (centered flex row) · `.stack` (column) · `.spread` (space-between) · `.center` (center text — safe on headings, paragraphs, and containers) · `.narrow` (width-capped centered block) · `.grow` · `.slide.top` (top-align a busy slide) Components: - `.card` — surface box; add `.tint-<hue>` for a colored wash, `.edge-<hue>` (or `.edge-ok/.edge-warn/.edge-danger/.edge-accent`) to recolor the border by meaning — works on `.key-thought`, `.timeline .item`, and `.steps` cells too - `.stat` (`.value` + `.label` children) inside `.stat-row` — big numbers; color a value with a hue class (`.value.red`); for stat×operator compositions (`a × b = c`) use `.row` instead so operators center vertically - `.concept` (`.icon` + `.label` children) — definition-slide header: big emoji icon over a shouty accent label; follow with a plain or `.muted` tagline paragraph - `.slide.title` — title-slide recipe: `h1` + `h3` (auto-accent) + `.meta` block for presenter/date - `.compare` — two children side by side with a "vs" divider (`data-vs="→"` to customize) - `.flow` — process row, arrows auto-inserted between children (works for text spans and for `.card` children) - `.steps` — auto-numbered card grid (children: plain divs with `h3` + `p`) - `.timeline` with `.item` (`.year`, `.label`) — milestones - `.key-thought` — boxed takeaway (one per slide max) - `.pill` — inline badge; combine with `.ok/.warn/.danger/.accent` or `.tint-<hue>` - `.interactive-badge` — marks slides that react to ↓/↑ · `.step-hint` — the "↓ do X" affordance line for stepped slides - `.block-label` — small top-left section label - `.img-row` — row of images; wrap each img in a `figure` + `figcaption` for captioned entries · `figure` + `figcaption` for single captioned images · `figure.corner` — pin a small reference figure (poster, book cover) to the slide's top-right, out of the content flow - `table` is styled by default (add `.mono` for numeric tables, `.compact` for dense centered data grids — combine as `class="mono compact"`; `.tint-green`/`.tint-red` on `<tr>` to highlight rows); side-by-side tables go in a `.row`, which lays them out by its gap - `blockquote`, `ol` (numbered takeaways), `ul` (arrow bullets), `code`, `pre`, `kbd` are styled by default ## Slide recipes Title: `# Big title` + `### subtitle` (Markdown). Section divider: `.block-label` + `h1` + `h3`. Bullets: `##` + `-` list. Two-column: `<div class="cols-2">` with text and image/card. Big numbers: `.stat-row` of `.stat`s. Comparison: `.compare` of two `.card`s. Process: `.flow` of spans. Steps: `.steps` of divs. History: `.timeline`. Quote: Markdown `>`. Takeaways: Markdown ordered list. Data: Markdown table. Closing: `# Thanks` + contact in `.muted`. Prefer Markdown for text-first slides; HTML for layout-heavy or interactive slides. ## Theming - Decks are theme-neutral: tokens adapt to dark/light automatically. The presenter picks the default via `zerp build --theme dark|light|system` (default: `system`); viewers override with the sun/moon toggle or the `t` key. The first press pins the opposite scheme (persisted in localStorage); the next press returns to the deck default and clears the pin. - Because both themes ship, anything you author must work in both — that is why hardcoded colors are forbidden. ## Printing and PDF export ```bash zerp print . -o deck.pdf ``` `zerp print` renders the deck directly to a PDF at its design size — no browser print dialog, no manual page-size setup. - Printing emits **one page per slide, in deck order**. Presentation chrome (nav, counter, progress bar, theme toggle, source badge) is never printed. - Steps print in their **final state**: `data-step` content is present, `data-until-step` content is absent. A printed deck shows every reveal. - Print with a **page size equal to the deck's design size** (its `zerp.size`, or 1920×1080 if it declares none) and backgrounds enabled. Pagination is size- and theme-agnostic: one slide fills exactly one page at any page size, in dark or light. - **Page capacity is physical**: content that overflows a slide is clipped at the bottom of the page, not reflowed onto a second page. Fix overflow the same way as on screen (trim content, or top-align with `.slide.top`); `zerp check` still gates it. - If a deck will additionally be exported to PPTX by a downstream pipeline, `llms-pptx.txt` (shipped alongside this file) has the export-specific authoring restrictions; the caller includes it alongside this guide when that target applies. ## Validation loop (required) After authoring or editing slides, ALWAYS run: ```bash zerp check . zerp check . --theme both # checks at the deck's design size by default # add --json for a machine-readable report (per-slide entries include the # source file); --theme dark|light|both and --only category,... narrow it; # pass --size WxH only to check at a size other than the deck's own ``` `zerp check` opens each theme in a real headless browser and needs a Chromium-class one: run `zerp install-browser` once to download a managed Chromium, or set `CHROME_BIN` to an existing Chrome/Chromium. Without one, `zerp check` errors and names the remedy — `zerp install-browser`, or the `CHROME_BIN` path if that is the problem. The whole session (launch, navigation, font activation, probe) is bounded by `--timeout ms` / `ZERP_VERIFY_TIMEOUT_MS`, 20000ms by default — raise it on a slow or loaded host. A timed-out session yields no report, which is a check that did not run, not a check that passed. To skip the per-run browser launch entirely, point `--browser-endpoint url` / `ZERP_BROWSER_ENDPOINT` at an already-running browser (`http(s)://` CDP, `ws(s)://` playwright); check borrows it and never closes it. Fix every `✗` error and `⚠` warning (font too small, text contrast too low, a surface whose background blends into what is behind it, a label sealed inside an `<svg>` where neither can be measured, text rendered by a font the deck does not bundle, one active/visible frame per slide missing or wrong size, page overflow, a print-safe-margin violation, or a browser console error — the report names the slide file, the element, and suggests fixes where there is a fix to suggest). Each line is prefixed with its category (`[contrast]`, `[type-size]`, `[surface]`, `[glyph]`, `[svg-text]`, `[frame]`, `[overflow]`, `[safe-zone]`, `[console]`); `--only` takes a comma-separated subset of those names. Re-run until clean. Items marked `?` (backgrounds with images/gradients) need a manual look. `zerp build` prints the same summary after writing, and — if no browser is available — a one-line notice that the check was skipped and `zerp check` runs it; the build itself still succeeds. **Layout findings are viewport-specific.** Overflow, frame geometry and safe-margin are judged against the checked viewport — a deck's own declared `zerp.size`, or 1920x1080 if it declares none, unless an explicit `--size WxH` overrides it. The summary and the `viewport` field of `--json` state what was checked, including its `source` (`"deck"`, `"default"`, or `"flag"`). A deck designed for a different screen than its declared (or default) size is not wrong when it overflows; declare the right `zerp.size`, or pass `--size WxH` to check against a size other than the deck's own. Contrast, type-size and glyph findings are viewport-independent. `zerp serve` live-reloads the browser on any change under `slides/` — the page returns to the same slide (URL hash) and replays the steps of every slide you had stepped through. Built decks contain no reload client. ## Interaction model `zerp` handles navigation (arrows, space, PageUp/Down, Home/End). Down/Up arrows advance the current slide's step counter and dispatch `slide-next` / `slide-prev` events to it. ### Declarative step reveals (default — no JavaScript) Mark elements with step attributes; the runtime toggles classes as ↓/↑ move the counter: - `data-step="N"` — appears once the counter reaches N (gets `.revealed`) - `data-until-step="N"` — disappears at N (gets `.step-done`) - Space is reserved (visibility, not display), so stepping never reflows a centered slide. - Add `.swap` to exchange same-sized content in place (a label, a glyph): swapped elements collapse instead of reserving, so the counterpart takes the slot. - Highlight-type steps (element always visible, restyled at step N): keep `data-step` and override in deck CSS — `.my-scope [data-step] { visibility: visible; }` plus `.my-scope [data-step].revealed { /* highlight */ }`. - Glyph markers accompanying a highlight (▲ ▼ next to a number): absolutely position them so they never skew centered content, and show them via the parent's `.revealed` (`.my-scope tr.revealed .marker { visibility: visible }`) — no `data-step` needed on the marker itself. ```html <div class="slide"> <div class="interactive-badge">Interactive</div> <h2>Example</h2> <p>Always visible.</p> <p data-step="1">Appears on the first ↓.</p> <div class="key-thought" data-step="2"><p>The payoff.</p></div> <p class="step-hint" data-until-step="2">↓ next</p> </div> ``` ### Scripted slides (escape hatch for real simulations) For state that isn't a fixed reveal sequence (random draws, live counters), use a script (works in `.html` files and raw HTML inside `.md`): ```html <div class="slide"> <div class="interactive-badge">Interactive</div> <h2>Example</h2> <div id="demo-output"></div> <script> (function () { var slide = document.currentScript.closest(".slide"); var step = 0; function render() { slide.querySelector("#demo-output").textContent = "Step " + step; } slide.addEventListener("slide-next", function () { if (step < 3) { step++; render(); } }); slide.addEventListener("slide-prev", function () { if (step > 0) { step--; render(); } }); render(); })(); </script> </div> ``` Rules: scope queries to `document.currentScript.closest(".slide")`; keep state in the closure; make `slide-prev` reverse state; no global key listeners; no external dependencies. Build static markup in HTML and have the script toggle classes / set `textContent` — do not assemble HTML strings with inline styles (static markup is what `zerp check` can verify). When a script must set a color, use a class or a token: `el.className = "value green"`. ## Custom CSS policy (last resort) 1. Reach for built-in classes and styled elements first — they cover title, list, column, stat, comparison, flow, step, timeline, quote, table, and image slides. 2. If a layout truly needs custom CSS, put a `<style>` inside the slide file, use ONLY `var(--zerp-*)` tokens, keep text at 1em+. 3. A `<style>` block is document-global. For deck-wide styles the convention is a style-only file sorted first (e.g. `slides/00-styles.html` containing just a `<style>` — it contributes no slide). 4. Re-run `zerp check` — it judges the browser's own computed styles, so custom CSS is checked exactly like built-in styles regardless of selector shape, specificity, `@media` blocks, or `!important`; nothing is skipped. 5. If the layout changes, run `zerp check . --theme both` with Chrome or Chromium available. This catches display overrides and wrapper/viewport regressions that static checking cannot see. ## Diagrams and inline SVG Inline `<svg>` is the right tool for the shapes of a diagram — paths, arcs, connectors, fills, wheels, boards. It is the wrong place for the words. **Draw with SVG; label with HTML positioned over it.** - `zerp check` audits HTML text. An `<svg><text>` label is excluded from element-level judging rather than mismeasured: Chrome still resolves a computed `color` for it (inherited from the surrounding HTML) even though the glyph is painted with `fill`, and computed `font-size` is in the svg's own user-unit space, unscaled by `viewBox`, so neither value describes what actually got painted. `zerp check` emits a separate `[svg-text]` `⚠` warning for any non-`aria-hidden` `<svg>` containing `<text>` instead. The one gap this leaves: HTML placed inside `<foreignObject>` gets no compensating warning, so keep labels as siblings of the `<svg>`, not nested inside it. - Export and rasterization pipelines treat an SVG as its own document and do not reliably hand it the deck's inlined fonts. HTML text keeps Montserrat and Roboto Mono everywhere; SVG text re-resolves to whatever the consuming machine happens to have. - Once the words live in HTML the graphic is decoration: mark the `<svg>` `aria-hidden="true"`, and both screen readers and `zerp check` skip it. - Numerals that are part of a depicted object rather than slide copy — a roulette wheel's pocket numbers, a die's pips, a keyboard's legends — are drawing, and stay in the SVG. The test is whether a reader who cannot see them loses information: if they would, that information belongs in HTML next to the graphic, and the `<svg>` then goes `aria-hidden`. ```html <div class="slide"> <h2>Two pockets</h2> <div class="wheel"> <svg viewBox="0 0 240 120" aria-hidden="true"> <circle cx="60" cy="60" r="46" fill="var(--zerp-red-solid)" /> <circle cx="180" cy="60" r="46" fill="var(--zerp-green-solid)" /> </svg> <span class="pocket left">18 red</span> <span class="pocket right">1 zero</span> </div> <style> .wheel { position: relative; width: fit-content; margin-inline: auto; } .wheel .pocket { position: absolute; top: 50px; font-weight: 700; color: var(--zerp-on-solid); } .wheel .left { left: 22px; } .wheel .right { left: 148px; } </style> </div> ``` A script that builds a diagram at runtime follows the same rule: emit the shapes into the SVG and the labels into sibling HTML, so the words stay checkable static markup. ## Characters and glyph coverage A built deck carries its fonts inside itself, as inlined subsets of Montserrat and Roboto Mono plus a one-glyph face for `→`. That is what makes it a single offline file, and it is also a hard edge: **a character no bundled subset covers is drawn by whatever font the viewing machine falls back to** — a different shape, weight and width on every OS, and re-resolved again by the reader's machine once the deck is exported to a format whose text runs carry one font face. Latin, Latin-Extended, Cyrillic and Vietnamese are available to both the body and display families by default; Greek is available to Roboto Mono only. `zerp check` finds fallback text by asking the browser itself what font painted each glyph (Chrome DevTools Protocol `CSS.getPlatformFontsForNode`), not by consulting a static coverage table. Since zerp inlines every font it ships as an `@font-face`, any font the browser reports as not custom (`isCustomFont: false`) means it fell back — that is a direct answer, not an inference from a `unicode-range`. The finding is one `[glyph]` `⚠` per element, naming the slide, the element and the fallback family it fell back to. This is per element, not per deck or per font role: Greek is available to Roboto Mono and not to Montserrat, so `Δ` in a `<code>` block is fine while the same character in an `<h1>` is not. Bundling a subset for one role does not cover another role. - Latin, Latin-Extended and Cyrillic text is covered. Common typography is covered: `— – … ‘ ’ “ ” · × − ↑ ↓ € ™`. - Mathematical and geometric symbols mostly are not: `≈ ≠ ≤ ≥ ▲ ▼ ◆ ★ ✓ ✗`. Say `~`, `<=`, `+`/`−`, or use words. - `→` is covered everywhere, because zerp bundles a face for it and its own `ul` markers use it. - Generated content (`::before`/`::after`) is judged for glyph coverage too — a deck that overrides a framework marker's glyph can get a finding for text the browser never actually draws — but not for contrast or type-size: the probe records no pseudo-element color or size, and judging generated content against the originating element's would describe a color/size pair the browser never painted together. - `<text>` inside inline SVG is excluded from glyph judging along with contrast, type-size and surface (see "Diagrams and inline SVG" for why); the separate `[svg-text]` warning still fires for any non-`aria-hidden` `<svg>` containing `<text>`. - Text a slide script generates at runtime is invisible to the check — the probe reads the rendered page as authored, before any script mutation the reader wouldn't already see reflected there at measurement time, the same reason subset selection cannot see it either (below). - An element whose stack names a family zerp does not bundle (`font-family: Georgia, serif`, your own `@font-face`) is judged the same way as any other: if the browser reports a non-custom font painting it, that is still a fallback and still gets flagged. Naming a system font on purpose does not opt text out of the warning — the guarantee this section protects is that a build ships every font its own text needs. ### Limits of the glyph check (know these before treating "clean" as "every glyph is bundled") - **Emoji are exempt**, deliberately: every platform draws them from its own colour font by design, so a system font drawing exactly an element's exempt characters raises nothing there. This errs toward under-reporting, never over-reporting: a ZWJ sequence like `👩‍👩‍👦` counts as three exempt (`Extended_Pictographic`) characters even though it draws one glyph, and generated-content alt text such as `content: "→" / "arrow"` counts its `"arrow"` alternative as exempt text too — both directions can only suppress a real finding, never invent one. - **Attribution is per element, not per codepoint.** The browser's font-fact count (`CSS.getPlatformFontsForNode`) is a deduplicated glyph-set count for a subtree, not a sum of characters, so where a parent's own fallback glyphs are a subset of a descendant's in the same fallback family, the finding lands on the descendant, not the parent. The slide is still flagged — only the pointer to "which element" is coarser than exact in that case. - **`<svg>` subtrees are excluded from glyph, contrast, type-size and surface judging alike** (see above and "Diagrams and inline SVG"). HTML placed inside `<foreignObject>` is the one case with no compensating warning at all. - **Generated content is judged for glyph coverage only**, never contrast or type-size, for the reason given above. - **Runtime-generated text is invisible**, to both subset selection and the check, for the reason given above — put a sample of expected runtime characters in static markup if you need either to see them. ## Deck configuration A deck needs no configuration. An optional `zerp` key in **its own package.json** covers the two things it cannot express any other way: which typefaces it is set in, and what design size it is authored for. Everything else stays zero-config. ### Choosing other typefaces ```json { "dependencies": { "@fontsource/bebas-neue": "^5", "@fontsource/inter": "^5", "@fontsource/jetbrains-mono": "^5" }, "zerp": { "fonts": { "display": { "family": "Bebas Neue", "weights": ["400"] }, "body": { "family": "Inter" }, "mono": { "family": "JetBrains Mono", "weights": ["400", "700"] } } } } ``` - `family` is the name the font declares, exactly as you would write it in `font-family`; zerp compares it with the package and errors if they disagree. - `fontsourcePackage` is optional and defaults to `@fontsource/` + the slugified family. **The deck installs that package itself** (`pnpm add @fontsource/inter`) — zerp resolves it from the deck's `node_modules`, and a package it cannot find is a build error that names the install command. - `weights` is optional. It defaults to what zerp's styles use — body `400 600 700 900 400-italic`, mono `400 700` — and a weight the family does not ship is simply not emitted. - `display` sets the face for `h1`. Unset, it follows `body` — family, package and weights — so a deck that names only `body` gets that family everywhere. - `mono` unset stays Roboto Mono; it never follows `body`, because the nav, code, tables and labels need real monospace metrics. - The display face applies to `h1` only. Move others onto it from your own stylesheet — `h2 { font-family: var(--zerp-font-display) }` — or off it with `h1 { font-family: var(--zerp-font-body) }`; zerp's rule carries zero specificity so a plain element selector wins. - All three roles keep everything else: the `→` face rides along, and subsets are still chosen by the deck's text, which is what makes a CJK family (`@fontsource/noto-sans-jp`) possible at all — it is carried a few ranges at a time. - Anything outside the Google Fonts directory, or a family that must not be bundled, is out of scope: this is a swap, not a font pipeline. **A built deck carries only the subsets its own text needs**, so a latin deck ships no Cyrillic and a deck that types one `№` ships the Cyrillic subset that covers it. This is what keeps a single-file deck small, and it has one consequence for scripts: string literals inside a slide `<script>` do count towards the choice (a script that prints `Ж` still pulls Cyrillic in), but characters a script derives at runtime — from a fetch, a computation, `String.fromCharCode` — appear nowhere in the source and cannot. This is the same reason the existing rule says to build static markup and have the script toggle classes or set `textContent`: if a script can produce characters that appear nowhere in the source, put a sample of them in static markup (a legend, a caption, a `hidden` element) so both the subset selection and this check can see them. ### Design size A deck renders at a fixed design canvas, declared with `"zerp": { "size": "WxH" }` in the deck's own `package.json`: ```json { "zerp": { "size": "1920x1080" } } ``` - Unset, the design size is `1920x1080`. This is what a deck with no `zerp` key gets. - The design size controls three things: the stage every slide frame is fixed at, the default viewport `zerp check` uses when `--size` is not passed, and the PDF page size `zerp print` produces. - The runtime scales the whole stage to fit the real browser window (letterboxed, centered) so the deck always fills the screen without reflowing; layout inside a slide never changes with window size. - Author proportional CSS with `cqw`/`cqh` (percent of the stage's design width/height), not `vw`/`vh`. Viewport units read the real window, which is wrong once the stage is scaled — `60cqh` always means 60% of the design height, at any window size; `60vh` does not. `cqw`/`cqh` work because the stage sets `container-type: size`. ## What to avoid - No full HTML documents inside slide files; no duplicated framework CSS or runtime. - No hardcoded colors anywhere (including inline styles and scripts). Sole exemption: colors of depicted real-world objects (a playing card's white face, a roulette pocket's black) may stay literal — they represent the object and must not flip with the theme. - No text below 1em; no `--zerp-faint` for text; no `.sm .muted` combos. - No `<text>` inside inline `<svg>` — draw the shapes in SVG and position HTML labels over it (see "Diagrams and inline SVG"). - No `<div class="slide">` wrappers inside Markdown files (added automatically). - Do not override the framework-owned `[data-zerp-slide]` visibility rules or author those `data-zerp-*` attributes yourself. One exception: put `data-zerp-bleed` on a top-level slide element that intentionally runs to the page edge (a full-bleed band or backdrop), so print-safe-margin checks skip it. - Do not recreate navigation; do not edit generated `index.html`. ## Validation commands In a consumer deck: `zerp check .`, then `zerp serve .` / `zerp build .`.

` blocks. Each `.md` file is auto-wrapped; separate multiple slides with `---` on its own line. - The page `` is derived from the first slide's highest-level heading (h1 before h2, regardless of order); style/script-only files contribute no slides and are skipped. Override with the `title` build option; falls back to the deck folder name. - A deck renders at a design size — 1920×1080 by default, or whatever it declares (see "Deck configuration" below) — and scales to fit the real window at runtime. Author against that fixed canvas; never against the actual viewport. - Never hand-edit the generated `index.html`. ## Slide numbering **"Slide N" always means the 1-based deck position** — the number the runtime counter shows to presenter and audience. File name prefixes only order files; a file may contain several slides, so a prefix is NOT a slide number. The runtime counter, the URL hash (`#N`), `zerp check` findings, and `zerp slides` all use deck positions. - Before editing "slide N", run `zerp slides .` (add `--json` for tooling): it prints each slide's position, source file, in-file ordinal, and title. Confirm the target by its heading. - Every composed inner `.slide` carries source-tracing attributes: `data-zerp-src` (source file), `data-zerp-src-slide` (`i/n` within that file), `data-zerp-index` (deck position). It is wrapped in a framework-owned `<div data-zerp-slide>` frame; the frame owns visibility and the inner `.slide` owns layout. - Treat `data-zerp-slide`, `data-zerp-slide-active`, and their display rules as reserved framework state. Put custom layout rules on `.slide` or a class on the inner root, not on the frame. - In a running deck, press `s` to toggle a source badge showing the active slide's position and source file. ## Design system — colors Colors come from CSS custom properties (design tokens). The framework ships a dark and a light theme; tokens flip automatically. **Never hardcode hex/rgb colors. Never invent new colors. Pick tokens by meaning.** Neutrals: - `--zerp-bg` page background · `--zerp-surface` cards/panels · `--zerp-border` borders - `--zerp-text` body text · `--zerp-muted` secondary text — use at body size (≥1.25em/20px), or at smaller sizes only with weight 700 - `--zerp-faint` decorative glyphs ONLY (arrows, dividers) — **never use for text** Accent hues (each in 4 roles): `blue green orange purple red amber teal` - `--zerp-<hue>` — colored text on the page/surface (use at body size or larger) - `--zerp-<hue>-solid` + `--zerp-on-solid` — filled backgrounds (badges, fills) and text on them - `--zerp-<hue>-tint` + `--zerp-<hue>-on-tint` — subtle washes (highlight cards/rows) and text on them Semantic aliases: `--zerp-accent` (blue), `--zerp-ok` (green), `--zerp-warn` (amber), `--zerp-danger` (red). Prefer semantic names when the color carries meaning; hue names for categorical coding. ## Typography rules - Body text is 1.25em (~20px). **Never set text below 1em; `.sm` (0.9×) is the only sanctioned shrink.** Prefer trimming content over shrinking text. - `.sm` is for inline spans within body text; on a bare paragraph it lands below the 16px floor and `zerp check` will flag it. - Do not combine `.sm` with `.muted` — small muted text fails contrast. - For a detail line under a heading or bold statement use `.sub` (1em, bold, muted — safe by construction). This is the idiom for the second line of a `.key-thought` and for card sub-text. - Colored text classes are bold by design (emphasis). Do not fight the weight. - Decorative glyphs (arrows, ▲/▼ markers) may be small: mark them `aria-hidden="true"` — screen readers and `zerp check` skip them. Keep the real information in text. - Captions: use `.caption` or `<figcaption>` — already sized and colored safely. - Direct slide children space themselves automatically (14px rhythm). Do not add margins for ordinary spacing; use an inline margin only to deliberately tighten or widen one specific gap. For a width-capped centered block use `.narrow` (or `margin-inline: auto`; a full `margin: 0 auto` kills the automatic rhythm). - Utility classes reliably override component defaults (component "soft defaults" are declared with `:where()`): `h3.accent` recolors a heading, `.value.red` recolors a stat, `p.xl` enlarges a paragraph, `.year.xl` enlarges a timeline year. Say what you mean with classes instead of inline styles. ## Built-in classes Emphasis: `.accent .ok .warn .danger .blue .green .orange .purple .red .amber .teal` (bold colored text) · `.muted` · `.mono` · `.lg .xl .sm .sub` · `.raised` (elevation shadow for images/cards) Layout: `.cols-2 .cols-3 .cols-4` (equal grids) · `.row` (centered flex row) · `.stack` (column) · `.spread` (space-between) · `.center` (center text — safe on headings, paragraphs, and containers) · `.narrow` (width-capped centered block) · `.grow` · `.slide.top` (top-align a busy slide) Components: - `.card` — surface box; add `.tint-<hue>` for a colored wash, `.edge-<hue>` (or `.edge-ok/.edge-warn/.edge-danger/.edge-accent`) to recolor the border by meaning — works on `.key-thought`, `.timeline .item`, and `.steps` cells too - `.stat` (`.value` + `.label` children) inside `.stat-row` — big numbers; color a value with a hue class (`.value.red`); for stat×operator compositions (`a × b = c`) use `.row` instead so operators center vertically - `.concept` (`.icon` + `.label` children) — definition-slide header: big emoji icon over a shouty accent label; follow with a plain or `.muted` tagline paragraph - `.slide.title` — title-slide recipe: `h1` + `h3` (auto-accent) + `.meta` block for presenter/date - `.compare` — two children side by side with a "vs" divider (`data-vs="→"` to customize) - `.flow` — process row, arrows auto-inserted between children (works for text spans and for `.card` children) - `.steps` — auto-numbered card grid (children: plain divs with `h3` + `p`) - `.timeline` with `.item` (`.year`, `.label`) — milestones - `.key-thought` — boxed takeaway (one per slide max) - `.pill` — inline badge; combine with `.ok/.warn/.danger/.accent` or `.tint-<hue>` - `.interactive-badge` — marks slides that react to ↓/↑ · `.step-hint` — the "↓ do X" affordance line for stepped slides - `.block-label` — small top-left section label - `.img-row` — row of images; wrap each img in a `figure` + `figcaption` for captioned entries · `figure` + `figcaption` for single captioned images · `figure.corner` — pin a small reference figure (poster, book cover) to the slide's top-right, out of the content flow - `table` is styled by default (add `.mono` for numeric tables, `.compact` for dense centered data grids — combine as `class="mono compact"`; `.tint-green`/`.tint-red` on `<tr>` to highlight rows); side-by-side tables go in a `.row`, which lays them out by its gap - `blockquote`, `ol` (numbered takeaways), `ul` (arrow bullets), `code`, `pre`, `kbd` are styled by default ## Slide recipes Title: `# Big title` + `### subtitle` (Markdown). Section divider: `.block-label` + `h1` + `h3`. Bullets: `##` + `-` list. Two-column: `<div class="cols-2">` with text and image/card. Big numbers: `.stat-row` of `.stat`s. Comparison: `.compare` of two `.card`s. Process: `.flow` of spans. Steps: `.steps` of divs. History: `.timeline`. Quote: Markdown `>`. Takeaways: Markdown ordered list. Data: Markdown table. Closing: `# Thanks` + contact in `.muted`. Prefer Markdown for text-first slides; HTML for layout-heavy or interactive slides. ## Theming - Decks are theme-neutral: tokens adapt to dark/light automatically. The presenter picks the default via `zerp build --theme dark|light|system` (default: `system`); viewers override with the sun/moon toggle or the `t` key. The first press pins the opposite scheme (persisted in localStorage); the next press returns to the deck default and clears the pin. - Because both themes ship, anything you author must work in both — that is why hardcoded colors are forbidden. ## Printing and PDF export ```bash zerp print . -o deck.pdf ``` `zerp print` renders the deck directly to a PDF at its design size — no browser print dialog, no manual page-size setup. - Printing emits **one page per slide, in deck order**. Presentation chrome (nav, counter, progress bar, theme toggle, source badge) is never printed. - Steps print in their **final state**: `data-step` content is present, `data-until-step` content is absent. A printed deck shows every reveal. - Print with a **page size equal to the deck's design size** (its `zerp.size`, or 1920×1080 if it declares none) and backgrounds enabled. Pagination is size- and theme-agnostic: one slide fills exactly one page at any page size, in dark or light. - **Page capacity is physical**: content that overflows a slide is clipped at the bottom of the page, not reflowed onto a second page. Fix overflow the same way as on screen (trim content, or top-align with `.slide.top`); `zerp check` still gates it. - If a deck will additionally be exported to PPTX by a downstream pipeline, `llms-pptx.txt` (shipped alongside this file) has the export-specific authoring restrictions; the caller includes it alongside this guide when that target applies. ## Validation loop (required) After authoring or editing slides, ALWAYS run: ```bash zerp check . zerp check . --theme both # checks at the deck's design size by default # add --json for a machine-readable report (per-slide entries include the # source file); --theme dark|light|both and --only category,... narrow it; # pass --size WxH only to check at a size other than the deck's own ``` `zerp check` opens each theme in a real headless browser and needs a Chromium-class one: run `zerp install-browser` once to download a managed Chromium, or set `CHROME_BIN` to an existing Chrome/Chromium. Without one, `zerp check` errors and names the remedy — `zerp install-browser`, or the `CHROME_BIN` path if that is the problem. The whole session (launch, navigation, font activation, probe) is bounded by `--timeout ms` / `ZERP_VERIFY_TIMEOUT_MS`, 20000ms by default — raise it on a slow or loaded host. A timed-out session yields no report, which is a check that did not run, not a check that passed. To skip the per-run browser launch entirely, point `--browser-endpoint url` / `ZERP_BROWSER_ENDPOINT` at an already-running browser (`http(s)://` CDP, `ws(s)://` playwright); check borrows it and never closes it. Fix every `✗` error and `⚠` warning (font too small, text contrast too low, a surface whose background blends into what is behind it, a label sealed inside an `<svg>` where neither can be measured, text rendered by a font the deck does not bundle, one active/visible frame per slide missing or wrong size, page overflow, a print-safe-margin violation, or a browser console error — the report names the slide file, the element, and suggests fixes where there is a fix to suggest). Each line is prefixed with its category (`[contrast]`, `[type-size]`, `[surface]`, `[glyph]`, `[svg-text]`, `[frame]`, `[overflow]`, `[safe-zone]`, `[console]`); `--only` takes a comma-separated subset of those names. Re-run until clean. Items marked `?` (backgrounds with images/gradients) need a manual look. `zerp build` prints the same summary after writing, and — if no browser is available — a one-line notice that the check was skipped and `zerp check` runs it; the build itself still succeeds. **Layout findings are viewport-specific.** Overflow, frame geometry and safe-margin are judged against the checked viewport — a deck's own declared `zerp.size`, or 1920x1080 if it declares none, unless an explicit `--size WxH` overrides it. The summary and the `viewport` field of `--json` state what was checked, including its `source` (`"deck"`, `"default"`, or `"flag"`). A deck designed for a different screen than its declared (or default) size is not wrong when it overflows; declare the right `zerp.size`, or pass `--size WxH` to check against a size other than the deck's own. Contrast, type-size and glyph findings are viewport-independent. `zerp serve` live-reloads the browser on any change under `slides/` — the page returns to the same slide (URL hash) and replays the steps of every slide you had stepped through. Built decks contain no reload client. ## Interaction model `zerp` handles navigation (arrows, space, PageUp/Down, Home/End). Down/Up arrows advance the current slide's step counter and dispatch `slide-next` / `slide-prev` events to it. ### Declarative step reveals (default — no JavaScript) Mark elements with step attributes; the runtime toggles classes as ↓/↑ move the counter: - `data-step="N"` — appears once the counter reaches N (gets `.revealed`) - `data-until-step="N"` — disappears at N (gets `.step-done`) - Space is reserved (visibility, not display), so stepping never reflows a centered slide. - Add `.swap` to exchange same-sized content in place (a label, a glyph): swapped elements collapse instead of reserving, so the counterpart takes the slot. - Highlight-type steps (element always visible, restyled at step N): keep `data-step` and override in deck CSS — `.my-scope [data-step] { visibility: visible; }` plus `.my-scope [data-step].revealed { /* highlight */ }`. - Glyph markers accompanying a highlight (▲ ▼ next to a number): absolutely position them so they never skew centered content, and show them via the parent's `.revealed` (`.my-scope tr.revealed .marker { visibility: visible }`) — no `data-step` needed on the marker itself. ```html <div class="slide"> <div class="interactive-badge">Interactive</div> <h2>Example</h2> <p>Always visible.</p> <p data-step="1">Appears on the first ↓.</p> <div class="key-thought" data-step="2"><p>The payoff.</p></div> <p class="step-hint" data-until-step="2">↓ next</p> </div> ``` ### Scripted slides (escape hatch for real simulations) For state that isn't a fixed reveal sequence (random draws, live counters), use a script (works in `.html` files and raw HTML inside `.md`): ```html <div class="slide"> <div class="interactive-badge">Interactive</div> <h2>Example</h2> <div id="demo-output"></div> <script> (function () { var slide = document.currentScript.closest(".slide"); var step = 0; function render() { slide.querySelector("#demo-output").textContent = "Step " + step; } slide.addEventListener("slide-next", function () { if (step < 3) { step++; render(); } }); slide.addEventListener("slide-prev", function () { if (step > 0) { step--; render(); } }); render(); })(); </script> </div> ``` Rules: scope queries to `document.currentScript.closest(".slide")`; keep state in the closure; make `slide-prev` reverse state; no global key listeners; no external dependencies. Build static markup in HTML and have the script toggle classes / set `textContent` — do not assemble HTML strings with inline styles (static markup is what `zerp check` can verify). When a script must set a color, use a class or a token: `el.className = "value green"`. ## Custom CSS policy (last resort) 1. Reach for built-in classes and styled elements first — they cover title, list, column, stat, comparison, flow, step, timeline, quote, table, and image slides. 2. If a layout truly needs custom CSS, put a `<style>` inside the slide file, use ONLY `var(--zerp-*)` tokens, keep text at 1em+. 3. A `<style>` block is document-global. For deck-wide styles the convention is a style-only file sorted first (e.g. `slides/00-styles.html` containing just a `<style>` — it contributes no slide). 4. Re-run `zerp check` — it judges the browser's own computed styles, so custom CSS is checked exactly like built-in styles regardless of selector shape, specificity, `@media` blocks, or `!important`; nothing is skipped. 5. If the layout changes, run `zerp check . --theme both` with Chrome or Chromium available. This catches display overrides and wrapper/viewport regressions that static checking cannot see. ## Diagrams and inline SVG Inline `<svg>` is the right tool for the shapes of a diagram — paths, arcs, connectors, fills, wheels, boards. It is the wrong place for the words. **Draw with SVG; label with HTML positioned over it.** - `zerp check` audits HTML text. An `<svg><text>` label is excluded from element-level judging rather than mismeasured: Chrome still resolves a computed `color` for it (inherited from the surrounding HTML) even though the glyph is painted with `fill`, and computed `font-size` is in the svg's own user-unit space, unscaled by `viewBox`, so neither value describes what actually got painted. `zerp check` emits a separate `[svg-text]` `⚠` warning for any non-`aria-hidden` `<svg>` containing `<text>` instead. The one gap this leaves: HTML placed inside `<foreignObject>` gets no compensating warning, so keep labels as siblings of the `<svg>`, not nested inside it. - Export and rasterization pipelines treat an SVG as its own document and do not reliably hand it the deck's inlined fonts. HTML text keeps Montserrat and Roboto Mono everywhere; SVG text re-resolves to whatever the consuming machine happens to have. - Once the words live in HTML the graphic is decoration: mark the `<svg>` `aria-hidden="true"`, and both screen readers and `zerp check` skip it. - Numerals that are part of a depicted object rather than slide copy — a roulette wheel's pocket numbers, a die's pips, a keyboard's legends — are drawing, and stay in the SVG. The test is whether a reader who cannot see them loses information: if they would, that information belongs in HTML next to the graphic, and the `<svg>` then goes `aria-hidden`. ```html <div class="slide"> <h2>Two pockets</h2> <div class="wheel"> <svg viewBox="0 0 240 120" aria-hidden="true"> <circle cx="60" cy="60" r="46" fill="var(--zerp-red-solid)" /> <circle cx="180" cy="60" r="46" fill="var(--zerp-green-solid)" /> </svg> <span class="pocket left">18 red</span> <span class="pocket right">1 zero</span> </div> <style> .wheel { position: relative; width: fit-content; margin-inline: auto; } .wheel .pocket { position: absolute; top: 50px; font-weight: 700; color: var(--zerp-on-solid); } .wheel .left { left: 22px; } .wheel .right { left: 148px; } </style> </div> ``` A script that builds a diagram at runtime follows the same rule: emit the shapes into the SVG and the labels into sibling HTML, so the words stay checkable static markup. ## Characters and glyph coverage A built deck carries its fonts inside itself, as inlined subsets of Montserrat and Roboto Mono plus a one-glyph face for `→`. That is what makes it a single offline file, and it is also a hard edge: **a character no bundled subset covers is drawn by whatever font the viewing machine falls back to** — a different shape, weight and width on every OS, and re-resolved again by the reader's machine once the deck is exported to a format whose text runs carry one font face. Latin, Latin-Extended, Cyrillic and Vietnamese are available to both the body and display families by default; Greek is available to Roboto Mono only. `zerp check` finds fallback text by asking the browser itself what font painted each glyph (Chrome DevTools Protocol `CSS.getPlatformFontsForNode`), not by consulting a static coverage table. Since zerp inlines every font it ships as an `@font-face`, any font the browser reports as not custom (`isCustomFont: false`) means it fell back — that is a direct answer, not an inference from a `unicode-range`. The finding is one `[glyph]` `⚠` per element, naming the slide, the element and the fallback family it fell back to. This is per element, not per deck or per font role: Greek is available to Roboto Mono and not to Montserrat, so `Δ` in a `<code>` block is fine while the same character in an `<h1>` is not. Bundling a subset for one role does not cover another role. - Latin, Latin-Extended and Cyrillic text is covered. Common typography is covered: `— – … ‘ ’ “ ” · × − ↑ ↓ € ™`. - Mathematical and geometric symbols mostly are not: `≈ ≠ ≤ ≥ ▲ ▼ ◆ ★ ✓ ✗`. Say `~`, `<=`, `+`/`−`, or use words. - `→` is covered everywhere, because zerp bundles a face for it and its own `ul` markers use it. - Generated content (`::before`/`::after`) is judged for glyph coverage too — a deck that overrides a framework marker's glyph can get a finding for text the browser never actually draws — but not for contrast or type-size: the probe records no pseudo-element color or size, and judging generated content against the originating element's would describe a color/size pair the browser never painted together. - `<text>` inside inline SVG is excluded from glyph judging along with contrast, type-size and surface (see "Diagrams and inline SVG" for why); the separate `[svg-text]` warning still fires for any non-`aria-hidden` `<svg>` containing `<text>`. - Text a slide script generates at runtime is invisible to the check — the probe reads the rendered page as authored, before any script mutation the reader wouldn't already see reflected there at measurement time, the same reason subset selection cannot see it either (below). - An element whose stack names a family zerp does not bundle (`font-family: Georgia, serif`, your own `@font-face`) is judged the same way as any other: if the browser reports a non-custom font painting it, that is still a fallback and still gets flagged. Naming a system font on purpose does not opt text out of the warning — the guarantee this section protects is that a build ships every font its own text needs. ### Limits of the glyph check (know these before treating "clean" as "every glyph is bundled") - **Emoji are exempt**, deliberately: every platform draws them from its own colour font by design, so a system font drawing exactly an element's exempt characters raises nothing there. This errs toward under-reporting, never over-reporting: a ZWJ sequence like `👩‍👩‍👦` counts as three exempt (`Extended_Pictographic`) characters even though it draws one glyph, and generated-content alt text such as `content: "→" / "arrow"` counts its `"arrow"` alternative as exempt text too — both directions can only suppress a real finding, never invent one. - **Attribution is per element, not per codepoint.** The browser's font-fact count (`CSS.getPlatformFontsForNode`) is a deduplicated glyph-set count for a subtree, not a sum of characters, so where a parent's own fallback glyphs are a subset of a descendant's in the same fallback family, the finding lands on the descendant, not the parent. The slide is still flagged — only the pointer to "which element" is coarser than exact in that case. - **`<svg>` subtrees are excluded from glyph, contrast, type-size and surface judging alike** (see above and "Diagrams and inline SVG"). HTML placed inside `<foreignObject>` is the one case with no compensating warning at all. - **Generated content is judged for glyph coverage only**, never contrast or type-size, for the reason given above. - **Runtime-generated text is invisible**, to both subset selection and the check, for the reason given above — put a sample of expected runtime characters in static markup if you need either to see them. ## Deck configuration A deck needs no configuration. An optional `zerp` key in **its own package.json** covers the two things it cannot express any other way: which typefaces it is set in, and what design size it is authored for. Everything else stays zero-config. ### Choosing other typefaces ```json { "dependencies": { "@fontsource/bebas-neue": "^5", "@fontsource/inter": "^5", "@fontsource/jetbrains-mono": "^5" }, "zerp": { "fonts": { "display": { "family": "Bebas Neue", "weights": ["400"] }, "body": { "family": "Inter" }, "mono": { "family": "JetBrains Mono", "weights": ["400", "700"] } } } } ``` - `family` is the name the font declares, exactly as you would write it in `font-family`; zerp compares it with the package and errors if they disagree. - `fontsourcePackage` is optional and defaults to `@fontsource/` + the slugified family. **The deck installs that package itself** (`pnpm add @fontsource/inter`) — zerp resolves it from the deck's `node_modules`, and a package it cannot find is a build error that names the install command. - `weights` is optional. It defaults to what zerp's styles use — body `400 600 700 900 400-italic`, mono `400 700` — and a weight the family does not ship is simply not emitted. - `display` sets the face for `h1`. Unset, it follows `body` — family, package and weights — so a deck that names only `body` gets that family everywhere. - `mono` unset stays Roboto Mono; it never follows `body`, because the nav, code, tables and labels need real monospace metrics. - The display face applies to `h1` only. Move others onto it from your own stylesheet — `h2 { font-family: var(--zerp-font-display) }` — or off it with `h1 { font-family: var(--zerp-font-body) }`; zerp's rule carries zero specificity so a plain element selector wins. - All three roles keep everything else: the `→` face rides along, and subsets are still chosen by the deck's text, which is what makes a CJK family (`@fontsource/noto-sans-jp`) possible at all — it is carried a few ranges at a time. - Anything outside the Google Fonts directory, or a family that must not be bundled, is out of scope: this is a swap, not a font pipeline. **A built deck carries only the subsets its own text needs**, so a latin deck ships no Cyrillic and a deck that types one `№` ships the Cyrillic subset that covers it. This is what keeps a single-file deck small, and it has one consequence for scripts: string literals inside a slide `<script>` do count towards the choice (a script that prints `Ж` still pulls Cyrillic in), but characters a script derives at runtime — from a fetch, a computation, `String.fromCharCode` — appear nowhere in the source and cannot. This is the same reason the existing rule says to build static markup and have the script toggle classes or set `textContent`: if a script can produce characters that appear nowhere in the source, put a sample of them in static markup (a legend, a caption, a `hidden` element) so both the subset selection and this check can see them. ### Design size A deck renders at a fixed design canvas, declared with `"zerp": { "size": "WxH" }` in the deck's own `package.json`: ```json { "zerp": { "size": "1920x1080" } } ``` - Unset, the design size is `1920x1080`. This is what a deck with no `zerp` key gets. - The design size controls three things: the stage every slide frame is fixed at, the default viewport `zerp check` uses when `--size` is not passed, and the PDF page size `zerp print` produces. - The runtime scales the whole stage to fit the real browser window (letterboxed, centered) so the deck always fills the screen without reflowing; layout inside a slide never changes with window size. - Author proportional CSS with `cqw`/`cqh` (percent of the stage's design width/height), not `vw`/`vh`. Viewport units read the real window, which is wrong once the stage is scaled — `60cqh` always means 60% of the design height, at any window size; `60vh` does not. `cqw`/`cqh` work because the stage sets `container-type: size`. ## What to avoid - No full HTML documents inside slide files; no duplicated framework CSS or runtime. - No hardcoded colors anywhere (including inline styles and scripts). Sole exemption: colors of depicted real-world objects (a playing card's white face, a roulette pocket's black) may stay literal — they represent the object and must not flip with the theme. - No text below 1em; no `--zerp-faint` for text; no `.sm .muted` combos. - No `<text>` inside inline `<svg>` — draw the shapes in SVG and position HTML labels over it (see "Diagrams and inline SVG"). - No `<div class="slide">` wrappers inside Markdown files (added automatically). - Do not override the framework-owned `[data-zerp-slide]` visibility rules or author those `data-zerp-*` attributes yourself. One exception: put `data-zerp-bleed` on a top-level slide element that intentionally runs to the page edge (a full-bleed band or backdrop), so print-safe-margin checks skip it. - Do not recreate navigation; do not edit generated `index.html`. ## Validation commands In a consumer deck: `zerp check .`, then `zerp serve .` / `zerp build .`.