first-commit

skills/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.

skills/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`.

skills/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.

skills/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.

skills/html-ppt/references/presenter-mode.md

@@ -0,0 +1,240 @@
+# Presenter Mode Guide · 演讲者模式指南
+
+这份文档说明如何在 html-ppt skill 里做出**带逐字稿的演讲者模式 PPT**。
+
+## 何时使用演讲者模式
+
+当用户的需求涉及以下任何一项时，**优先使用演讲者模式**：
+
+- 提到"**演讲**"、"**分享**"、"**讲稿**"、"**逐字稿**"、"**speaker notes**"
+- 提到"**presenter view**"、"**演讲者视图**"、"**演讲者模式**"
+- 需要"**30 分钟 / 45 分钟 / 1 小时**的分享"
+- 说"我要去给团队讲 xxx"、"要做一场技术分享"、"要做路演"
+- 强调"**不想忘词**"、"**怕讲不流畅**"、"**需要提词器**"
+
+如果用户只要做一份"静态好看的 PPT"（例如小红书图文、产品图册、汇报 slides 自己不讲），**不需要**演讲者模式。
+
+## 两种做法
+
+### ✅ 推荐做法：直接用 `presenter-mode-reveal` 模板
+
+```bash
+cp -r templates/full-decks/presenter-mode-reveal examples/my-talk
+```
+
+这个模板已经预设好所有必需元素：
+- 支持 S 键切换演讲者视图
+- 5 个主题可用 T 键循环（tokyo-night / dracula / catppuccin-mocha / nord / corporate-clean）
+- 左右键翻页
+- 每一页都有 150–300 字的示例逐字稿
+- 底部有键位提示
+
+直接改内容即可。
+
+### 🔧 进阶做法：给任意已有模板加演讲者模式
+
+html-ppt 的 **S 键演讲者视图是 `runtime.js` 内置的，所有 full-deck 模板都自动支持**。你只需要做两件事：
+
+1. **每张 slide 末尾加 `<aside class="notes">`**（或 `<div class="notes">`），里面写逐字稿
+2. **确认 HTML 引入了 `assets/runtime.js`**
+
+```html
+<section class="slide">
+  <h2>你的标题</h2>
+  <p>内容...</p>
+  <aside class="notes">
+    <p>这里是演讲时要说的话，150-300 字...</p>
+  </aside>
+</section>
+```
+
+## 逐字稿写作三铁律
+
+这是整个方法论的核心。AI 在帮用户写逐字稿时必须遵守：
+
+### 铁律 1：不是讲稿，是"提示信号"
+
+❌ **错误写法**（像在念稿）：
+```
+大家好，欢迎来到今天的分享。今天我将要给大家介绍一下我们团队在过去三个月做的工作。
+首先，我们来看一下背景情况。在过去的三个月中，我们遇到了以下几个问题……
+```
+
+✅ **正确写法**（提示信号 + 加粗核心）：
+```
+<p>欢迎！今天分享我们团队<strong>过去 3 个月</strong>的工作。</p>
+<p>先说<em>背景</em>——三个月前我们遇到了<strong>三个核心问题</strong>：
+延迟高、成本炸、稳定性差。</p>
+<p>接下来逐个讲解怎么解的。</p>
+```
+
+**差别**：正确版本把关键词加粗，过渡句独立成段，看一眼就能接上。
+
+### 铁律 2：每页 150–300 字
+
+- **少于 150 字**：提示不够，讲到一半会卡
+- **多于 300 字**：你根本来不及扫完
+- **2–3 分钟/页** 是最舒服的节奏
+
+### 铁律 3：用口语，不用书面语
+
+| ❌ 书面语 | ✅ 口语 |
+|---|---|
+| 因此 | 所以 |
+| 该方案 | 这个方案 |
+| 然而 | 但是 / 不过 |
+| 进行优化 | 优化一下 |
+| 我们将会 | 我们会 / 接下来 |
+| 综上所述 | 所以简单来说 |
+
+**检查方法**：写完读一遍，听起来像说话才对。
+
+## 必备 HTML 结构
+
+```html
+<!DOCTYPE html>
+<html lang="zh-CN" data-themes="tokyo-night,dracula,corporate-clean">
+<head>
+  <meta charset="utf-8">
+  <title>...</title>
+  <link rel="stylesheet" href="../../../assets/fonts.css">
+  <link rel="stylesheet" href="../../../assets/base.css">
+  <link rel="stylesheet" id="theme-link" href="../../../assets/themes/tokyo-night.css">
+  <link rel="stylesheet" href="../../../assets/animations/animations.css">
+  <link rel="stylesheet" href="style.css">
+</head>
+<body>
+<div class="deck">
+
+  <section class="slide" data-title="Cover">
+    <h1>你的标题</h1>
+    <p>副标题</p>
+    <aside class="notes">
+      <p>讲稿段落 1（加<strong>加粗关键词</strong>）。</p>
+      <p>讲稿段落 2（过渡句独立成段）。</p>
+      <p>讲稿段落 3（自然收尾，引出下一页）。</p>
+    </aside>
+  </section>
+
+  <!-- 更多 slide ... -->
+
+</div>
+<script src="../../../assets/runtime.js"></script>
+</body>
+</html>
+```
+
+## 演讲者视图显示的内容
+
+按 `S` 键后，**弹出一个独立的演讲者窗口**（原页面保持观众视图不变）。演讲者窗口是 **4 个独立的磁吸卡片**：
+
+```
+ 观众窗口（原页面）           演讲者窗口（磁吸卡片）
+┌─────────────────┐   ┌─────────────────────┬──────────────────┐
+│                 │   │ 🔵 CURRENT         │ 🟣 NEXT            │
+│  正常 slide     │   │ ━━━━━━━━━━━━━━━━ │ ━━━━━━━━━━━━━ │
+│  全屏展示       │◄►│                   │  iframe preview   │
+│                 │   │  iframe preview   │  （下一页）         │
+│                 │   │  （当前页）        ├──────────────────┤
+│                 │   │                   │ 🟠 SPEAKER SCRIPT  │
+│                 │   │                   │ ━━━━━━━━━━━━━ │
+│                 │   ├─────────────────────┤  [大字号逐字稿]   │
+│                 │   │ 🟢 TIMER           │  [可滚动]         │
+│                 │   │ ⏱ 12:34   3 / 8 │                   │
+│                 │   │ [← Prev][Next →]  │                   │
+└─────────────────┘   └─────────────────────┴──────────────────┘
+       ↑ BroadcastChannel 双向同步翻页 ↑
+```
+
+卡片交互规则：
+- **拖动卡片 header**（带彩色圆点和标题的顶部条）→ 移动卡片位置
+- **拖动卡片右下角的三角手柄** → 调整卡片大小
+- **位置/尺寸自动保存到 localStorage**，下次打开恢复
+- 底部 "重置布局" 按钮恢复默认排列
+
+卡片内容：
+- 🔵 **CURRENT** — 当前页 **像素级完美预览**（iframe 加载原 HTML 文件的 `?preview=N` 模式，错色不可能）
+- 🟣 **NEXT** — 下一页预览，同样像素级完美
+- 🟠 **SPEAKER SCRIPT** — 逐字稿，字号 18px，支持 `<strong>` (橘色加粗)、`<em>` (蓝色强调)、`<code>` 等 inline 样式
+- 🟢 **TIMER** — 计时器不会丢失焦点，带切页按钮
+
+两窗口同步：在任一窗口按 ← → 翻页，另一个窗口自动同步（BroadcastChannel）。
+
+丝滑翻页：iframe 只加载一次，后续翻页用 `postMessage` 切换可见的 slide，**不重新加载、不闪烁**。
+
+## 键盘快捷键（演讲者模式）
+
+| 键 | 动作 |
+|---|---|
+| `S` | 打开演讲者窗口（弹出新窗口，原页面保持观众视图） |
+| `←` `→` / Space / PgDn | 翻页（即使在演讲者视图里） |
+| `T` | 切换主题 |
+| `R` | 重置计时器（仅演讲者视图下） |
+| `F` | 全屏 |
+| `O` | 总览 |
+| `Esc` | 关闭所有浮层 |
+
+## 双屏演讲的标准流程
+
+1. 打开 `index.html`，按 `S` → 弹出演讲者窗口
+2. 把**观众窗口**（原页面）拖到投影 / 外接屏，按 `F` 全屏
+3. 把**演讲者窗口**（弹窗）留在你面前的屏幕
+4. 在任一窗口按 ← → 翻页，两边自动同步
+5. 演讲者窗口里看逐字稿 + 下一页 + 计时器
+
+> 💡 **为什么预览像素级完美**：每个预览是一个 `<iframe>`，它加载的就是同一个 deck HTML 文件，只是 URL 多了 `?preview=N` 参数。`runtime.js` 检测到这个参数时只渲染第 N 页、隐藏所有 chrome。**iframe 使用与观众视图完全相同的 CSS、主题、字体和 viewport**——颜色和排版保证一致。外层用 CSS `transform: scale()` 把 1920×1080 缩到卡片宽高，等比缩放不变形。
+
+> 💡 **为什么不闪烁**：iframe 初次加载后就常驻，翻页时 presenter 窗口通过 `postMessage({type:'preview-goto', idx:N})` 告诉 iframe 切换到第 N 页。iframe 内的 runtime.js 只切换 `.is-active` class，**不重新加载、不渲染白屏**。
+
+## 常见错误
+
+### ❌ 把逐字稿写在 slide 可见位置
+
+```html
+<!-- 错误：这段文字观众会看到 -->
+<p style="font-size:12px;color:gray">
+  这里讲 xxx，然后讲 yyy...
+</p>
+```
+
+✅ 正确：
+```html
+<aside class="notes">
+  <p>这里讲 xxx，然后讲 yyy...</p>
+</aside>
+```
+
+`.notes` 类默认 `display:none`，只在演讲者视图可见。
+
+### ❌ 忘记引入 runtime.js
+
+没有 `<script src="../../../assets/runtime.js"></script>` = 没有 S 键、没有演讲者视图、没有翻页。
+
+### ❌ 逐字稿用书面语
+
+念出来像 AI 机器人。**写完一定读一遍**。
+
+### ❌ 每页 50 字
+
+提示不够，照样忘词。
+
+### ❌ 每页 500 字
+
+眼睛根本扫不过来，等于没写。
+
+## 用 AI 生成逐字稿的标准 prompt
+
+> "请为每一张 slide 写一段 **150-300 字**的逐字稿，放在 `<aside class="notes">` 里。
+> 要求：
+> 1. 用**口语**，不要书面语（所以/但是/接下来，不是因此/然而/综上所述）
+> 2. 把**核心关键词**用 `<strong>` 加粗
+> 3. 过渡句独立成段（每段 1-3 句）
+> 4. 读起来像说话，不像念稿
+> 5. 结尾要有自然的过渡，引出下一页"
+
+## 推荐搭配
+
+- **主题**：`tokyo-night`（深色，技术分享首选）、`corporate-clean`（浅色，商务汇报）、`dracula`（深色备选）
+- **字体**：默认 Noto Sans SC + JetBrains Mono，无需更改
+- **动效**：克制使用，`fade-up` / `rise-in` 最自然，不要用 `glitch-in` / `confetti-burst` 之类花哨的
+- **页数**：30 分钟分享 = 8–12 页；45 分钟 = 12–16 页；1 小时 = 16–22 页

skills/html-ppt/references/themes.md

@@ -0,0 +1,107 @@
+# Themes catalog
+
+Every theme is a short CSS file in `assets/themes/` that overrides tokens
+defined in `assets/base.css`. Switch themes by changing the `href` of
+`<link id="theme-link">` or by pressing **T** if the deck has a
+`data-themes="a,b,c"` attribute on `<body>` or `<html>`.
+
+All themes define the same variables: `--bg`, `--bg-soft`, `--surface`,
+`--surface-2`, `--border`, `--text-1/2/3`, `--accent`, `--accent-2/3`,
+`--good`, `--warn`, `--bad`, `--grad`, `--grad-soft`, `--radius*`, `--shadow*`,
+`--font-sans`, `--font-display`.
+
+## Light & calm
+
+| name | description | when to use |
+|---|---|---|
+| `minimal-white` | 极简白，克制高级。Inter，强文字层级，极低阴影。 | 内部汇报、一对一技术评审、不抢内容的严肃话题 |
+| `editorial-serif` | 杂志风 Playfair 衬线 + 奶油底。 | 品牌故事、文字密度大的长文演讲 |
+| `soft-pastel` | 柔和马卡龙三色渐变。 | 产品发布、面向消费者、轻松话题 |
+| `xiaohongshu-white` | 小红书白底 + 暖红 accent + 衬线标题。 | 小红书图文、生活/美学类内容 |
+| `solarized-light` | 经典低眩光配色。 | 长时间观看的工作坊、教学 |
+| `catppuccin-latte` | catppuccin 浅色。 | 开发者、极客友好的技术分享 |
+
+## Bold & statement
+
+| name | description | when to use |
+|---|---|---|
+| `sharp-mono` | 纯黑白 + Archivo Black + 硬阴影。 | 宣言类、极具冲击力的视觉 |
+| `neo-brutalism` | 厚描边、硬阴影、明黄 accent。 | 创业路演、敢说敢做的调性 |
+| `bauhaus` | 几何 + 红黄蓝原色。 | 设计 talk、艺术史/产品美学主题 |
+| `swiss-grid` | 瑞士网格 + Helvetica 感 + 12 栏底纹。 | 严肃排版、设计行业 |
+| `memphis-pop` | 孟菲斯波普背景点 + 大字标题。 | 年轻、潮流、品牌合作 |
+
+## Cool & dark
+
+| name | description | when to use |
+|---|---|---|
+| `catppuccin-mocha` | catppuccin 深。 | 开发者内部分享、长时间观看 |
+| `dracula` | 经典 Dracula 紫红主色。 | 代码密集的技术分享 |
+| `tokyo-night` | Tokyo Night 蓝夜。 | 偏冷技术分享、基础设施 |
+| `nord` | 北欧清冷蓝白。 | 基础设施、云产品 |
+| `gruvbox-dark` | 温暖复古深色。 | Terminal / vim / *nix 社群 |
+| `rose-pine` | 玫瑰松，柔和暗色。 | 设计+开发交界、审美向技术 |
+| `arctic-cool` | 蓝/青/石板灰 浅色版。 | 商业分析、金融、冷静理性 |
+
+## Warm & vibrant
+
+| name | description | when to use |
+|---|---|---|
+| `sunset-warm` | 橘 / 珊瑚 / 琥珀三色渐变。 | 生活方式、奖项颁发、情绪正向 |
+
+## Effect-heavy
+
+| name | description | when to use |
+|---|---|---|
+| `glassmorphism` | 毛玻璃 + 多色光斑背景。 | Apple 式发布会、产品特性展示 |
+| `aurora` | 极光渐变 + blur + saturate。 | 封面 / CTA / 结语页 |
+| `rainbow-gradient` | 白底 + 彩虹流动渐变 accent。 | 欢乐向、节日、庆祝页 |
+| `blueprint` | 蓝图工程 + 网格底纹 + 蒙太奇字体。 | 系统架构、工程蓝图 |
+| `terminal-green` | 绿屏终端 + 等宽 + 发光文字。 | CLI/black-hat/复古朋克 |
+
+## v2 additions
+
+### Light & professional
+
+| name | description | when to use |
+|---|---|---|
+| `corporate-clean` | 纯白 + 海军蓝 accent + Inter + 保守边框。 | 董事会汇报、B2B 销售、金融保险 |
+| `pitch-deck-vc` | YC 风白底 + 蓝紫渐变 accent + 大留白。 | 融资路演、种子轮、VC meeting |
+| `academic-paper` | 论文白 + 衬线正文 + 黑墨 + 蓝链接。 | 学术报告、研究分享、会议论文 |
+| `japanese-minimal` | 象牙白 + 朱红 accent + 极大留白 + Noto Serif。 | 品牌升级、匠人故事、禅意叙事 |
+| `engineering-whiteprint` | 白底 + 坐标纸网格 + 海军墨线 + 等宽字。 | 系统设计、API 文档、架构白皮书 |
+
+### Bold & editorial
+
+| name | description | when to use |
+|---|---|---|
+| `magazine-bold` | 奶油底 + 超大 Playfair 衬线 + 橙色 spot。 | 专栏文章、封面故事、品牌月刊 |
+| `news-broadcast` | 白底 + 红色竖条 + Oswald 大写 + 硬阴影。 | 突发新闻、发布通稿、数据播报 |
+| `midcentury` | 奶油底 + 芥末/青/焦橙 + 锐利几何。 | 设计史、家居美学、复古品牌 |
+| `retro-tv` | 暖奶油 + CRT 扫描线 + 琥珀橙 accent。 | 怀旧叙事、八零九零年代主题 |
+
+### Effect-heavy / dramatic
+
+| name | description | when to use |
+|---|---|---|
+| `cyberpunk-neon` | 纯黑 + 霓虹粉青黄 + 发光 + JetBrains Mono。 | 黑客、地下文化、赛博 talk |
+| `vaporwave` | 深紫 + 粉红青蓝渐变 + 晕染光斑。 | 音乐、潮流艺术、A E S T H E T I C |
+| `y2k-chrome` | 银铬渐变 + 彩虹 accent + 大圆角 + Space Grotesk。 | 千禧怀旧、时尚品牌、Gen-Z |
+
+## How to apply
+
+```html
+<link rel="stylesheet" id="theme-link" href="../assets/themes/aurora.css">
+```
+
+Or enable `T`-cycling by listing themes on the body:
+
+```html
+<body data-themes="minimal-white,aurora,catppuccin-mocha" data-theme-base="../assets/themes/">
+```
+
+## How to extend
+
+Copy an existing theme, rename it, and override only the variables you want to
+change. Keep each theme under ~200 lines. Prefer adjusting tokens to adding
+new selectors.