@w3kits-com/plugin-opendesign 0.1.8 → 0.1.9

package/dist/__w3kits/assets/design-templates/html-ppt/references/animations.md

@@ -0,0 +1,147 @@
+# Animations catalog
+
+All animations live in `assets/animations/animations.css`. Apply them by
+adding `class="anim-<name>"` OR `data-anim="<name>"` to any element
+(`runtime.js` re-triggers `data-anim` elements whenever a slide becomes
+active, so you get the entry effect every time you navigate onto the slide).
+
+Open `templates/animation-showcase.html` to browse all of them — one slide
+per animation, auto-playing on slide enter. Press **A** on any slide to cycle
+a random animation on the current page.
+
+## Directional fades
+
+| name | effect | use for |
+|---|---|---|
+| `fade-up` | Translate from +32 px, fade. | Default for paragraph + card entry. |
+| `fade-down` | Translate from -32 px, fade. | Headers / banners / callouts. |
+| `fade-left` | Translate from -40 px. | Left column in a two-column layout. |
+| `fade-right` | Translate from +40 px. | Right column in a two-column layout. |
+
+## Dramatic entries
+
+| name | effect | use for |
+|---|---|---|
+| `rise-in` | +60 px rise + blur-off. | Slide titles, hero headlines. |
+| `drop-in` | -60 px drop + slight scale. | Banners, alert bars. |
+| `zoom-pop` | Scale 0.6 → 1.04 → 1. | Buttons, stat numbers, CTAs. |
+| `blur-in` | 18 px blur clears. | Cover page reveal. |
+| `glitch-in` | Clip-path steps + jitter. | Tech / cyber / error states. |
+
+## Text effects
+
+| name | effect | use for |
+|---|---|---|
+| `typewriter` | Monospace-like type reveal. | One-liners, slogans. |
+| `neon-glow` | Cyclic text-shadow pulse. | Terminal-green / dracula themes. |
+| `shimmer-sweep` | White sheen passes across. | Metallic buttons, premium cards. |
+| `gradient-flow` | Infinite horizontal gradient slide. | Brand wordmarks. |
+
+## Lists & numbers
+
+| name | effect | use for |
+|---|---|---|
+| `stagger-list` | Children rise-in one-by-one. | Any `<ul>` or `.grid`. |
+| `counter-up` | Number ticks 0 → target. | KPI, stat-highlight pages. |
+
+Counter markup:
+```html
+<span class="counter" data-to="1248">0</span>
+```
+
+## SVG / geometry
+
+| name | effect | use for |
+|---|---|---|
+| `path-draw` | Strokes draw themselves. | Lines, arrows, diagrams. |
+| `morph-shape` | Path `d` morph. | Background shapes. |
+
+Put `class="anim-path-draw"` on `<svg>`; every path/line/circle inside gets drawn.
+
+## 3D & perspective
+
+| name | effect | use for |
+|---|---|---|
+| `parallax-tilt` | Hover → 3D tilt. | Hero cards, product shots. |
+| `card-flip-3d` | Y-axis 90° flip. | Before/after reveal. |
+| `cube-rotate-3d` | Rotate in from a cube side. | Section dividers. |
+| `page-turn-3d` | Left-hinge page turn. | Editorial / story flows. |
+| `perspective-zoom` | Pull from -400 Z. | Cover openings. |
+
+## Ambient / continuous
+
+| name | effect | use for |
+|---|---|---|
+| `marquee-scroll` | Infinite horizontal loop. | Client logo strips. |
+| `kenburns` | 14 s slow zoom on images. | Hero backgrounds. |
+| `confetti-burst` | Pseudo-element sparkle burst. | Thanks / win pages. |
+| `spotlight` | Circular clip-path reveal. | Big reveal moments. |
+| `ripple-reveal` | Corner-origin ripple reveal. | Section transitions. |
+
+## Respecting motion preferences
+
+All animations are disabled automatically when
+`prefers-reduced-motion: reduce` is set. Do not override this.
+
+## Tips
+
+- Prefer `data-anim="..."` over `class="anim-..."` so that the runtime
+  re-triggers the animation whenever the slide becomes active.
+- Use at most 1-2 distinct animation types on a single slide. Mixing 5 looks
+  messy.
+- Stagger lists + a single hero entry = clean rhythm.
+- For counter-up, pair with `stat-highlight.html` or `kpi-grid.html`.
+
+## FX (canvas)
+
+CSS animations are fire-and-forget entry effects. **FX** are live, continuously
+running canvas/DOM effects that start when their slide becomes active and stop
+when it leaves. They are loaded by `assets/animations/fx-runtime.js`, which
+dynamically pulls every module under `assets/animations/fx/*.js` and watches
+`.slide.is-active` to run lifecycle.
+
+Add to any page:
+```html
+<script src="../assets/animations/fx-runtime.js"></script>
+```
+
+Then drop one of these into any slide:
+```html
+<div data-fx="particle-burst" style="width:100%;height:360px;"></div>
+```
+
+The container just needs a size — the FX auto-sizes a canvas to fit with
+`ResizeObserver` + DPR correction. Colors read your theme (`--accent`,
+`--accent-2`, `--ok`, `--warn`, `--danger`).
+
+| name | effect | use case | trigger |
+|---|---|---|---|
+| `particle-burst` | Particles explode from center, gravity + fade, re-bursts every 2.5s. | Reveal moments, stat pages. | `<div data-fx="particle-burst">` |
+| `confetti-cannon` | Colored rotating rects arcing from both bottom corners. | Thank you / success pages. | `<div data-fx="confetti-cannon">` |
+| `firework` | Rockets from bottom explode into colored sparks, continuous. | Celebration, launch slides. | `<div data-fx="firework">` |
+| `starfield` | 3D perspective starfield flying outward. | Sci-fi / deep space backgrounds. | `<div data-fx="starfield">` |
+| `matrix-rain` | Falling green katakana + hex columns. | Cyber / security / data theme. | `<div data-fx="matrix-rain">` |
+| `knowledge-graph` | Force-directed graph, 28 labeled nodes, ~50 edges, live physics. | Knowledge / RAG / graph slides. | `<div data-fx="knowledge-graph">` |
+| `neural-net` | 4-6-6-3 feedforward net with pulses traveling along edges. | ML / model architecture slides. | `<div data-fx="neural-net">` |
+| `constellation` | Drifting points, linked when within 150 px, opacity by distance. | Ambient hero backgrounds. | `<div data-fx="constellation">` |
+| `orbit-ring` | 5 concentric rings with dots at different speeds, radial glow. | System / planet / layered concepts. | `<div data-fx="orbit-ring">` |
+| `galaxy-swirl` | Logarithmic spiral of ~800 particles, slow rotation. | Cover pages, intros. | `<div data-fx="galaxy-swirl">` |
+| `word-cascade` | Words fall from top, pile up at bottom. | Vocabulary / concept cloud slides. | `<div data-fx="word-cascade">` |
+| `letter-explode` | Heading letters fly in from random directions, loops every ~4.5s. | Big titles, hero text. | `<div data-fx="letter-explode" data-fx-text-value="EXPLODE">` |
+| `chain-react` | 8 circles with a domino pulse wave traveling across. | Pipeline / sequential flow. | `<div data-fx="chain-react">` |
+| `magnetic-field` | Particles travel bezier/sin curves leaving trails. | Energy / flow / abstract. | `<div data-fx="magnetic-field">` |
+| `data-stream` | Rows of scrolling hex/binary text, cyberpunk. | Data, API, security. | `<div data-fx="data-stream">` |
+| `gradient-blob` | 4 drifting blurred radial gradients (additive). | Soft hero backgrounds. | `<div data-fx="gradient-blob">` |
+| `sparkle-trail` | Pointer-driven sparkle emitter (auto-wiggles if idle). | Interactive reveal, hover canvases. | `<div data-fx="sparkle-trail">` |
+| `shockwave` | Expanding rings from center on loop. | Impact, launch, alert. | `<div data-fx="shockwave">` |
+| `typewriter-multi` | 3 lines typing concurrently with blinking block cursors (DOM). | Terminal, agent boot log. | `<div data-fx="typewriter-multi" data-fx-line1="> boot...">` |
+| `counter-explosion` | Number counts 0 → target, bursts particles, resets after 4s. | KPI reveal, record highs. | `<div data-fx="counter-explosion" data-fx-to="2400">` |
+
+FX tips:
+- One FX per slide is almost always enough. Mix with regular CSS `data-anim`
+  effects for layered polish.
+- The container needs an explicit size (height) — the canvas fills 100%.
+- Every module respects theme custom properties. Set `--accent` / `--accent-2`
+  on the slide or element to recolor on the fly.
+- Lifecycle is automatic: entering a slide starts the FX, leaving stops it and
+  frees the canvas. You can also call `window.__hpxReinit(el)` manually.

package/dist/__w3kits/assets/design-templates/html-ppt/references/authoring-guide.md

@@ -0,0 +1,141 @@
+# Authoring guide
+
+How to turn a user request ("make me a deck about X") into a finished
+html-ppt deck. Follow these steps in order.
+
+## 1. Understand the deck
+
+Before touching files, clarify:
+
+1. **Audience** — engineers? designers? executives? consumers?
+2. **Length** — 5 min lightning? 20 min share? 45 min talk?
+3. **Language** — Chinese, English, bilingual? (Noto Sans SC is preloaded.)
+4. **Format** — on-screen live, PDF export, 小红书图文?
+5. **Tone** — clinical / playful / editorial / cyber?
+
+The audience + tone map to a theme; the length maps to slide count; the
+format maps to runtime features (live → notes + T-cycle; PDF → page-break
+CSS, already handled in `base.css`).
+
+## 2. Pick a theme
+
+Use `references/themes.md`. When in doubt:
+
+- **Engineers** → `catppuccin-mocha` / `tokyo-night` / `dracula`.
+- **Designers / product** → `editorial-serif` / `aurora` / `soft-pastel`.
+- **Execs** → `minimal-white` / `arctic-cool` / `swiss-grid`.
+- **Consumers** → `xiaohongshu-white` / `sunset-warm` / `soft-pastel`.
+- **Cyber / CLI / infra** → `terminal-green` / `blueprint` / `gruvbox-dark`.
+- **Pitch / bold** → `neo-brutalism` / `sharp-mono` / `bauhaus`.
+- **Launch / product reveal** → `glassmorphism` / `aurora`.
+
+Wire the theme as `<link id="theme-link" href="../assets/themes/NAME.css">`
+and list 3-5 alternatives in `data-themes` so the user can press T to audition.
+
+## 3. Outline the deck
+
+A solid 20-minute deck is usually:
+
+```
+cover → toc → section-divider #1 → [2-4 body pages] →
+section-divider #2 → [2-4 body pages] → section-divider #3 →
+[2-4 body pages] → cta → thanks
+```
+
+Pick 1 layout per page from `references/layouts.md`. Don't repeat the same
+layout twice in a row.
+
+## 4. Scaffold the deck
+
+```bash
+./scripts/new-deck.sh my-talk
+```
+
+This copies `templates/deck.html` into `examples/my-talk/index.html` with
+paths rewritten. Add/remove `<section class="slide">` blocks to match your
+outline.
+
+## 5. Author each slide
+
+For each outline item:
+
+1. Open the matching single-page layout, e.g. `templates/single-page/kpi-grid.html`.
+2. Copy the `<section class="slide">…</section>` block.
+3. Paste into your deck.
+4. Replace demo data with real data. Keep the class structure intact.
+5. Set `data-title="..."` (used by the Overview grid).
+6. Add `<div class="notes">…</div>` with speaker notes.
+
+## 6. Add animations sparingly
+
+Rules of thumb:
+
+- Cover/title: `rise-in` or `blur-in`.
+- Body content: `fade-up` for the hero element, `stagger-list` for grids/lists.
+- Stat pages: `counter-up`.
+- Section dividers: `perspective-zoom` or `cube-rotate-3d`.
+- Closer: `confetti-burst` on the "Thanks" text.
+
+Pick **one** accent animation per slide. Everything else should be calm.
+
+## 7. Chinese + English decks
+
+- Fonts are already imported in `fonts.css` (Noto Sans SC + Noto Serif SC).
+- Use `lang="zh-CN"` on `<html>`.
+- For bilingual titles, stack lines: `<h1 class="h1">主标题<br><span class="dim">English subtitle</span></h1>`.
+- Keep English subtitles in a lighter weight (300) and dim color to avoid
+  visual competition.
+
+## 8. Review in-browser
+
+```bash
+open examples/my-talk/index.html
+```
+
+Walk through every slide with ← →. Press:
+
+- **O** — overview grid; catch any layout clipping.
+- **T** — cycle themes; make sure nothing looks broken in any theme.
+- **S** — open speaker notes; verify every slide has notes.
+
+## 9. Export to PNG
+
+```bash
+# single slide
+./scripts/render.sh examples/my-talk/index.html
+
+# all slides (autodetect count by looking for .slide sections)
+./scripts/render.sh examples/my-talk/index.html all
+
+# explicit slide count + output dir
+./scripts/render.sh examples/my-talk/index.html 12 out/my-talk-png
+```
+
+Output is 1920×1080 by default. Change in `render.sh` if the user wants 3:4
+for 小红书图文 (1242×1660).
+
+## 10. What to NOT do
+
+- Don't hand-author from a blank file.
+- Don't use raw hex colors in slide markup. Use tokens.
+- Don't load heavy animation frameworks. Everything should stay within the
+  CSS/JS that already ships.
+- Don't add more than one new template file unless a genuinely new layout
+  type is needed. Prefer composition.
+- Don't delete slides from the showcase decks.
+- **Don't put presenter-only text on the slide.** Any descriptive text,
+  narration cues, or explanations meant for the speaker (e.g. "这一页的重点是…",
+  "Note: mention X here", small grey captions explaining the slide's purpose)
+  MUST go inside `<div class="notes">`, not as visible elements. The `.notes`
+  div is hidden (`display:none`) and only shown via the S overlay. Slides
+  should contain ONLY audience-facing content.
+
+## Troubleshooting
+
+- **Theme doesn't switch with T**: check `data-themes` on `<body>` and
+  `data-theme-base` pointing to the themes directory relative to the HTML
+  file.
+- **Fonts fall back**: make sure `fonts.css` is linked before the theme.
+- **Chart.js colors wrong**: charts read CSS vars in JS; make sure they run
+  after the DOM is ready (`addEventListener('DOMContentLoaded', …)`).
+- **PNG too small**: bump `--window-size` in `scripts/render.sh`.

package/dist/__w3kits/assets/design-templates/html-ppt/references/full-decks.md

@@ -0,0 +1,98 @@
+# Full-Deck Templates
+
+Self-contained multi-slide HTML decks under `templates/full-decks/<name>/`. Each folder contains:
+
+- `index.html` — complete multi-slide deck (cover / section / content / code / chart or diagram / CTA / thanks, 7+ slides)
+- `style.css` — scoped with `.tpl-<name>` class prefix so multiple templates can coexist
+- `README.md` — short rationale, inspiration, and use guidance
+
+All templates pull the shared `assets/fonts.css`, `assets/base.css`, and `assets/runtime.js` from the skill root. Navigate with `← →` / `space`, use `F` for fullscreen, `O` for overview.
+
+Use these when you want a coherent, opinionated look for an entire deck — not a mix-and-match of layouts. Each template is visually distinctive enough to be identified at a glance.
+
+---
+
+## 1. xhs-white-editorial — 白底杂志风
+
+- **Source inspiration:** `20260409 升级版知识库/小红书图文/v2-白底版/slide_01_cover.html` + `20260412-AI测试与安全/html/xhs-ai-testing-safety-v2.html`
+- **Key visual traits:** pure-white background, top 10-color rainbow bar, 80-110px display headlines, purple→blue→green→orange→pink gradient text, macaron soft-card set (soft-purple/pink/blue/green/orange), black-on-white `.focus` pills, hero quote box.
+- **When to use:** dual-purpose XHS image + horizontal deck; dense text with strong emphasis; Chinese-first audience.
+- **Path:** `templates/full-decks/xhs-white-editorial/index.html`
+
+## 2. graphify-dark-graph — 暗底知识图谱
+
+- **Source inspiration:** `20260413-graphify/ppt/graphify.html`
+- **Key visual traits:** `#06060c→#0e1020` deep-night gradient, drifting blur orbs, SVG force-directed graph overlay on cover, rainbow-shift gradient headlines, JetBrains Mono command-line glow, glass-morphism cards (warm/blue/green/purple/danger). Accent palette: amber `#e8a87c`, mint `#7ed3a4`, mist-blue `#7eb8da`, lilac `#b8a4d6`.
+- **When to use:** dev-tool / CLI / knowledge-graph / data-viz launches; live-demo decks that want an "AI-native + sci-fi + warm" vibe.
+- **Path:** `templates/full-decks/graphify-dark-graph/index.html`
+
+## 3. knowledge-arch-blueprint — 奶油蓝图架构
+
+- **Source inspiration:** `20260405-Karpathy-知识库/20260405 架构图v2.html`
+- **Key visual traits:** cream paper `#F0EAE0` base, single rust accent `#B5392A`, 48px blueprint grid mask, hard 2px black border cards, pipeline step-boxes with one hero raised, right-side rust insight callout, Playfair serif big numbers, SVG dashed feedback-loop arrows. Zero gradients, zero soft shadows.
+- **When to use:** system architecture diagrams, data-flow maps, engineering white-papers; you want a serious, printable, README-friendly feel.
+- **Path:** `templates/full-decks/knowledge-arch-blueprint/index.html`
+
+## 4. hermes-cyber-terminal — 暗终端 honest-review
+
+- **Source inspiration:** `20260414-hermes-agent/ppt/hermes-record.html` + `hermes-vs-openclaw.html`
+- **Key visual traits:** `#0a0c10` black, 56px cyber grid + CRT vignette + scanlines, window traffic-light chrome, `$ prompt` command-line headlines, mint-green `#7ed3a4` glow big text, JetBrains Mono throughout, stroke-only bar charts, blinking cursor, amber/green/red tag hierarchy, dark code box.
+- **When to use:** reviews of CLI / agent / dev tools with trace, diff, and benchmarks; when you want the "honest technical reviewer" voice.
+- **Path:** `templates/full-decks/hermes-cyber-terminal/index.html`
+
+## 5. obsidian-claude-gradient — GitHub 暗紫渐变
+
+- **Source inspiration:** `20260406-obsidian-claude/slides.html`
+- **Key visual traits:** GitHub-dark `#0d1117`, purple+blue radial ambient plus 60px masked grid, center-aligned layout, purple pill tags, three-stop gradient text `#a855f7→#60a5fa→#34d399`, GitHub-ish code palette (`#010409` bg + purple/blue/orange/green tokens), purple-left-border highlight block.
+- **When to use:** developer workflow / MCP / Agent / dev-tool tutorials; feels like GitHub Blog / Linear Changelog; config + steps heavy content.
+- **Path:** `templates/full-decks/obsidian-claude-gradient/index.html`
+
+## 6. testing-safety-alert — 红琥珀警示
+
+- **Source inspiration:** `20260412-AI测试与安全/html/xhs-ai-testing-safety-v2.html`
+- **Key visual traits:** top and bottom 45° red-black hazard stripes, red strike-through negation headlines, L1/L2/L3 green/amber/red tier cards, alert-box with circular status dot, policy-yaml code block with red left border and `bad` keyword highlighting, red/green checklist, Q1 incident stacked bar chart.
+- **When to use:** safety / risk / incident post-mortem / red-team / pre-launch AI review / policy-as-code; when the audience needs to feel "this is serious, don't skim".
+- **Path:** `templates/full-decks/testing-safety-alert/index.html`
+
+## 7. xhs-pastel-card — 柔和马卡龙慢生活
+
+- **Source inspiration:** `20260412-obsidian-skills/html/xhs-obsidian-skills.html` + pastel patterns shared with `20260409` v2-白底版
+- **Key visual traits:** cream `#fef8f1` base, three soft blurred blobs, Playfair italic serif display headlines mixed with sans body, full-color 28px rounded macaron cards (peach / mint / sky / lilac / lemon / rose), italic Playfair `01-04` numerals, SVG donut chart, chip+page topbar.
+- **When to use:** lifestyle / personal-growth / slow-living / emotional content; when you want a "magazine, handmade, not-so-techy" feel; themes like rest, pause, softness.
+- **Path:** `templates/full-decks/xhs-pastel-card/index.html`
+
+## 8. dir-key-nav-minimal — 方向键 8 色极简
+
+- **Source inspiration:** `20260405-Karpathy-知识库/20260405 演示幻灯片【方向键版】.html`
+- **Key visual traits:** 8 slides each on its own mono background (indigo / cream / crimson / emerald / slate / violet / white / charcoal), each with its own accent color, 160px display headline + 4px stubby accent line divider, arrow `→` prefixed Mono list, bottom-left `← →` kbd hint plus bottom-right page label, huge breathing negative space.
+- **When to use:** keynote-style minimalist talk where you have something to say and not much to show; one idea per slide; talks / launches / public presentations.
+- **Path:** `templates/full-decks/dir-key-nav-minimal/index.html`
+
+---
+
+## Scenario decks (generic, reusable)
+
+These are not extracted from a single source — they are generic scaffolds for the most common presentation jobs. Each is visually distinctive and content-rich out of the box.
+
+| # | Name | Slides | Feel | When to use |
+|---|---|---|---|---|
+| 9  | `pitch-deck`       | 10 | White + blue→purple gradient, YC/VC vibe, big numbers, traction chart | Fundraising, startup pitch, investor meeting |
+| 10 | `product-launch`   | 8  | Dark hero + light content, warm orange→peach, feature cards, pricing tiers, CTA | Announcing a product, launch keynote |
+| 11 | `tech-sharing`     | 8  | GitHub-dark, JetBrains Mono, terminal code blocks, agenda + Q&A | 技术分享, internal tech talk, conference talk |
+| 12 | `weekly-report`    | 7  | Corporate clarity, 8-cell KPI grid, shipped list, 8-week bar chart, next-week table | 周报, team status update, business review |
+| 13 | `xhs-post`         | 9  | **3:4 @ 810×1080**, warm pastel, dashed sticker cards, page dots | 小红书 图文 post, Instagram carousel |
+| 14 | `course-module`    | 7  | Warm paper + Playfair serif, persistent left sidebar of learning objectives, MCQ self-check | 教学模块, online course, workshop module |
+| 15 | `presenter-mode-reveal` 🎤 | 6  | **演讲者模式专用** · tokyo-night 默认 · 5 主题 T 键切换 · 每页带 150–300 字逐字稿示例 | **技术分享/演讲/课程**—需要按 S 键看逐字稿的场景 ✨ |
+
+Each folder: `index.html`, scoped `style.css` (prefixed `.tpl-<name>`), `README.md`. The `xhs-post` template overrides the default `.slide` box to fixed `810×1080` for 3:4 portrait.
+
+> 🎤 **任何演讲场景（技术分享 / 课程 / 路演）都推荐用 `presenter-mode-reveal`**，或者参考 [presenter-mode.md](./presenter-mode.md) 指南给其他模板加 `<aside class="notes">` 逐字稿。
+
+---
+
+## Authoring notes
+
+- Every template scopes its CSS under `.tpl-<name>` so two or more templates can load on the same page without collisions.
+- Swap demo content, but keep the structural classes — they are what gives each template its identity.
+- The shared runtime (`assets/runtime.js`) provides keyboard nav, fullscreen, overview grid, theme cycling — you don't need to add any JS.
+- Charts are hand-rolled SVG (no CDN dependency). Feel free to replace with chart.js / echarts if you need interactive data.

package/dist/__w3kits/assets/design-templates/html-ppt/references/layouts.md

@@ -0,0 +1,103 @@
+# Layouts catalog
+
+Every layout lives in `templates/single-page/<name>.html` as a fully
+functional standalone page with realistic demo data. Open any file directly
+in Chrome to see it working.
+
+To compose a new deck: open the file, copy the `<section class="slide">…</section>`
+block (or multiple blocks) into your deck HTML, and replace the demo data.
+Shared CSS (base, theme, animations) is already wired by `deck.html`.
+
+## Openers & transitions
+
+| file | purpose |
+|---|---|
+| `cover.html` | Deck cover. Kicker + huge title + lede + pill row. |
+| `toc.html` | Table of contents. 2×3 grid of numbered cards. |
+| `section-divider.html` | Big numbered section break (02 · Theme). |
+
+## Text-centric
+
+| file | purpose |
+|---|---|
+| `bullets.html` | Classic bullet list with card-wrapped items. |
+| `two-column.html` | Concept + example side by side. |
+| `three-column.html` | Three equal pillars with icons. |
+| `big-quote.html` | Full-bleed pull quote in editorial-serif style. |
+
+## Numbers & data
+
+| file | purpose |
+|---|---|
+| `stat-highlight.html` | One giant number + subtitle (uses `.counter` animation). |
+| `kpi-grid.html` | 4 KPIs in a row with up/down deltas. |
+| `table.html` | Data table with hover rows, right-aligned numerics. |
+| `chart-bar.html` | Chart.js bar chart, theme-aware colors. |
+| `chart-line.html` | Chart.js dual-line chart with filled area. |
+| `chart-pie.html` | Chart.js doughnut + takeaways card. |
+| `chart-radar.html` | Chart.js radar comparing 2 products on 6 axes. |
+
+## Code & terminal
+
+| file | purpose |
+|---|---|
+| `code.html` | Syntax-highlighted code via highlight.js (JS example). |
+| `diff.html` | Hand-rolled +/- diff view. |
+| `terminal.html` | Terminal window mock with traffic-light header. |
+
+## Diagrams & flows
+
+| file | purpose |
+|---|---|
+| `flow-diagram.html` | 5-node pipeline with arrows and one highlighted node. |
+| `arch-diagram.html` | 3-tier architecture grid. |
+| `process-steps.html` | 4 numbered steps in cards. |
+| `mindmap.html` | Radial mindmap with SVG path-draw animation. |
+
+## Plans & comparisons
+
+| file | purpose |
+|---|---|
+| `timeline.html` | 5-point horizontal timeline with dots. |
+| `roadmap.html` | 4-column NOW / NEXT / LATER / VISION. |
+| `gantt.html` | 12-week gantt chart with 5 parallel tracks. |
+| `comparison.html` | Before vs After two-panel card. |
+| `pros-cons.html` | Pros and cons two-card layout. |
+| `todo-checklist.html` | Checklist with checked/unchecked states. |
+
+## Visuals
+
+| file | purpose |
+|---|---|
+| `image-hero.html` | Full-bleed hero with Ken Burns gradient background. |
+| `image-grid.html` | 7-cell bento grid with gradient placeholders. |
+
+## Closers
+
+| file | purpose |
+|---|---|
+| `cta.html` | Call-to-action with big gradient headline + buttons. |
+| `thanks.html` | Final "Thanks" page with confetti burst. |
+
+## Picking a layout
+
+- **Opener**: `cover.html`, often followed by `toc.html`.
+- **Section break**: `section-divider.html` before every major section.
+- **Core content**: `bullets.html`, `two-column.html`, `three-column.html`.
+- **Show numbers**: `stat-highlight.html` (single) or `kpi-grid.html` (4-up).
+- **Show plot**: `chart-bar.html` / `chart-line.html` / `chart-pie.html` / `chart-radar.html`.
+- **Show a diff or change**: `comparison.html`, `diff.html`, `pros-cons.html`.
+- **Show a plan**: `timeline.html`, `roadmap.html`, `gantt.html`, `process-steps.html`.
+- **Show architecture**: `arch-diagram.html`, `flow-diagram.html`, `mindmap.html`.
+- **Code / demo**: `code.html`, `terminal.html`.
+- **Closer**: `cta.html` → `thanks.html`.
+
+## Naming / structure conventions
+
+- Each slide is `<section class="slide" data-title="...">`.
+- Header pills: `<p class="kicker">…</p>`, eyebrow: `<p class="eyebrow">…</p>`.
+- Titles: `<h1 class="h1">…</h1>` / `<h2 class="h2">…</h2>`.
+- Lede: `<p class="lede">…</p>`.
+- Cards: `<div class="card">…</div>` (variants: `card-soft`, `card-outline`, `card-accent`).
+- Grids: `.grid.g2`, `.grid.g3`, `.grid.g4`.
+- Notes: `<div class="notes">…</div>` per slide.