slides-grab 1.3.0 → 1.4.0

package/skills/slides-grab/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: slides-grab
-description: End-to-end presentation workflow for Codex. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF and per-slide PNG are preferred; PPTX/Figma export is experimental / unstable.
+description: End-to-end presentation workflow usable in Codex and Claude Code. Use when making a full presentation from scratch — planning, designing slides, editing, and exporting. PDF and per-slide PNG are preferred; PPTX/Figma export is experimental / unstable.
 metadata:
   short-description: Full pipeline from topic to PDF/PNG + experimental / unstable PPTX/Figma export
 ---
 
-# slides-grab Skill (Codex) - Full Workflow Orchestrator
+# slides-grab Skill - Full Workflow Orchestrator
 
 Guides you through the complete presentation pipeline from topic to exported file.
 
@@ -35,13 +35,16 @@ Use the installed **slides-grab-design** skill.
 5. If validation fails, automatically fix the slide HTML/CSS until validation passes.
 6. For bespoke slide imagery, use `slides-grab image --prompt "<prompt>" --slides-dir <path>` so the default god-tibo-imagen provider (reuses local Codex ChatGPT login — no API key required) saves a local asset under `<slides-dir>/assets/`.
 7. For complex diagrams (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw` over hand-built HTML/CSS diagrams. Render the asset with `slides-grab tldraw`, store it under `<slides-dir>/assets/`, and place it in the slide with a normal `<img>`.
-8. Keep local videos under `<slides-dir>/assets/`, prefer `poster="./assets/<file>"` thumbnails, and use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly) when the source starts on a supported web page.
-9. The default provider, god-tibo-imagen, reuses the local Codex ChatGPT login (`~/.codex/auth.json`) — run `codex login` once; no API key required. ⚠️ god-tibo-imagen uses an unsupported private Codex backend that may break without notice. Optional alternatives: `--provider codex` (Codex/OpenAI gpt-image-2 via `OPENAI_API_KEY`; maps `--aspect-ratio` to the nearest supported OpenAI image size; `--image-size 2K|4K` is Nano Banana-only) or `--provider nano-banana` (Google `gemini-3-pro-image-preview` via `GOOGLE_API_KEY` or `GEMINI_API_KEY`; supports `--image-size 2K|4K`). If credentials are unavailable, fall back to web search/download into `<slides-dir>/assets/`.
-10. Launch the interactive editor for review: `slides-grab edit --slides-dir <path>`
-11. Revise slides based on user feedback via the editor, then re-run validation after each edit round.
-12. When the user confirms editing is complete, suggest next steps: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final preview, or proceed directly to Stage 3 for PDF/PPTX export.
+8. For quantitative slides, use Chart.js as the default charting library. Start from `templates/chart.html` when useful, keep chart scripts inside each `slide-*.html`, set `animation: false`, `responsive: true`, and `maintainAspectRatio: false`, and size every `<canvas>` with a stable wrapper so validation can inspect real painted pixels.
+9. Keep local videos under `<slides-dir>/assets/`, prefer `poster="./assets/<file>"` thumbnails, and use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly) when the source starts on a supported web page.
+10. The default provider, god-tibo-imagen, reuses the local Codex ChatGPT login (`~/.codex/auth.json`) — run `codex login` once; no API key required. ⚠️ god-tibo-imagen uses an unsupported private Codex backend that may break without notice. Optional alternatives: `--provider codex` (Codex/OpenAI gpt-image-2 via `OPENAI_API_KEY`; maps `--aspect-ratio` to the nearest supported OpenAI image size; `--image-size 2K|4K` is Nano Banana-only) or `--provider nano-banana` (Google `gemini-3-pro-image-preview` via `GOOGLE_API_KEY` or `GEMINI_API_KEY`; supports `--image-size 2K|4K`). If credentials are unavailable, fall back to web search/download into `<slides-dir>/assets/`.
+11. **Run the design gate as an adversarial quality loop** before presenting the deck (`skills/slides-grab-design/references/design-gate.md`): capture render evidence (`slides-grab png … --output-dir <path>/gate-preview`), dispatch two parallel read-only reviewer passes when the current runtime supports subagents/tasks (A: System Contract / Constraint Integrity, B: Audience Impact / Expressive Readability), and synthesize contract coherence against audience impact into one Design Gate Report with a verdict. If subagents are unavailable, run the same two passes sequentially from the bundled reference. Review Litmus is the shared audience-success tie-breaker, not a third pass. **Resolve every Critical finding** (unreadable text, palette violation, AI slop trope as a slide's primary treatment, key slide with no visual anchor, invented data), re-run validate, capture fresh PNGs, and re-run both adversarial passes until the latest rendered state reaches `Proceed` or requires `Rethink approach`. For `Proceed`, the Pass A/B reports must follow the CLI-enforced structure in `slides-grab-design/references/design-gate.md` (role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, findings table, and required checks marked `PASS`). When the verdict is `Proceed`, record the export-unlocking receipt with `slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>`. If the CLI rejects the reports, continue the fix → validate → render → A/B review loop. Track deferred Minor/Note in `<slides-dir>/design-debt.md`.
+12. Launch the interactive editor for review: `slides-grab edit --slides-dir <path>`
+13. For decks with Chart.js or other `<canvas>` charts, also build the viewer (`slides-grab build-viewer --slides-dir <path>`) and visually confirm the charts render in `viewer.html`; validation reports `empty-canvas` when a visible canvas has no painted pixels.
+14. Revise slides based on user feedback via the editor, then re-run validation and the design gate after each edit round that changes layout, color, typography, imagery, or content density.
+15. When the user confirms editing is complete, suggest next steps: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final preview, or proceed directly to Stage 3 for PDF/PPTX export.
 
-**Do not proceed to Stage 3 without approval.**
+**Do not proceed to Stage 3 without approval, and never while any Critical design-gate finding is unresolved.**
 
 ### Stage 3 — Export
 
@@ -62,12 +65,14 @@ Use the installed **slides-grab-export** skill.
 
 1. **Always follow the stage order**: Plan → Design → Export.
 2. **Get explicit user approval** before advancing to the next stage.
-3. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
-4. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
-5. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
-6. Use the stage skills as the source of truth for plan, design, and export rules.
-7. When a slide needs a complex diagram, default to a `tldraw`-generated asset unless the user explicitly asks for a different approach.
-8. When a slide needs bespoke imagery, prefer the default god-tibo-imagen provider via `slides-grab image` (reuses local Codex ChatGPT login — no API key required) and keep the saved asset local under `<slides-dir>/assets/`.
+3. **Pass the design gate before export**: Stage 2 must end with a Design Gate Report whose verdict is `Proceed` (zero unresolved Critical findings) on the **latest rendered state** before the deck advances to Stage 3. The gate (`skills/slides-grab-design/references/design-gate.md`) runs after `slides-grab validate`; use runtime-native subagents/tasks for Pass A/B when available, or run the same bundled procedure sequentially. Record the latest Proceed verdict with `slides-grab design-gate`; `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` block if that receipt is missing, stale, or backed by Pass A/B reports that fail the CLI-enforced report contract. Any fix requires fresh PNG evidence and another Pass A/B challenge. Critical hard-blocks export; Major findings are listed for user acceptance; Minor/Note findings may be tracked in the design-debt log.
+4. **Read each stage's SKILL.md** for detailed rules — this skill only orchestrates.
+5. **Use `decks/<deck-name>/`** as the slides workspace for multi-deck projects.
+6. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and must be described as best-effort output.
+7. Use the stage skills as the source of truth for plan, design, and export rules.
+8. When a slide needs a complex diagram, default to a `tldraw`-generated asset unless the user explicitly asks for a different approach.
+9. When a slide needs bespoke imagery, prefer the default god-tibo-imagen provider via `slides-grab image` (reuses local Codex ChatGPT login — no API key required) and keep the saved asset local under `<slides-dir>/assets/`.
+10. When a slide needs a chart, default to Chart.js in-slide canvas rendering and require `slides-grab validate` plus `slides-grab build-viewer` review so blank canvases are caught before export.
 
 ## Reference
 - `references/presentation-workflow-reference.md` — archived end-to-end workflow guidance from the legacy skill set

package/skills/slides-grab/references/presentation-workflow-reference.md

@@ -22,18 +22,19 @@ Use the installed **slides-grab-plan** skill.
 Use the installed **slides-grab-design** skill.
 
 1. Read approved `slide-outline.md`.
-2. If the user has not approved a visual direction yet, use `slides-grab list-styles` to shortlist bundled styles, optionally `slides-grab preview-styles` to open the visual gallery in browser, and agree on a direction with the user. If none of the 35 bundled styles fit, design a fully custom visual direction.
+2. If the user has not approved a visual direction yet, use `slides-grab list-styles` to shortlist bundled styles, optionally `slides-grab preview-styles` to open the visual gallery in browser, and agree on a direction with the user. If none of the 95 bundled styles fit, design a fully custom visual direction.
 3. Generate `slide-*.html` files in the slides workspace (default: `slides/`).
 4. Run validation: `slides-grab validate --slides-dir <path>`
 5. If validation fails, automatically fix the slide HTML/CSS until validation passes.
 6. Build the viewer: `slides-grab build-viewer --slides-dir <path>`
 7. When a slide calls for bespoke imagery, prefer `slides-grab image --prompt "<prompt>" --slides-dir <path>` so the default god-tibo-imagen provider (reuses local Codex ChatGPT login — no API key required) saves a local asset under `<slides-dir>/assets/`.
 8. For complex diagrams (architecture, workflows, relationship maps, multi-node concepts), prefer `tldraw`. Render a local diagram asset with `slides-grab tldraw`, store it under `<slides-dir>/assets/`, and place it into the slide with a normal `<img>`.
-9. Keep local videos under `<slides-dir>/assets/`, prefer `poster="./assets/<file>"` thumbnails, and use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly) when the source starts on a supported web page.
-10. The default provider, god-tibo-imagen, reuses the local Codex ChatGPT login (`~/.codex/auth.json`) — run `codex login` once; no API key required. ⚠️ god-tibo-imagen uses an unsupported private Codex backend that may break without notice. Optional alternatives: `--provider codex` (Codex/OpenAI gpt-image-2 via `OPENAI_API_KEY`; maps `--aspect-ratio` to the nearest supported OpenAI image size; `--image-size 2K|4K` is Nano Banana-only) or `--provider nano-banana` (Google `gemini-3-pro-image-preview` via `GOOGLE_API_KEY` or `GEMINI_API_KEY`; supports `--image-size 2K|4K`). If credentials are unavailable, fall back to web search + download into `<slides-dir>/assets/`.
-11. Present viewer to user for review.
-12. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
-13. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
+9. For quantitative slides, use Chart.js as the default charting library, preferably starting from `templates/chart.html`. Keep scripts in `slide-*.html`, disable animation, use stable canvas wrappers, and fix any `empty-canvas` validation error before review.
+10. Keep local videos under `<slides-dir>/assets/`, prefer `poster="./assets/<file>"` thumbnails, and use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly) when the source starts on a supported web page.
+11. The default provider, god-tibo-imagen, reuses the local Codex ChatGPT login (`~/.codex/auth.json`) — run `codex login` once; no API key required. ⚠️ god-tibo-imagen uses an unsupported private Codex backend that may break without notice. Optional alternatives: `--provider codex` (Codex/OpenAI gpt-image-2 via `OPENAI_API_KEY`; maps `--aspect-ratio` to the nearest supported OpenAI image size; `--image-size 2K|4K` is Nano Banana-only) or `--provider nano-banana` (Google `gemini-3-pro-image-preview` via `GOOGLE_API_KEY` or `GEMINI_API_KEY`; supports `--image-size 2K|4K`). If credentials are unavailable, fall back to web search + download into `<slides-dir>/assets/`.
+12. Present viewer to user for review. For Chart.js decks, specifically confirm charts render inside `viewer.html`.
+13. Revise individual slides based on feedback, then re-run validation and rebuild the viewer.
+14. Optionally launch the visual editor: `slides-grab edit --slides-dir <path>`
 
 **Do not proceed to Stage 3 without approval.**
 
@@ -57,3 +58,4 @@ Use the installed **slides-grab-export** skill.
 5. **Call out export risk clearly**: PPTX and Figma export are experimental / unstable and should be described as best-effort output.
 6. **Prefer tldraw for complex diagrams**: Use `slides-grab tldraw` for diagram-heavy slides unless the user explicitly wants another rendering path.
 7. **Prefer Codex/OpenAI for bespoke imagery**: Use `slides-grab image` when a slide benefits from generated imagery, and keep the result as a local asset under `<slides-dir>/assets/`.
+8. **Prefer Chart.js for charts**: Use real canvas charts for quantitative claims and require validation plus viewer review before export.

package/skills/slides-grab-card-news/SKILL.md

@@ -5,7 +5,7 @@ metadata:
   short-description: Square card-news workflow on top of slides-grab (PNG by default)
 ---
 
-# slides-grab Card News Skill (Codex)
+# slides-grab Card News Skill
 
 Use this when the user wants card news instead of a widescreen presentation.
 

package/skills/slides-grab-design/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: slides-grab-design
-description: Stage 2 design skill for Codex. Generate and iterate slide-XX.html files in the selected slides workspace.
+description: Stage 2 design skill usable in Codex and Claude Code. Generate and iterate slide-XX.html files in the selected slides workspace.
 metadata:
   short-description: Build HTML slides and viewer for review loop
 ---
 
-# slides-grab Design Skill (Codex)
+# slides-grab Design Skill
 
 Use this after `slide-outline.md` is approved.
 
@@ -33,15 +33,19 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 6. When a slide needs iconography, prefer Lucide as the default icon library. Use clean Lucide icons before falling back to emoji, and only use emoji when the brief explicitly calls for them.
 7. When a slide explicitly needs bespoke imagery, when the user asks for an image, or when stronger imagery would materially improve the slide, prefer `slides-grab image --prompt "<prompt>" --slides-dir <path>` to generate a local asset with the default god-tibo-imagen provider (which reuses the local Codex ChatGPT login — no API key required) and save it under `<slides-dir>/assets/`.
 8. If the deck needs a complex diagram (architecture, workflows, relationship maps, multi-node concepts), create the diagram in `tldraw`, export it with `slides-grab tldraw`, and treat the result as a local slide asset under `<slides-dir>/assets/`.
-9. If the slide needs a local video, store the video under `<slides-dir>/assets/`, reference it as `./assets/<file>`, and prefer a `poster="./assets/<file>"` thumbnail so PDF export uses a stable still image.
-10. If the source video starts on YouTube or another supported page, use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly if needed) to download it into `<slides-dir>/assets/` before saving the slide HTML.
-11. Run `slides-grab validate --slides-dir <path>` after generation or edits.
-12. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
-13. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
-14. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
-15. Iterate on user feedback by editing only requested slide files, then re-run validation after each edit round.
-16. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
-17. Keep revising until user approves conversion stage.
+9. If a slide needs a chart, default to Chart.js (`<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>`) and start from `templates/chart.html` when helpful. Keep the script in the slide HTML, use real data from the outline/research, set `animation: false`, `responsive: true`, and `maintainAspectRatio: false`, wrap each `<canvas>` in a fixed-size or flex-stable container, and use direct labels or concise legends that match the approved style tokens.
+10. If the slide needs a local video, store the video under `<slides-dir>/assets/`, reference it as `./assets/<file>`, and prefer a `poster="./assets/<file>"` thumbnail so PDF export uses a stable still image.
+11. If the source video starts on YouTube or another supported page, use `slides-grab fetch-video --url <youtube-url> --slides-dir <path>` (or `yt-dlp` directly if needed) to download it into `<slides-dir>/assets/` before saving the slide HTML.
+12. Run `slides-grab validate --slides-dir <path>` after generation or edits. Treat `empty-canvas` as a chart-rendering failure: fix the Chart.js target id, script loading, canvas sizing, or chart initialization until the canvas paints.
+13. If validation fails, automatically fix the source slide HTML/CSS and re-run validation until it passes.
+14. Run the slide litmus check from `references/beautiful-slide-defaults.md` before presenting the deck for review.
+15. **Run the design gate as an adversarial quality loop** (`references/design-gate.md`) before showing the deck: (a) capture render evidence with `slides-grab png --slides-dir <path> --output-dir <path>/gate-preview --resolution 1080p`; (b) run two read-only reviewer passes — Pass A (System Contract / Constraint Integrity) and Pass B (Audience Impact / Expressive Readability) — that open the rendered PNGs directly, using runtime-native subagents/tasks in parallel when available or sequential passes when not; (c) synthesize contract coherence against audience impact into a single Design Gate Report ending in a verdict (`Proceed` / `Revise and re-review` / `Rethink approach`). Review Litmus is the shared audience-success tie-breaker, not a third pass. Keep the two reviewer passes distinct from the slide-building pass. The render evidence aims the reviewers; it is not the verdict. For `Proceed`, each pass report must satisfy the CLI-enforced structure in `references/design-gate.md`: role title, `VERDICT: PASS`, confidence, rendered PNG evidence filenames, current `slide-*.html: <sha256>` fingerprints, `Unresolved Critical: 0`, `Blocking findings: None`, a findings table, and all required checks marked `PASS`.
+16. **Repeat until the latest rendered state survives the gate.** Critical findings (unreadable text, palette violation, an AI slop trope used as a slide's primary treatment, a key slide with no real visual anchor, invented data shown as real) hard-block progress. Fix the source HTML/CSS, re-run `slides-grab validate`, capture fresh PNGs, then re-run both adversarial passes until the verdict is `Proceed` (zero unresolved Critical) or `Rethink approach` requires redesigning the visual thesis/system. When the verdict is `Proceed`, write the export-unlocking receipt with `slides-grab design-gate --slides-dir <path> --verdict proceed --pass-a-report <pass-a.md> --pass-b-report <pass-b.md>`. If the CLI rejects the reports, treat that as the loop still failing: fix the missing evidence/checks or unresolved findings, re-render, re-review, and retry. Record deferred Minor/Note findings in `<slides-dir>/design-debt.md`; never silently drop a finding.
+17. Launch the interactive editor for visual review: `slides-grab edit --slides-dir <path>`
+18. For decks with Chart.js or other canvas charts, also run `slides-grab build-viewer --slides-dir <path>` and open `viewer.html` to confirm charts render inside the generated iframe viewer, not only as standalone `slide-*.html` files.
+19. Iterate on user feedback by editing only requested slide files, then re-run validation and the design gate after each edit round that changes layout, color, typography, imagery, or content density.
+20. When the user confirms editing is complete, suggest: build the viewer (`slides-grab build-viewer --slides-dir <path>`) for a final read-only preview, or proceed to export (PDF/PPTX).
+21. Keep revising until user approves conversion stage.
 
 ## Rules
 - Keep slide size 720pt x 405pt.
@@ -65,7 +69,10 @@ Generate high-quality `slide-XX.html` files in the selected slides workspace (`s
 - Avoid AI slop tropes — aggressive gradient backgrounds, left-border accent cards, SVG-drawn imagery, generic font stacks (Inter/Roboto/Arial), and generic 3×2 icon-plus-blurb grids. See `references/beautiful-slide-defaults.md` for the full list.
 - Prefer `tldraw` for complex diagrams instead of recreating dense node/edge diagrams directly in HTML/CSS.
 - Use `slides-grab tldraw` plus `templates/diagram-tldraw.html` when that gives a cleaner, more export-friendly result.
+- Prefer Chart.js for charts. Do not fake charts with decorative div bars when the slide is communicating data; real `<canvas>` charts are validated for painted pixels and blank canvases fail as `empty-canvas`.
+- Keep Chart.js chart animation disabled for deterministic validation/export, and keep canvas dimensions stable with CSS so the drawing buffer and layout box are both non-zero.
 - Do not present slides for review until `slides-grab validate --slides-dir <path>` passes.
+- Do not present slides for review, and do not advance toward export, while any **Critical** design-gate finding is unresolved (`references/design-gate.md`). Critical hard-blocks; Major findings are listed for user acceptance; Minor/Note findings may be tracked. `slides-grab pdf`, `slides-grab convert`, and `slides-grab figma` require a fresh `slides-grab design-gate` Proceed receipt.
 - Do not start conversion before approval.
 - Use the packaged CLI and bundled references only; do not depend on unpublished agent-specific files.
 
@@ -74,4 +81,5 @@ For full constraints and style system, follow:
 - `references/design-rules.md`
 - `references/detailed-design-rules.md`
 - `references/beautiful-slide-defaults.md` — slide-specific art direction defaults adapted from OpenAI's frontend design guidance and Anthropic's Claude design system guidance (content/color discipline, system declaration, AI slop tropes)
+- `references/design-gate.md` — the structured design-quality gate run after validation and before export: severity rubric (Critical/Major/Minor/Note), the seven checks, evidence-before-shipping, design-debt log, and the gate report/verdict format. Run with runtime-native subagents/tasks when available, or as two explicit sequential reviewer passes, then record Proceed with `slides-grab design-gate`.
 - `references/design-system-full.md` — archived full design system, templates, and advanced pattern guidance

package/skills/slides-grab-design/references/design-gate.md

@@ -0,0 +1,349 @@
+# slides-grab Design Gate
+
+The design gate is the structured, pass/fail design-quality review a deck must clear **after** `slides-grab validate` (technical correctness) and **before** export. Validation proves the HTML is mechanically sound; the design gate proves the deck is actually well-designed.
+
+This gate is adapted from inclusive multi-agent design review process (severity-gated critique, evidence before claims, deferred-issue tracking) and grounded in this repo's own art direction (`beautiful-slide-defaults.md`, `detailed-design-rules.md`).
+
+> **One rule above all:** the gate produces a **verdict with evidence**, never an opinion. "This looks good" is not a pass. "I checked these criteria against these slides and here is the result" is a pass.
+
+---
+
+## Where the gate runs
+
+```
+Stage 2 (Design)
+  generate slides
+    → slides-grab validate        (technical: asset paths, tags, size, overflow)
+    → Review Litmus               (beautiful-slide-defaults.md)
+    → DESIGN GATE  ← this file    (dual-oracle Visual QA → severity-classified verdict)
+        ├─ capture render evidence   (slides-grab png → gate-preview/*.png)
+        ├─ Pass A  read-only  (System Contract / Constraint Integrity)      ┐ parallel
+        ├─ Pass B  read-only  (Audience Impact / Expressive Readability)    ┘
+        ├─ synthesize one verdict    (Proceed / Revise / Rethink)
+        └─ if not Proceed: fix → validate → re-render → adversarial re-review
+    → user visual review (editor)
+  user approves
+Stage 3 (Export)  ← refuses to start while any Critical finding is unresolved
+```
+
+Run the gate as an **adversarial quality loop**, not a one-shot audit:
+- after the first full pass of slide generation, before presenting the deck for review,
+- again after any edit round that changes layout, color, typography, imagery, or content density, and
+- repeatedly until the synthesized verdict is `Proceed` or the gate declares `Rethink approach`.
+
+The loop is: **validate → render evidence → Pass A + Pass B → synthesize → fix findings → validate again → re-render → re-review**. Do not reuse old PNGs or old pass reports after a fix; every loop uses fresh rendered evidence. The same adversarial roles run again, because the fix for one side can create a new defect for the other side.
+
+The gate is a separate evaluation pass. Run it with a critical eye, using runtime-native subagents/tasks for the two reviewer passes when available, so the reviewer is not the same mind that just defended every choice while building.
+
+---
+
+## Severity rubric
+
+Every finding gets exactly one severity. Severity decides what happens next — it is not a vibe.
+
+| Severity | Definition | Action |
+|----------|-----------|--------|
+| **Critical** | Breaks the deck's design integrity or makes a slide fail its job: unreadable text, palette violation, an AI slop trope shipped as the primary treatment, no real visual anchor on a key slide, or a slide whose main point cannot be grasped. | **Must fix before proceeding. Hard-blocks export.** |
+| **Major** | Significantly degrades quality but the slide still works: weak hierarchy, inconsistent system across slides, decorative chrome carrying no meaning, copy that does not scan. | **Should fix before review/handoff.** Advisory — user may choose to proceed. |
+| **Minor** | Improvement opportunity that neither blocks nor significantly degrades: small spacing/alignment imperfections, a slightly off accent usage. | **Fix if cheap, otherwise track as design debt.** |
+| **Note** | Observation or idea for a future iteration. | **Document, do not act on now.** |
+
+**Hard gate rule:** Critical findings block progress. They must be resolved (or the offending slide redesigned) before the deck advances to export. No Critical is ever silently downgraded to get to a green verdict.
+
+**No silent drops:** every Minor and Note that is not fixed this round is written into the design-debt log (see below). Findings either get fixed or get tracked — never dropped.
+
+---
+
+## What the gate checks
+
+Run every slide through these checks. Each check maps to existing repo rules; the gate's job is to enforce them as a structured pass, not to invent new taste.
+
+### 1. System consistency (from `beautiful-slide-defaults.md` → "Vocalize the System")
+- [ ] The deck commits to a declared system: reused layout patterns, **max two background colors**, **max two typefaces**, **one accent color**.
+- [ ] Section dividers and content slides follow the declared rhythm; the system does not drift slide to slide.
+- [ ] Image-led vs text-led slides match the declared content plan.
+
+### 2. Color discipline (from `beautiful-slide-defaults.md` → "Color Discipline")
+- [ ] Every color traces back to the approved style spec (`src/design-styles-data.js`) / the user's brand tokens, or a documented harmonic `oklch()` extension of them.
+- [ ] No fresh standalone hex colors invented mid-slide.
+- [ ] One accent color across the deck; two background colors max.
+- **A color that cannot be traced to the approved palette is Critical.**
+
+### 3. AI slop tropes (from `beautiful-slide-defaults.md` → "AI Slop Tropes to Avoid")
+- [ ] No aggressive full-slide gradient background used as the primary surface.
+- [ ] No rounded-rectangle "accent card" with a solid left-border stripe as a default container.
+- [ ] No iconography or product imagery drawn with inline SVG shapes (use a real asset or `data-image-placeholder`).
+- [ ] No generic font stacks (Inter, Roboto, Arial, Fraunces, OS system stacks) — Pretendard or the style-specified typeface only.
+- [ ] No emoji as default iconography (Lucide is the default; emoji only when the brief explicitly calls for a playful native-emoji tone).
+- [ ] No generic 3×2 "feature card grid" (icon + heading + two-line blurb) used as the default answer to a content slide.
+- [ ] No faux chrome (drop shadows, subtle gradients, card borders) added to decorate empty space instead of carrying meaning.
+- **A slop trope shipped as a slide's primary treatment is Critical. An isolated, secondary instance is Major.**
+
+### 4. Composition & hierarchy (from `beautiful-slide-defaults.md` → "Beautiful Defaults")
+- [ ] Each slide has one job, one primary takeaway, one dominant visual anchor.
+- [ ] The opening slide reads like a poster — the title or brand is the loudest element, free of secondary clutter.
+- [ ] Whitespace, alignment, scale, cropping, and contrast do the work before any decorative chrome.
+- [ ] Cardless by default; a card appears only where it improves structure or comprehension.
+- **A key slide (opener, section divider, closing) with no real visual anchor is Critical.**
+
+### 5. Content discipline (from `beautiful-slide-defaults.md` → "Content Discipline")
+- [ ] No filler copy, dummy stats, invented numbers, vague percentages, or stat strips that only exist to look informational.
+- [ ] No element added beyond the approved outline without user sign-off.
+- [ ] Copy scans in seconds; every line, badge, and callout earns its place.
+- **Invented data presented as real is Critical.**
+
+### 6. Typography & legibility (from `detailed-design-rules.md`)
+- [ ] Body copy ≥ 14pt on a 720×405pt slide; nothing below the 10pt absolute floor.
+- [ ] A consistent type scale is reused across the deck (display / headline / body / caption roles), not ad-hoc sizes per slide.
+- [ ] Text has enough contrast against its background to be read comfortably at presentation distance.
+- **Text below the 10pt floor, or text that is effectively unreadable against its background, is Critical.**
+
+### 6b. Korean/CJK word-break integrity (from `detailed-design-rules.md`)
+
+Korean and CJK text must break **between words (어절), never inside one.** A single word split across two lines — e.g. `오케스트` / `레이션`, `에이전` / `트` — looks broken on a slide and must be fixed, not tolerated as "acceptable wrapping."
+
+This check has **two layers**: (1) *prevent* mid-word breaks at build time with `word-break: keep-all`; (2) at the gate, the Visual QA pass *catches the side effect* of keep-all — uneven (ragged) lines — and devises a fix strategy. Layer 1 is mechanical and should already be on. Layer 2 needs a human/oracle reading the rendered slide, because "is this line balance ugly?" is a visual judgment, not a grep.
+
+**Layer 1 — Prevent mid-word breaks (build-time baseline):**
+- [ ] No 어절/word is broken mid-word across lines. The break point always falls at a space (word boundary), not inside a token.
+- [ ] `word-break: keep-all` is set on every heading, quote, and body block that can wrap. This is the default baseline for slide HTML.
+- [ ] Indivisible units (a label like `[Image #1]`, a product name, a number+unit) use `white-space: nowrap;` so they never split.
+
+**Layer 2 — Line balance after keep-all (Visual QA judgment):**
+
+`keep-all` stops mid-word breaks, but it has a known side effect: when a long word will not fit, the whole word is pushed to the next line, which can leave the deck with **ragged lines** — one line nearly full, the next carrying only a word or two. When the **per-line character counts differ a lot across the wrapped lines** of a single block, the block looks lopsided.
+
+- [ ] No wrapped text block is left badly ragged: a near-full line followed by a line carrying only a stray word or two.
+- [ ] Across the lines of one wrapped block, the per-line character counts are roughly even — no single line is a small fraction of the others.
+- [ ] No orphaned tail line carrying a single syllable or 1–2 characters that belongs with the line above.
+
+When Visual QA (Pass B) finds a ragged/lopsided block, it must **devise a fix strategy**, not just flag it. Choose from the ladder below (cheapest first that keeps the design intent):
+1. **Insert an explicit `<br>`** at the intended phrase boundary so the wrap lands where you want it and the lines read as balanced whole-word groups.
+2. **Balance the lines automatically** with `text-wrap: balance;` (or `pretty`) so the browser evens out per-line length.
+3. **Reduce the average characters per line** — narrow the text box (`max-width`) or add more deliberate line breaks so each line carries fewer, more even characters. Lowering the average per-line count this way trades a taller block for even, calm lines, which usually reads better on a slide than two wildly uneven lines. Prefer this when the imbalance comes from one overflowing word forcing an awkward wrap.
+4. **Nudge letter-spacing or font-size down a notch** to pull a stranded word back onto the previous line — but never below the 14pt body floor / 10pt absolute floor.
+5. **Re-word or shorten the copy** (within the approved outline) so it wraps cleanly. If it changes meaning, ask the user first.
+
+- **Severity:** A key slide (title, section divider, closing) or a large heading/quote with a **mid-word Korean break (Layer 1)** is **Major** (must fix before review). A **badly ragged / lopsided wrapped block (Layer 2)** on a key slide or large heading is **Major**; the same in small body/caption text, or a merely slightly-uneven-but-whole-word wrap, is **Minor** (fix or track). Set `word-break: keep-all` proactively while building so Layer 1 rarely surfaces, leaving the gate to focus on Layer 2 line balance.
+
+### 7. Review Litmus (from `beautiful-slide-defaults.md` → "Review Litmus")
+
+Review Litmus exists because the two reviewer roles need one shared audience-success contract. It keeps synthesis from collapsing into either subjective taste ("I like it") or pure rule compliance ("the tokens are legal, therefore it passes"). It is **not a third reviewer pass**; it is the gate-level tie-breaker that asks whether a contract-compliant slide still succeeds for the audience.
+
+`beautiful-slide-defaults.md` keeps the litmus as the authoring/self-review heuristic before handoff. This file uses the same litmus during synthesis: when Pass A and Pass B disagree below Critical severity, prefer the fix that makes the slide's point faster, clearer, and less dependent on decorative chrome.
+
+For each slide, confirm:
+- [ ] The audience can grasp the main point in 3–5 seconds.
+- [ ] One dominant idea, not multiple competing blocks.
+- [ ] One real visual anchor, not just decoration.
+- [ ] Still feels premium with shadows/cards/chrome stripped away.
+- [ ] No line of copy, badge, or callout can be removed without losing meaning.
+
+---
+
+## How the gate is run: the Visual QA procedure (dual-oracle)
+
+The seven checks above are *what* to judge. This section is *how* to judge them with real evidence. The gate is run as a Visual QA procedure adapted from the dual-oracle web/TUI verification pattern: capture objective render evidence, dispatch two parallel read-only reviewer passes, then synthesize one verdict.
+
+> **The render evidence is not the verdict.** `slides-grab validate` numbers and rendered PNGs *aim* the reviewers; they do not, by themselves, pass the deck. A clean validate run can still hide an unreadable heading, an awkward Korean line break, or a key slide with no anchor.
+
+### Step 1 — Capture objective render evidence
+
+The gate must be run against the **actual rendered slides**, never the raw HTML alone. Reading HTML cannot reveal CJK line breaks, descender clipping, accent overuse, element overlap, or weak hierarchy as they appear on screen.
+
+```
+slides-grab png --slides-dir <path> --output-dir <path>/gate-preview --resolution 1080p
+```
+
+This renders one PNG per slide. These PNGs are the REFERENCE evidence every reviewer pass must open and inspect. Also keep the `slides-grab validate` summary (it must already be green) as supporting evidence.
+
+### Step 2 — Dispatch two read-only reviewer passes in parallel
+
+Send BOTH passes in a single message so they run concurrently. Each pass is **read-only**: it reviews and reports, it never edits slides. Each opens the rendered PNGs directly and returns a verdict with located findings. The two passes differ in charter, not in tooling.
+
+The passes are dialectical roles, not checklist buckets. Pass A asks whether the deck honors its approved system contract; Pass B asks whether the rendered slides actually land for the audience. A strong deck satisfies both: **contract without impact is inert; impact without contract is drift.**
+
+**Pass A — System Contract / Constraint Integrity (contract guardian).** Proves the deck is allowed, coherent, and traceable before it is allowed to be impressive. It protects the approved design contract: style tokens, palette provenance, type system, semantic tags, asset/content provenance, anti-slop rules, and no ad-hoc drift across slides. Covers gate checks 1 (system consistency), 2 (color discipline), 3 (AI slop), and 5 (content discipline). Owns the **rule** side of the Rule → side effect matrix: whether each mechanical rule is actually applied and consistent. Inputs: all slide HTML source + the rendered PNGs + the validate summary + the approved style spec from `src/design-styles-data.js`.
+
+**Pass B — Audience Impact / Expressive Readability (audience guardian).** Opens every rendered PNG and judges what the audience actually sees, feels, and understands. It protects each slide's one job, hierarchy, scanability, visual anchor, legibility, CJK line balance, and the compensation for visual side effects created by mechanical rules. Covers gate checks 4 (composition & hierarchy), 6 (typography & legibility), 6b (Korean/CJK word-break integrity — **both layers**), and 7 (Review Litmus). Owns the **side effect / compensation** side of the Rule → side effect matrix. Special weight on: **(Layer 1) mid-word Korean breaks** (a single 어절 split across two lines, e.g. `오케스트`/`레이션`) — fix with `word-break: keep-all`; **(Layer 2) ragged/lopsided line balance** introduced by keep-all — a near-full line followed by a stray-word line, or large per-line character-count differences within one block. For Layer 2, Pass B must **propose a concrete strategy** from the 6b ladder: insert `<br>` at the phrase boundary, apply `text-wrap: balance`, or **reduce the average characters per line** (narrow `max-width` / add breaks) so all lines are evened out — not merely flag it. Also weigh descender/baseline clipping, orphaned single-syllable tail lines, glyph drop (tofu), accent overuse, and element overlap. Inputs: the rendered PNGs (must be opened with an image-viewing tool) + the slide HTML + the validate summary.
+
+Each pass returns: `VERDICT: PASS | REVISE | FAIL`, a confidence, a located findings list with one severity per finding (Critical/Major/Minor/Note), and a BLOCKING list.
+
+For a `Proceed` gate, the CLI enforces the pass-report contract below. A short "looks good / Proceed" note is not enough and `slides-grab design-gate --verdict proceed` rejects it. Every pass report must reference the rendered PNG evidence files that `slides-grab design-gate` creates, for example `slide-01.png`, `slide-02.png`, etc. It must also include the current slide source fingerprint for every `slide-*.html` file in the reviewed deck (`slide-01.html: <sha256>`). If the slide source changes after the reports were written, the old reports cannot be reused.
+
+**Pass A required report skeleton:**
+
+```markdown
+# Pass A: System Contract / Constraint Integrity
+
+VERDICT: PASS
+Confidence: High
+Evidence: <slides-dir>/.slides-grab/gate-preview/slide-01.png, ...
+Slide fingerprints: slide-01.html: <sha256>, ...
+Unresolved Critical: 0
+Blocking findings: None
+
+## Checks
+- [x] System consistency: PASS — <evidence>
+- [x] Color discipline: PASS — <evidence>
+- [x] AI slop tropes: PASS — <evidence>
+- [x] Content discipline: PASS — <evidence>
+
+## Findings
+| Slide | Finding | Severity | Fix | Status |
+|-------|---------|----------|-----|--------|
+| slide-01 | No blocking findings | Note | None | tracked |
+```
+
+**Pass B required report skeleton:**
+
+```markdown
+# Pass B: Audience Impact / Expressive Readability
+
+VERDICT: PASS
+Confidence: High
+Evidence: <slides-dir>/.slides-grab/gate-preview/slide-01.png, ...
+Slide fingerprints: slide-01.html: <sha256>, ...
+Unresolved Critical: 0
+Blocking findings: None
+
+## Checks
+- [x] Composition & hierarchy: PASS — <evidence>
+- [x] Typography & legibility: PASS — <evidence>
+- [x] Korean/CJK word-break integrity: PASS — <evidence>
+- [x] Review Litmus: PASS — <evidence>
+
+## Findings
+| Slide | Finding | Severity | Fix | Status |
+|-------|---------|----------|-----|--------|
+| slide-01 | No blocking findings | Note | None | tracked |
+```
+
+If either pass has an unresolved Critical finding, non-empty blocking findings, a non-`PASS` verdict, missing rendered evidence, missing current slide fingerprints, missing findings table, or missing required checks, fix the slides and run the full loop again. Do not call `slides-grab design-gate --verdict proceed` until both pass reports satisfy this structure.
+
+> **If no image-capable reviewer is available in the harness**, the gate cannot be completed honestly by the orchestrator alone. Do NOT declare `Proceed` from HTML/grep inspection only. Either (a) route Pass B to an image-capable model/agent, or (b) hand the rendered `gate-preview/` PNGs to the user for the visual verdict. Code-level checks (palette grep, slop grep, font/typography floor, validate) may be reported as a **partial** result, but the visual checks (4, 6, 7) stay open until a real viewing happens. An open visual check is not a pass.
+
+### Step 3 — Synthesize one verdict
+
+Merge both passes into a single Design Gate Report (format below). Do not average the two reports and do not let one role erase the other. Per the severity rubric: any Critical from either pass blocks `Proceed`. Pass A can veto a choice that violates the approved contract, provenance, mechanical rules, or content truth. Pass B can veto a contract-compliant slide that still fails its audience job, rendered hierarchy, readability, CJK precision, or side-effect compensation. For non-Critical disagreement, use Review Litmus to decide the disposition: for **Major**, fix now or list it for user acceptance in the report; for **Minor**, fix now or track as design debt. Reconcile conflicts with the order in "Reconciliation". The synthesized report — not either pass alone, and not the validate numbers — is the gate's verdict.
+
+Use the current runtime's native subagent/task mechanism when available. If the runtime has no such mechanism, run Pass A and Pass B sequentially from this reference and keep their findings separate before synthesis.
+
+### Step 4 — Fix and repeat until quality holds
+
+If the verdict is `Revise and re-review`, fix the listed Critical findings, run `slides-grab validate` again, capture fresh PNGs, and dispatch both passes again. The next pass must inspect the updated render evidence from scratch; do not treat a previous pass as still valid after layout, color, type, imagery, or density changes.
+
+If the verdict is `Rethink approach`, stop patching individual slides. Rewrite the visual thesis / system declaration, regenerate or substantially redesign the failing slide family, then restart the full gate loop from validation and fresh render evidence.
+
+`Proceed` means the current loop has zero unresolved Critical findings **and** both adversarial roles have had a chance to challenge the current rendered state. It does not mean the first review was good enough; it means the latest reviewed state survived the loop.
+
+---
+
+## Evidence before shipping (the Iron Law)
+
+Never report the gate as passed on belief. A pass requires having actually looked at the rendered output.
+
+- [ ] The deck was inspected slide by slide against the checks above — name the slides, not "the deck looks fine."
+- [ ] `slides-grab validate --slides-dir <path>` passed (the gate assumes technical validation is already green).
+- [ ] For any imagery/diagram claim, the asset was confirmed to render (local asset present, not a broken reference).
+- [ ] Every Critical and Major finding is listed with the specific slide and the specific fix.
+
+"I believe the deck is well-designed" is not evidence. "I reviewed slides 01–12 against the seven checks; here are the findings" is.
+
+---
+
+## Design-debt log
+
+Findings that are not fixed this round are not dropped — they are tracked.
+
+Maintain `<slides-dir>/design-debt.md` with one row per deferred finding:
+
+```markdown
+# Design Debt — <deck name>
+
+| Slide | Finding | Severity | Why deferred | Fix |
+|-------|---------|----------|--------------|-----|
+| slide-07 | Accent used on two competing elements | Minor | Cosmetic, low impact | Demote secondary to muted text |
+```
+
+Rules:
+- Only **Minor** and **Note** items may land here as design debt. **Critical** findings must be resolved before the gate passes. **Major** findings are fixed before handoff when practical, or explicitly listed in the report for user acceptance; they are never silently dropped into debt.
+- Debt accumulates across edit rounds; review it before the final approval so nothing important silently ages out.
+
+---
+
+## Gate report format
+
+The gate always ends with a single structured report. Use exactly this shape:
+
+```markdown
+## Design Gate Report — <deck name>
+
+**Slides reviewed:** slide-01 … slide-XX
+**Technical validation:** pass (slides-grab validate)
+
+### Findings
+| Slide | Finding | Severity | Fix |
+|-------|---------|----------|-----|
+| slide-03 | Full-slide gradient as primary surface | Critical | Replace with flat surface token + real visual anchor |
+| slide-08 | Hierarchy flat; two headings compete | Major | Promote one headline, demote the other to caption |
+| slide-05 | Accent slightly off the palette | Minor | Snap to approved accent token (tracked as debt) |
+
+### Verdict
+[ Proceed / Revise and re-review / Rethink approach ]
+
+**Reason:** <one or two sentences tied to the findings>
+```
+
+### Verdict meanings
+- **Proceed** — zero unresolved Critical findings. Major findings, if any, are listed for the user to accept or fix. The deck may advance to user review / export.
+- **Revise and re-review** — one or more Critical findings exist. Fix them, then run the gate again. Export stays blocked.
+- **Rethink approach** — the deck's design direction itself is failing (system never cohered, repeated slop across many slides). Stop patching; reset the visual thesis / system declaration before regenerating.
+
+---
+
+## Reconciliation (when checks conflict)
+
+If two checks pull in opposite directions on the same slide, treat the disagreement as useful signal: **contract without impact is inert; impact without contract is drift.** Resolve in this order:
+
+1. **Legibility wins over aesthetics** — a beautiful slide nobody can read fails.
+2. **Clarity wins over decoration** — the slide's one job beats any embellishment.
+3. **Approved contract wins over local cleverness** — tokens, content truth, semantic rules, and the user's chosen style/brief govern.
+4. **Review Litmus breaks Major/Minor ties** — prefer the option the audience grasps in 3–5 seconds with one idea and one anchor.
+5. **Escalate to the user** if still unresolved — present the trade-off, let them decide.
+
+---
+
+## Rule → side effect → Visual QA compensation matrix
+
+Every mechanical rule in this framework prevents one class of defect but can introduce its own visual side effect. The discipline is **two-layered**: a build-time rule prevents the defect, and the gate's Visual QA pass catches and compensates the side effect the rule creates. Check 6b (Korean word-break → ragged lines) is the canonical example; the full set is below.
+
+The left half is mechanical (apply while building, or `slides-grab validate` enforces it). The right half is a **visual judgment** — it needs a reviewer reading the rendered PNG, because "does this look broken?" is not a grep. When Pass B finds a side effect, it must **propose the compensation**, not just flag it.
+
+| # | Mechanical rule (prevents) | Side effect it can create | Visual QA compensation (in order) | Severity if unfixed |
+|---|---|---|---|---|
+| 1 | **`word-break: keep-all`** — no mid-word Korean break | **Ragged / lopsided lines**: one near-full line, next carries one stray word | `<br>` at phrase boundary → `text-wrap: balance` → reduce avg chars/line via narrower `max-width` → nudge letter-spacing/size (≥14pt) | Major on key slide/large heading; Minor in body |
+| 2 | **Tight `line-height`** to fit one line | **Descender/받침 clipping**: 한글 받침(ㅂ,ㅍ,ㄱ) or latin g/y/p tails cut off; `text-clipped` may also trip | Raise `line-height` (≥1.3 display, ≥1.5 body) → add `padding-block` → if metric-driven, `ascent/descent-override` on the @font-face | Critical if glyphs actually clipped; Major if cramped |
+| 3 | **`white-space: nowrap`** on indivisible units | **Horizontal overflow** past the 720pt frame (caught by `overflow-outside-frame`) | Confirm the unit truly cannot wrap; otherwise drop nowrap → shorten the token → `text-overflow: ellipsis` only if truncation is acceptable | Critical (frame overflow blocks export) |
+| 4 | **Fixed pt type scale** (display/headline/body roles) | A long Korean title **overflows or force-shrinks** below the scale / the 14pt floor | Re-break the title with `<br>` → shorten copy (within outline; ask if meaning changes) → `clamp()` within the scale band — never below 14pt body / 10pt floor | Major (broken scale); Critical if pushed under 10pt |
+| 5 | **`overflow: hidden`/`clip` on the frame OR any inner container** | **Silent clipping**: content is cut but looks intentional. Two sub-cases: (a) `validate` text-clipped catches a *text element* clipping itself; (b) **it does NOT catch a parent container (`overflow:hidden`/`clip`, e.g. a `border-radius` card or a `flex:1` column box) clipping its *children*** — those children are neither out-of-frame nor self-clipped, so both built-in checks miss them. This is the known gate blind spot. | **Detect mechanically AND visually.** Mechanical: for every element with computed `overflow` ∈ {hidden, clip} on either axis, flag when `scrollHeight > clientHeight + 1` or `scrollWidth > clientWidth + 1` (a child is being cut). Visual: read every PNG — a cut bottom line/edge confirms it. Fix: reduce content (tighter spacing/margins, smaller step) or enlarge the box so children fit; never leave hidden-but-clipped content. | Critical (a clipped slide fails its job) |
+| 6 | **One accent color** (palette discipline) | **Flat hierarchy**: every emphasis is the same color, so primary vs secondary blurs | Differentiate by **size / weight / position / lightness step**, not a new hue; reserve the accent for the single most important mark per slide | Major if the eye cannot find the anchor |
+| 7 | **Text only in semantic tags** (`p/h1-h6/li`) | **Micro-alignment friction**: cannot drop raw text in `<div>`/`<span>` for pixel placement | Wrap the text node in a `<p>` and position the wrapper with grid/flex/absolute; use `::before/::after` for purely decorative strings | Minor (mechanical, rarely visual) |
+| 8 | **Fixed grid (e.g. 3-up)** for rhythm | **Lopsided last row**: item count (2,4,5) does not divide the grid → orphan cell / empty gap | `repeat(auto-fit, minmax(...))` → asymmetric 60/40 split → promote one item to a 2× hero so the gap reads as intentional | Major if it looks like a mistake; Minor if balanced |
+| 9 | **CDN webfont (Pretendard)** | **Export font drop / layout shift**: PNG/PDF renders a fallback if the font is not ready → different metrics, re-wrapped lines | Wait on `document.fonts.ready` before capture (export tooling already does); confirm Korean glyphs render in the PNG, not tofu; self-host for offline/CI | Critical if glyphs drop (tofu); Major if metrics shifted wrapping |
+| 10 | **No CSS gradients** (raster to PNG instead) | **Color banding / pixelation** in the rasterized gradient | Render at 2× scale → add subtle dither/noise overlay → widen the gradient's tonal range → keep it vector (SVG/`print` PDF) if the target allows | Minor unless banding is obviously visible |
+| 11 | **Dark theme** (modern-dark etc.) | **Bright asset clash**: a light chart/logo/screenshot floats as a bright island; muted text drops below readable contrast | Restyle the asset to the dark surface (transparent bg, thin border) or invert it; verify body text clears WCAG AA (~4.5:1) against the dark bg | Critical if text unreadable; Major if asset clashes |
+| 12 | **Left-align grid** (reading flow) | **Poster slides feel flat**: covers, one-line quotes, hero numbers want optical centering | Allow centering as a declared exception for cover/quote/hero slide types only; or use a golden-ratio (38/62) indent so left-aligned still reads centered | Minor (taste); Major if a hero slide reads weak |
+
+**How the gate uses this matrix:** Pass A (**System Contract / Constraint Integrity**) owns the *rule* side: is the mechanical rule actually applied and consistent — palette, semantic tags, keep-all baseline, asset contract. Pass B (**Audience Impact / Expressive Readability**) owns the *side-effect / compensation* side: open the PNG and judge ragged lines, clipping, banding, flat hierarchy, asset clash, then propose the compensation. A row's side effect found on a key slide at the listed severity blocks `Proceed` if Critical, and is reported for the user if Major.
+
+> This matrix is a living list. When a new mechanical rule is added to the framework, add its side effect and compensation here in the same turn — a rule without a documented side effect is an incomplete rule.
+
+---
+
+## Relationship to the other references
+
+- `design-rules.md` — packaged hard rules (spec, assets, review loop). The gate assumes these are already satisfied.
+- `beautiful-slide-defaults.md` — the source of the art-direction checks above; read it for the full rationale.
+- `detailed-design-rules.md` — typography scale and color-usage detail behind checks 2 and 6.
+- `design-system-full.md` — archived deep-dive for advanced pattern guidance.

package/skills/slides-grab-design/references/design-rules.md

@@ -24,6 +24,14 @@ These are the packaged design rules for installable `slides-grab` skills.
 - Avoid emoji as the default icon treatment; only use emoji when the brief explicitly calls for them.
 - Keep icons visually consistent within a deck (stroke weight, size, and color should follow the slide's design tokens).
 
+## Chart guidance
+- Use Chart.js as the default charting library for quantitative slides; `templates/chart.html` is the packaged starting point.
+- Keep chart scripts inside the relevant `slide-*.html` file and initialize charts after the target `<canvas>` exists.
+- Use `animation: false`, `responsive: true`, and `maintainAspectRatio: false` for deterministic validation, viewer preview, and export.
+- Put each `<canvas>` inside a stable fixed-size or flex-stable wrapper so the layout box and drawing buffer are non-zero.
+- Use real data from the outline/research notes, label sample data as sample/synthetic, and avoid decorative pseudo-charts for data claims.
+- Run `slides-grab validate --slides-dir <path>` and fix any `empty-canvas` error before building the viewer or exporting.
+
 ## Asset rules
 - Store deck-local assets in `<slides-dir>/assets/`
 - Reference deck-local assets as `./assets/<file>`
@@ -52,15 +60,16 @@ These are the packaged design rules for installable `slides-grab` skills.
 - `templates/diagram.html`
 - `templates/diagram-tldraw.html`
 - `templates/custom/`
-- `templates/design-styles/README.md` — bundled design collection reference derived from `corazzon/pptx-design-styles`
-- `templates/design-styles/preview.html` — visual gallery of all 35 styles (open with `slides-grab preview-styles`)
-- `src/design-styles-data.js` — full style specs (colors, fonts, layout, signature elements, things to avoid) for all 35 bundled styles; read this after the user picks a style to ground your design tokens
+- `templates/design-styles/README.md` — bundled design collection reference derived from `corazzon/pptx-design-styles` and `epoko77-ai/design-diversity`
+- `templates/design-styles/preview.html` — visual gallery of all 95 styles (open with `slides-grab preview-styles`)
+- `src/design-styles-data.js` and `src/design-diversity-data.js` — full style specs (colors, fonts, layout, signature elements, things to avoid) for all 95 bundled styles; read these after the user picks a style to ground your design tokens
 
 ## Review loop
 - The design style is chosen in Stage 1 (Plan) and recorded in `slide-outline.md`'s meta section (`style: <id>`). Do not re-open style selection in Stage 2 — read and apply the already-approved style.
 - Generate or edit only the needed slide files.
 - Prefer `slides-grab image` before remote image sourcing when the slide needs bespoke imagery.
 - Prefer `tldraw` for complex diagrams instead of hand-building dense diagram geometry in HTML/CSS.
+- Prefer Chart.js for charts and verify the generated `viewer.html` when a deck contains `<canvas>` charts.
 - Re-run validation after every generation/edit pass.
 - Rebuild the viewer only after validation passes.
 - Do not move to export until the user approves the reviewed deck.