slides

slides — End-to-end slide creation tool

An integrated slide creation tool from topic research to final delivery: topic research → style selection → AI-generated HTML → conversion to editable PPTX / PDF. Supports extracting reusable design styles from existing slides and building a personal style library.

Core capabilities

Topic research: Input a topic and audience to automatically produce a structured research report (research.md) and a page-by-page outline (slides_outline.json）
Editable PPTX: Text is preserved as editable text boxes (not screenshots), with position, font size, and color precisely reproduced
Hybrid dynamic backgrounds: HTML retains WebGL / ASCII / canvas animations; when exporting to PPTX, only the background layer is frozen, while foreground text, cards, lines, and images continue to be rebuilt item by item as native objects
High-fidelity PDF: Rendered based on Chromium, with browser rendering as the foundation, and checked page by page before delivery
Style extraction: Extract style parameters such as color schemes, fonts, and layouts from existing HTML slides, and save them as reusable JSON style files
Style library: Includes 38 preset styles (legal black gold, minimalist editorial white, consulting blue, in-depth report, objective grid, etc.), and supports users in extracting and extending their own
Design system: Built-in CSS design language (typography scale, spacing system, component patterns, visual hierarchy rules), with 12 complete HTML template files that can be cloned directly with content replaced
Pre-validation: Before conversion, use Playwright to check slide containers, dimensions, overflow, gradients/inset shadows, bare div text, remote/base64 images, text backgrounds/borders, and other risks
Compatible with any HTML: Automatically handles viewport-relative units (100vh, clamp(), vw), flexbox, and grid layouts
Animation system: Browser mode supports entrance animations (fadeSlideUp/Left/Right/Scale), delay cascades (d1-d6), and page transition strategies (cascade/hero/quote/directional); automatically degrades when exporting to PPTX
Multi-page detection: Automatically identifies .slide / section containers, enabling one-click conversion of multiple pages in a single file
Universally distributable: Contains no built-in personal information; speaker identity, contact details, avatar, and QR code come from local configuration, and when not configured, anonymous defaults are generated, ready to use out of the box
Local conversion: The conversion engine does not require a cloud API; remote fonts, images, or scripts in the HTML may still access the network, so when handling private materials, use local resources and verify the input source.

Input/Output

Input

HTML slide file(required): An HTML file containing .slide or section containers
Output format(optional):--format pptx|pdf|both; explicit parameters take precedence; otherwise, the format is selected based on the output file's .pptx / .pdf suffix, and when there is no recognizable suffix, PPTX is the default.
Layout ratio(optional):--layout 16:9|4:3, default 16:9
Style parameters(optional):--extract-style extract style,--save 名称 save to style library

Output

PPTX file: editable PowerPoint (text preserved as text boxes)
PDF file: high-fidelity PDF rendered via Chromium
Style JSON：--extract-style : outputs structured style parameters

Technical architecture

HTML 文件 → Playwright 渲染（固定视口）
    → 动态背景层单独冻结为静态 PNG
    → getBoundingClientRect() / getComputedStyle() 提取前景位置与样式
    → Codex Presentations Runtime：Artifact Tool 逐项重建 + finalizer
    → 本地 CLI 回退：PptxGenJS 逐项重建
    → PDF：Chromium 高保真渲染

风格提取 → 遍历 DOM 元素收集配色/字体/布局
    → 聚类去重 → 结构化 JSON → 风格库

Local configuration (optional)

SkillsShip with no personal information built in. When no configuration is present, generate with anonymous defaults—the deck contains only this session's content, with no speaker name, contact information, avatar, QR code, or blank introduction page.

When personalization is needed, use local configuration to provide speaker identity, contact information, branding, and display toggles:

# 引导模式：打印需要收集的字段清单（Agent 逐项询问后回填）
node scripts/init-profile.js

# 非交互写入（默认 ~/.config/slides/profile.local.json）
node scripts/init-profile.js --name "张三" --title 律师 --organization "某某律师事务所" \
  --wechat-qr ~/assets/wx.png --show-wechat-qr --style 商务权威

# 校验（只报字段是否已填与路径状态，不打印资料值）
node scripts/check-profile.js

Configuration is storedoutside the skill directory, so skill upgrades/reinstalls do not overwrite it. Each run loads only one configuration, resolved in this order:--config / SLIDES_PROFILE → deck project .slides/profile.json → skill directory config/profile.local.json → ~/.config/slides/profile.local.json → anonymous default. Relative paths are resolved relative to the directory containing the selected configuration file; an explicit path error or corrupted JSON results in an immediate error, with no fallback to someone else's information.

General convention for separating public and private:Git-tracked = publishable general content; ignored by .gitignore = private to the user（config/profile.local.json、config/local/、assets/local/ , etc.). Original copies of one's own old materials are placed in config/local/(recovery source, not read at runtime).

When generating HTMLread the same configuration:

node scripts/load-profile.js --json       # 完整配置（供生成流程消费）
node scripts/load-profile.js --footer     # 仅页脚文本
node scripts/load-profile.js --assets     # 已启用素材的解析路径

If an identity field is left blank, that element is omitted and not fabricated. The introduction page is determined by presentation.intro_pages , and the closing format is determined by presentation.closing_mode .
show_profile / show_footprints / show_wechat_qr / show_public_account_qr When disabled,do not readthe corresponding image and source file, and leave no placeholder box on the page.
A QR code is a commitment to explicitly display: if enabled but the image is missing, treat it as a validation error; do not substitute an old code or a fake code.
Private assets such as avatars / QR codes / fonts are referenced directly by configuration path during local authoring;decks sent to others must be packaged separately(copy into the deck resource directory, change to relative references, and verify it opens after moving).
During conversion, exported metadata (PPTX author) and the personal style save directory both read the same configuration; when no identity is configured, fall back to the tool name and personal style directory.

For field definitions and migration notes, see local configuration; for a blank template, see config/profile.example.json。

complete creation workflow

① 需求澄清      ② 研究/大纲      ③ 风格+版式       ④ 生成 HTML       ⑤ 预检       ⑥ 转换+QA
受众/场景/格式 → research.md → 风格库/版式家族 → 本地 HTML 文件 → validate → PPTX/PDF
页数/证据密度     outline.json    templates/playbook    固定视口/语义标签   strict     打开复核

Standard process：

Requirements clarification: first read the local configuration (node scripts/load-profile.js) to determine speaker identity, footer, and display toggles; if not configured, generate anonymously and do not fill in any personal information. Then confirm audience, scenario, page count, delivery format (PPTX/PDF/both), whether subsequent editing is needed, evidence density, and visual tone; mark missing information as "to be supplemented".
Research and outline: when the user only has a topic, first produce research.md + slides_outline.json(refer to references/research/); when the user already has a manuscript, first break it down into per-page objectives.
Style and layout selection: the default style takes the configured brand.style(if not configured, it is determined by the scenario); select a preset from the style library or extract the style of an old deck; then based on references/layout-theme-playbook.md select a layout family, using references/templates/ full HTML template files (12 page types, sharing the _base.css design system).
Generate HTML：clone references/templates/ corresponding template files, replace placeholder content, and switch the :root theme variables. Follow the _base.css design system: semantic tags, local images, fixed viewport. Dynamic backgrounds are uniformly marked with data-ppt-background, and speaker notes are written in the slide's data-note or [data-speaker-notes] .
Pre-check validation: run cd scripts && npm run validate -- ../example.html --strict; for the final file, replace with the target HTML path. Fix errors first, then handle warnings.
Conversion output: run node convert.js 新内容.html -o 输出 --format both --background-mode auto, or output PPTX/PDF as needed. If the Codex environment provides a Presentations Runtime, prefer to rebuild with the Artifact Tool per references/native-pptx-rebuild.md and pass the finalizer; for the local CLI, use the built-in PptxGenJS converter.
Final QA: review in three places—browser preview, PPTX opening, and PDF opening: page size, text clipping, missing images, whether PDF text is selectable, whether PPTX foreground elements are individually editable, whether dynamic backgrounds are statically preserved in the PPTX, and whether speaker notes are written.

Common references：

Layouts and themes:references/layout-theme-playbook.md
Full HTML templates:references/templates/(12 page types + _base.css design system + README.md index)
PPTX/PDF stability:references/pptx-guide.md
Hybrid native rebuild:references/native-pptx-rebuild.md
Style reference:references/style-reference.md
Local configuration (identity/assets/preferences/initialization/migration):references/configuration.md
Chinese courseware typography and redundancy removal:references/cn-deck-polish.md(§1–23: no italics / minimal header and footer / remove redundancy on cover and section pages / remove source citations / photo aspect ratios / inline colors to prevent invisibility / counter synchronization / split introduction pages per configuration / closing form per configuration / signature background visibility / light-dark pairing / page-turn navigation interaction / assets under two strategies: local creation and external delivery / §14 three-layer viewport overflow pitfalls / §15–19 process overview step-by-step / parallel card density / precise Skill naming / unified proper nouns / cross-page font size consistency / §20–22 component reuse: read CSS first / 720p budget and DOM geometry verification / full page number renumbering (two counters grouped by page with the same number) + typography baseline appendix / §23 vertical engine backing and slide same family)—review before generating and auditing a Chinese deck

Topic research module

When the user only has a topic idea and no usable script or slide outline yet, use the built-in research framework:

Inputs：

topic: research topic
audience: audience (legal team/corporate legal/public sharing, etc.)
target_pages: target page count (8-12 recommended)
tone: presentation style (professional and rigorous/forward-looking and innovative/training-oriented, etc.)

Outputs：

research.md: structured research report (including core conclusions, evidence, risks and boundaries)
slides_outline.json: page-by-page outline (each page includes title, summary, layout type, key points, speaker notes)

Research resources：

Research framework:references/research/research_framework.md
Report template:references/research/research_report_template.md
Outline Schema:references/research/slides_outline.schema.json

Writing principles：

Facts before opinions: give evidence first, then conclusions
Actionable conclusions: at least 1 actionable recommendation per page
Explainable terminology: add a one-sentence definition when a key term first appears

Usage

Command line

All three delivery paths are retained: PPTX for later editing, PDF for reading and distribution,both generate both at the same time.--format Takes precedence over the filename extension; when no format is specified and the output has no recognizable extension, it still defaults to PPTX. Multi-file/directory input currently only supports merging into PPTX; PDF or dual format requires first organizing the content into a single multi-page HTML to avoid silently omitting subsequent files.

# 安装依赖（首次）
cd scripts && npm install
npx playwright install chromium

# ── 文件转换 ──
# 单文件 → PPTX
node convert.js slides.html -o output.pptx --background-mode auto

# 单文件 → PDF
node convert.js slides.html -o output.pdf --format pdf

# 单文件 → PPTX + PDF
node convert.js slides.html -o output --format both

# 目录批量转换
node convert.js ./slides-dir/ -o presentation.pptx

# 4:3 布局
node convert.js slides.html -o output.pptx --layout 4:3

# ── 风格提取 ──
# 从 HTML 提取风格，输出 JSON
node convert.js slides.html --extract-style -o style.json

# 提取并保存到风格库
node convert.js slides.html --extract-style --save 商务法律风

# 列出风格库中所有可用风格
node convert.js --list-styles

# ── 转换前预检 ──
# 宽松模式：输出错误/警告但不中断
npm run validate -- ../example.html

# 严格模式：存在错误时退出非零
npm run validate -- ../example.html --strict

# 指定 4:3 视口
npm run validate -- ../example.html --viewport 1000x750 --strict

html2pdf.js fidelity option table (v1.5.11+)

html2pdf On top of preserving v1.5.10's default behavior, the following optional parameters are added. All optionsare off by default, fully equivalent to v1.5.10; enable them as needed to improve fidelity.

Option	Value	Effect	Default
`textRendering`	`geometricPrecision` / `optimizeLegibility` / `auto`	Reduce the probability of CJK glyphs being rasterized as Type3 on macOS	`auto`
`backgroundStrategy`	`as-is` / `freeze` / `hide`	Dynamic background handling:`freeze` snapshot the canvas's current frame into a static image (preserves texture, still a raster background);`hide` hide completely (cleanest vector text);`as-is` leave untouched	`as-is`
`preferExactSize`	`true` / `false`	Use integer pixel dimensions instead of mm floating-point conversion (eliminates `960.96×540.96` drift)	`false`
`outline`	`true` / `false`	PDF outline/bookmark, extracted from `[data-pdf-outline]` / `<header>` / `.kicker` Extract	`false`
`tagged`	`true` / `false`	Output tagged PDF (accessibility screen reading)	`false`
`marginMode`	`none` / `compact` / `normal` / `wide`	Single-page PDF margin preset; multi-page deck default remains `none`	`none`
`margin`	`{top,right,bottom,left}`	Explicitly override `marginMode`(accepts numeric strings or mm units)	—

Typical usage：

// 单页 HTML 报告：紧凑边距
await html2pdf('report.html', 'report.pdf', { marginMode: 'compact' });

// 多页 deck：保留动态背景纹理
await html2pdf('deck.html', 'deck.pdf', { backgroundStrategy: 'freeze' });

// 跨设备归档：尺寸精确 + 可访问性标签
await html2pdf('deck.html', 'deck.pdf', { preferExactSize: true, tagged: true });

Regression guarantee: v1.5.11 has passed 7 unit tests (scripts/tests/test-html2pdf-fidelity.mjs), covering the default path and all new option combinations; default invocation output is binary-compatible with v1.5.10.

scripts/ contains 3 different conversion entry points, suited to different scenarios:

HTML type	Detection feature	Script to use	Output
Vertical paginated deck(default case)	`.slide` containervertically stacked(no `#deck` container)	`convert.js` or `html2pdf.js`	Multi-page PDF (text selectable)
Horizontal paging carousel ⚠️	`#deck { position:fixed; width:10000vw; transform:translateX }` mode (reveal.js / custom carousel)	`html2pdf.js`(≥v1.5.2, text-layer PDF) ⭐;`html2pdf-carousel-hd.js` falls back to (image-based)	Multi-page PDF (text selectable）
Vertical scroll-snap + WebGL signature ⚠️	`body{scroll-snap-type:y}` + `.slide{width:100vw;height:100vh}` + `position:fixed` WebGL/canvas dynamic background (scroll-snap courseware form)	`html2pdf-scrollsnap-hd.js` ⭐	Multi-page PDF (image-based, rasterized per browser view)
Single-page HTML	Only 1 `.slide` or no `.slide` container	`convert.js` or `html2pdf.js`	Single-page PDF

⚠️ Script selection for horizontal paging carousel (revised 2026-09-07)

Revision (html2pdf.js v1.5.2 / v1.5.3): The real root cause of the single-page/incomplete rendering even after the v1.5.1 patch was that html,body { height:100%; overflow:hidden } re-cropped the staticized content into one page—v1.5.2 has lifted this; v1.5.3 adds the body.exporting export-state convention (courseware can hide the presentation HUD).Since v1.5.2, horizontal paging carousel by default uses html2pdf.js: 37-page carousel deck verified to paginate correctly, with selectable and searchable text layers(case: multi-page presentation courseware regression sample). carousel-hd is downgraded to a fallback (image-based) for when the print path fails. Prerequisites: conversion waiting must satisfy document.fonts.ready(built into html2pdf.js); the courseware should provide the body.exporting hidden rule.

Historical lesson (v1.5.1 era, retained for reference) — why we fell back to the screenshot method at the time:

convert.js detected .slide container count (appeared to be 38 slides) but @page size + page-break-after under the position:fixed; width:10000vw containerdoes not take effect
Result:detectCount: 38, but the PDF actually outputs only 1 page (the other 37 slides were pushed out of the viewport by the #deck horizontal transform)
html2pdf.js v1.5.1 already had the #deck static patch, butsingle-page rendering — animation completeness depends on waitForTimeout(100), often causing fonts not loaded / data-anim elements with opacity=0 / WebGL canvas not drawn

Correct approach for the carousel-hd script（scripts/html2pdf-carousel-hd.js）：

Fix the viewport to 1280×720(slide natural size)
deviceScaleFactor=2 → each PNG 2560×1440 (HD)
await page.evaluate(() => document.fonts.ready) — wait for web fonts to finish loading
For each .slide：
- inject __revealForCapture() → cancel all web animations + force data-anim elements opacity: 1
- await page.waitForTimeout(900) — wait for the CSS transition .9s animation to complete
page.screenshot({ clip }) capture a single slide
ImageMagick convert *.png output.pdf merge into a multi-page PDF

Usage：

cd scripts
node html2pdf-carousel-hd.js <input.html> <output.pdf>
# 输出示例：carousel-hd: 检测到 38 张幻灯片 @ 1280×720 ×2DPR
#          carousel-hd: 合并 38 张 PNG → PDF (ImageMagick)

Visual verification script：

# 转完用 PyMuPDF 抽 3 张看
python3 -c "
import fitz
doc = fitz.open('output.pdf')
for i in [0, 1, 9, 19, 37]:
    pix = doc[i].get_pixmap(matrix=fitz.Matrix(0.4, 0.4))
    pix.save(f'page_{i+1}.png')
"
# 找最大 PNG（封面 / 结语通常内容最满）—— 几张图加起来应 < 5 MB

Known trade-offs：

✅ Rasterized as rendered in the browser (including web fonts, WebGL filters, data-anim elements)
❌ PDF text is images —pdftotext / PyMuPDF get_text() cannot extract text
❌ Cannot search / copy
❌ Large files (38-slide carousel PDF ≈ 6 MB; vs text-based PDF 38 pages ≈ 0.4 MB)

If selectable text is required：

Modify the HTML so that .slide toggles hidden / shown in the carousel state (do not use transform translateX, use display:none toggling) → then convert.js / html2pdf.js is usable

⚠️ Vertical scroll-snap + WebGL signage background: use the scrollsnap-hd script

Common form of scroll-snap + WebGL signage courseware:body{scroll-snap-type:y proximity} + .slide{width:100vw;height:100vh} + position:fixed WebGL dual canvas (bg-dark/bg-light) + IntersectionObserver switching by slide body.light-bg（Clone note: synced body classes must have matching CSS consumers; when slides have a semi-transparent background, each page's backing must be from the same family as the slide — see cn-deck-polish.md §23）+ data-anim entrance animation + low-power degradation.@page+page-break does not take effect on position:fixed canvas,convert.js/html2pdf.js will lose the background or output only 1 page.

scripts/html2pdf-scrollsnap-hd.js 's approach：channel=chrome + --use-gl=swiftshader make headless actually render WebGL;emulateMedia reducedMotion:'no-preference' prevent low-power degradation; inject CSS to hide #nav/#hint/#overview, disable scroll-snap; slide by slide scrollIntoView({behavior:'instant'}) + force [data-anim] opacity:1 + wait for IntersectionObserver and multiple RAF frames; screenshot the viewport (1280×720×2DPR); merge with magick.

cd scripts
# 若 HTML 含 Google Fonts 外链（思源宋体等），先造去字体副本避免 goto 超时
grep -vE "fonts\.(googleapis|gstatic)\.com" 原.html > /tmp/副本.html
node html2pdf-scrollsnap-hd.js /tmp/副本.html 输出.pdf
# 输出示例：scrollsnap-hd: 检测到 45 张幻灯片 @ 1280×720 ×2DPR
#           scrollsnap-hd: 合并 45 张 PNG → PDF (ImageMagick)

Trade-off same as carousel-hd: rasterized from browser frames (including WebGL signage, light/dark background switching, ASCII cover layer, data-anim entrance), but PDF text is images, not selectable/searchable, and files are large (45 pages ≈ 20 MB).

Built-in style library

38 preset styles are located in the references/styles/ directory and can be referenced directly when AI generates new HTML. Categorized by scenario:

Legal/Government

Style	Applicable scenario	Primary color scheme
Legal Black Gold	Legal lectures, training courseware	Black background + gold
Minimal Editorial White	Training, lectures, professional sharing	White background + emerald green
Government Red	Government reports, Party building courseware	Red tones
Policy Document	Policy interpretation, industry standards	Dark blue and red two-color

Business/Finance

Style	Applicable scenario	Primary color scheme
Business Authority	Annual reports, financial analysis	Dark blue + red
Business Gold	Corporate reports, business presentations	Gold tones
Consulting Blue	Strategic analysis, management reports	Professional dark blue
Finance Dark Gray	Investment analysis, fund roadshows	Dark gray + gold
Investment Banking Black	IPO roadshows, trading demonstrations	Pure black + red and blue
Insurance Blue White	Insurance products, risk control reports	Dark blue on white background

Technology/Creative

Style	Applicable scenario	Primary color scheme
Tech Dark Night	Tech launches, AI products	Black and blue + gold glow
Tech Blue	Tech sharing, product launches	Blue tones
Cyberpunk	Tech creativity, game launches	Neon pink, cyan, purple
Frosted Glass	SaaS products, UI showcases	Translucent purple and blue
Nordic Aurora	High-end consumer goods, brand positioning	Ice blue + aurora colors
Startup Pitch	Financing BP, growth reports	Purple and cyan contrasting colors

Editorial/Grid

Style	Applicable scenario	Primary color scheme
In-depth Reporting	In-depth long-form articles, industry observation, character interviews	Warm bone white + ink black + brick red
Objective Grid	Data reporting, architecture explanations, methodology walkthroughs	Pure white + graphite black + true red

Education/Academic

Style	Applicable scenario	Primary color scheme
Educational Charts	Statistical reports, data analysis	Multicolor charts
Education green	Education and training, knowledge sharing	Green tones
Education chalk	Classroom teaching, knowledge popularization	Dark green background + chalk white
Academic deep blue	Thesis defense, academic conferences	Navy blue + warm white

Industry/Scenario

Style	Applicable scenarios	Primary color scheme
Platinum white-gold	Fintech, corporate websites	White background + blue and gold
Vibrant tech	Startup pitch, youth education	Deep blue + orange
Academic retro	Academic lectures, historical reviews	Deep red + deep blue
Natural forest	ESG reports, environmental themes	Green tones
Paper and ink	Cultural lectures, calligraphy themes	Off-white + ink
Dark botanicals	Ecological themes, high-end showcases	Dark tones + greenery
Swiss modern	Design sharing, brand showcases	Red, black, and white
Bold signal	Creative presentations, brand launches	High-contrast clashing colors
Electric studio	Creative workshops, new media	Neon + dark tones
Minimalist Japanese	Brand philosophy, lifestyle	Large white space + ink
Engineering blueprint	Engineering specifications, system architecture	Blueprint blue + white lines
Medical mint	Medical reports, health popularization	Mint green + white background
Real estate gold	Property launches, real estate reports	Dark green, black, and gold
FMCG vitality	Product launches, FMCG marketing	Bright multicolor
Dining warm orange	Food and beverage brands, menu displays	Warm orange + cream white
Wedding champagne	Wedding planning, event proposals	Champagne gold + soft pink

You can also extract a custom style from existing HTML:node convert.js 课件.html --extract-style --save 风格名

Supported HTML features

Feature	PPTX	PDF
Text (p, h1-h6)	Editable text boxes	Native text
Images (img)	Native images	Native images
Lists (ul, ol)	Native bullet points	Native lists
Background color	Shape fill	CSS background
Background image	Image background	CSS background
Borders, rounded corners	Native shapes	CSS rendering
Shadows	PPTX shadows	CSS rendering
Flexbox / Grid	Computed positioning	Native rendering
100vh / clamp()	Force viewport then extract	Native rendering
CSS gradients	Must be preprocessed into images; the preflight check will warn	Native rendering, but may trigger text rasterization
Entrance animations	Not supported (automatically downgraded to static)	data-anim triggers fade-in/slide-in/scale
Page transitions	Not supported	data-animate specifies cascade/hero/quote/directional
WebGL / ASCII / canvas dynamic backgrounds	Frozen as a static background image; the foreground remains editable	Preserve dynamic effects or render statically at the PDF point in time
Speaker notes (data-note / data-speaker-notes)	Written into PowerPoint notes	The browser notes panel is implemented in HTML

Directory structure

slides/
├── SKILL.md                 # 本文件
├── CHANGELOG.md
├── DECISIONS.md
├── TASKS.md
├── .gitignore               # 本地配置与私有素材不入库
├── example.html             # 示例幻灯片（可直接转换测试）
├── assets/                  # 常规素材目录（头像/二维码/照片；图片默认 gitignored，README 说明规则）
├── config/
│   ├── profile.schema.json  # 本地配置字段与默认值
│   ├── profile.example.json # 可复制的空白配置
│   ├── *.local.json / *.local.md # 私有配置与偏好（gitignored，不入库不发布）
│   └── local/               # 旧版个人资料原件（恢复来源，gitignored）
├── references/
│   ├── configuration.md     # 本地配置：解析顺序、字段、初始化、迁移、发布边界
│   ├── pptx-guide.md        # PPTX/PDF 转换规则（五条铁律 + 元素支持矩阵）
│   ├── native-pptx-rebuild.md # 动态背景冻结 + 前景原生对象重建工作流
│   ├── layout-theme-playbook.md # 版式家族、主题字段、反泛化设计规则
│   ├── browser-guide.md     # 浏览器演示模式（视口适配 + 动画 + scroll-snap）
│   ├── style-reference.md   # 风格参考（AI 生成时引用）+ 设计哲学 + 反 AI-slop
│   ├── cn-deck-polish.md    # 中文课件去冗余与隐形坑
│   ├── templates/           # 完整 HTML 模板库（可直接 clone 替换内容）
│   │   ├── _base.css        # 共享设计系统（排版刻度、间距、组件、动画）
│   │   ├── README.md        # 模板索引 + 页面节奏建议
│   │   ├── 01-cover.html    # 封面页（dark）
│   │   ├── 02-content-list.html # 标题+要点列表（light）
│   │   ├── 03-data-grid.html    # 大数据/KPI 看板（dark）
│   │   ├── 04-quote.html        # 金句/引用页（dark）
│   │   ├── 05-timeline.html     # 横向时间线（light）
│   │   ├── 06-two-column.html   # 左右对比（light）
│   │   ├── 07-section-divider.html # 章节分隔（dark）
│   │   ├── 08-case-evidence.html   # 案例/证据卡片（light）
│   │   ├── 09-process-flow.html    # 流程步骤（light）
│   │   ├── 10-risk-matrix.html     # 风险矩阵（light）
│   │   ├── 11-training.html        # 培训讲义（light）
│   │   └── 12-image-text.html      # 图文混排（light）
│   ├── templates.md         # [旧版] 文字描述模板（保留兼容）
│   ├── styles/              # 风格库（38 个内置预设 + 使用者私有风格另存于配置目录）
│   │   ├── README.md
│   │   └── *.json           # 内置风格定义（JSON）
│   └── research/            # 主题研究模块
│       ├── research_framework.md     # 研究框架（六段式结构）
│       ├── research_report_template.md # 研究报告模板
│       └── slides_outline.schema.json # 分页大纲 JSON Schema
└── scripts/
    ├── html2pptx.js         # PPTX 转换核心引擎
    ├── html2pdf.js          # PDF 转换模块
    ├── extract-style.js     # 风格提取模块（保存到个人风格目录）
    ├── validate-slides.js   # HTML 转换前预检脚本
    ├── convert.js           # CLI 入口（读本地配置决定导出元数据）
    ├── load-profile.js      # 配置解析（生成/导出共用；也可作 CLI 查询）
    ├── init-profile.js      # 配置初始化（引导模式 + 非交互回填）
    ├── check-profile.js     # 配置校验
    └── package.json

Known limitations (PPTX mode)

CSS gradients → must be pre-rasterized into PNG images
Text elements must not have backgrounds/borders → use <div> for wrapping
Bare text in div → must be wrapped with tags such as <p> wrapped by tags such as
Inline element margin → not supported by PowerPoint
inset shadows → will corrupt the PPTX file
Remote/base64 images → unstable in PPTX; uniformly change to local images
Page overflow → the browser can scroll but PPTX will clip; must be fixed via preflight
Dynamic backgrounds do not become PowerPoint animations → auto / freeze mode only freezes background frames; foreground objects remain natively editable

PDF mode is more tolerant of CSS and is recommended when editing is not needed; however, if text must be selectable and searchable, you still need to avoid overlaying gradients, filters, or large semi-transparent layers on body text areas.

Pre-conversion validation script

scripts/validate-slides.js uses Playwright to render HTML locally and check for common conversion risks:

Whether a .slide / section container exists
Whether the slide size is close to a fixed viewport
Whether body/slide/child elements overflow
Whether gradients,box-shadow: inset, remote images, or base64 images are used
Whether there is bare div text
Whether text elements directly carry backgrounds or borders

First installation and run:

cd scripts
npm install
npx playwright install chromium
npm run validate -- ../example.html --strict

Dependencies

Node.js >= 18
Playwright (Chromium, first run npx playwright install chromium）
npm dependency installation:cd scripts && npm install
Preflight script:cd scripts && npm run validate -- ../example.html --strict
System fonts (for Chinese, it is recommended to use legally installed Microsoft YaHei, PingFang SC, or Noto Sans CJK)
The optional high-definition screenshot PDF path additionally requires Google Chrome and ImageMagick 7 (magick); the regular PPTX/PDF path only requires Playwright Chromium.