SeaSlides HTML Slides Skill

Convert source material into a browser-ready HTML deck with synchronized SVG, PNG, and PPTX outputs.

Pipeline: Source -> Project -> Theme -> Strategist -> [Images] -> Executor -> Assemble -> Review -> Export

Hard Contract for Standard Slides

1. Run creation phases serially and complete each gate before continuing.
2. Ask at blocking decisions. In unattended mode, decide them and continue.
3. Convert document sources to Markdown before planning.
4. Preserve Template-Content Separation (TCS): shell in index-template.html, reusable styling in template.css, semantic slides in content.html.
5. Keep <style>, <script>, <link>, event handlers, and ad hoc visual styles out of standard-slide content.html.
6. Permit inline styles only for data values on the component/property allowlist defined in ${SKILL_DIR}/references/shared-standards.md; the validator enforces the same list.
7. Reassemble after every content, CSS, or template change. Treat root index.html, SVGs, both PNG routes, overview, and compiler receipts as one synchronized generation.
8. Pass the source gate before building, then pass the current-build visual gate before delivery. Build PPTX in that same build when it is requested.

The canonical standard-slide TCS rules live in ${SKILL_DIR}/references/shared-standards.md and ${SKILL_DIR}/scripts/validate_project.py.

Scenario Routing

Route special outputs before applying the standard-slide contract:

Intent	Read and follow
Academic or conference poster	${SKILL_DIR}/references/scenarios/poster.md
CV or resume	${SKILL_DIR}/references/scenarios/cv.md
Social cover, article header, or thumbnail	${SKILL_DIR}/references/scenarios/social-cover.md
Standard HTML presentation	Continue below

Each special scenario defines its own authoring and review contract. Do not apply the standard-slide TCS validator or standard slide-count/rhythm rules unless that scenario explicitly requests them.

Match the user's language. Keep the structural headings in content_design_spec.md stable while writing values in the user's language when appropriate.

For 25+ slide decks, use ${SKILL_DIR}/workflows/resume-execute.md to split planning and execution across sessions.

Standard-Slide Architecture

File	Responsibility
index-template.html	Browser shell, navigation, external libraries, {{CONTENT}} placeholder
template.css	Canvas metadata, theme tokens, layout and component classes
content.html	Semantic <section class="slide ..."> blocks and speaker notes

html_compiler.py --all atomically assembles root index.html and produces output/svgs/, output/pngs/, output/browser_pngs/, output/overview.png, output/slides.pdf, output/dom-audit.json, output/render-fidelity.json, and output/compile-manifest.json. Add --include-pptx when PowerPoint is required; it produces output/slides.pptx in the same build and receipt.

Resource Map

Load references only when entering the relevant phase.

Phase or need	Resource
Full creation workflow	${SKILL_DIR}/workflows/create-presentation.md
Theme selection	${SKILL_DIR}/workflows/select-theme.md
New theme creation	${SKILL_DIR}/workflows/create-template.md
Topic-only research	${SKILL_DIR}/workflows/topic-research.md
Chart calibration	${SKILL_DIR}/workflows/verify-charts.md
Visual review	${SKILL_DIR}/workflows/visual-review.md
Strategist role	${SKILL_DIR}/references/strategist.md
Standard HTML/TCS contract	${SKILL_DIR}/references/shared-standards.md
Executor fundamentals	${SKILL_DIR}/references/executors/base.md
General / consulting / MBB / academic style	${SKILL_DIR}/references/executors/<style>.md
Components and layouts	${SKILL_DIR}/references/components.md, ${SKILL_DIR}/references/layouts.md
Design heuristics	${SKILL_DIR}/references/design-guide.md
Image dispatch and layout	${SKILL_DIR}/references/image-base.md, ${SKILL_DIR}/references/image-layout-patterns.md
Review rubric and issue severity	${SKILL_DIR}/references/visual-review.md, ${SKILL_DIR}/references/checklist.md
Artifact and visual issue ownership	${SKILL_DIR}/references/artifact-ownership.md
Theme creation internals	${SKILL_DIR}/references/template-designer.md
Browser DOM export	${SKILL_DIR}/scripts/docs_html/browser_dom_export.md
Content plan template	${SKILL_DIR}/templates/content_design_spec_reference.md

Use ${SKILL_DIR}/templates/index.json as the only theme catalog. Do not maintain a second theme list in this entry file.

Workflow

Step 1: Process Sources

Gate: Source material or a topic is available.

If only a topic is provided, follow ${SKILL_DIR}/workflows/topic-research.md or create a source brief before continuing.

Input	Command
PDF	python3 ${SKILL_DIR}/scripts/source_to_md/pdf_to_md.py <file> --images filtered
DOCX / EPUB / HTML / LaTeX / RST	python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>
PPTX / PPSX	python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>
Excel	python3 ${SKILL_DIR}/scripts/source_to_md/excel_to_md.py <file>
Web page	python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <url>
Markdown / text	Read directly

Do not proceed with only an unread raw document when a converter is available.

Step 2: Initialize the Project

Gate: Readable source content exists.

python3 ${SKILL_DIR}/scripts/project_manager.py init <project_name>
python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --copy

Use --exact-name only when a deterministic, date-free directory name is needed (for example, a reproducible benchmark); normal projects retain the dated suffix.

Use --move only when explicitly requested. Copy extracted images into assets/ and import the converted Markdown.

Step 3: Select a Theme

Gate: Project directory exists.

Follow ${SKILL_DIR}/workflows/select-theme.md.

1. Read ${SKILL_DIR}/templates/index.json.
2. Use a user-named theme directly; otherwise rank themes by metadata such as tags, bestFor, style, audience, and content needs.
3. Present a concise recommendation and wait unless unattended mode is active.
4. Do not use a fixed default theme merely because the request is ambiguous; choose the best-supported candidate from the catalog.

Copy the selected theme files:

cp ${SKILL_DIR}/templates/<theme>/index-template.html <project_path>/
cp ${SKILL_DIR}/templates/<theme>/template.css <project_path>/

Read the selected theme's theme.md and demo.html. Use their actual CSS vocabulary and composition patterns; do not copy irrelevant sample content or decorative details mechanically. A demo may contain theme-authoring geometry: never copy a non-data inline style into standard-slide content.html; translate reusable treatment into template.css classes.

Step 4: Produce the Content Design Spec

Gate: Theme is selected and understood.

Read the Strategist and shared standards. Present the nine decisions as one bundle and wait unless unattended mode is active:

1. Page format
2. Page-count range
3. Target audience
4. Style objective
5. Color scheme
6. Typography plan
7. Image approach
8. Slide rhythm plan
9. Per-slide component/layout assignment

For standard slides, use canvas metadata in the first :root block of template.css:

:root {
  --slide-width: 1280px;
  --slide-height: 720px;
}

Use 960x720 for 4:3. Scenario documents own non-slide canvas formats.

If user images exist, run:

python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/assets

Write content_design_spec.md from ${SKILL_DIR}/templates/content_design_spec_reference.md, including project settings, a catalog theme ID, narrative, per-slide content/layout decisions, image decisions, colors, and typography. Record intentionally excluded assets.

Step 5: Acquire Images When Needed

Gate: The design spec requests generated or searched images.

Read ${SKILL_DIR}/references/image-base.md, then the relevant image workflow. Generate/search assets, verify files, and match image shape to the intended slot. Skip this phase when no new images are needed.

Step 6: Author content.html

Gate: Design spec, selected theme, and required assets are ready.

Read executor base, exactly one style executor, shared standards, template.css, the selected theme.md, and demo.html.

Author standard slides with these constraints:

• Use <section class="slide [mode] [modifier]" data-notes="..."> for every slide.
• Every slide must resolve to one valid mode: give it an explicit light, dark, hero light, or hero dark class; a selected theme's documented default mode in theme.md is also valid. Do not rely on an undocumented CSS fallback.
• Use only classes defined by the selected theme or required external libraries.
• Put reusable styling in template.css; use only canonical data-value inline styles from shared standards.
• Keep every slide visible in the settled export state without hover, timer, scroll, or active-carousel dependencies.
• Use action titles when they clarify the conclusion; allow short thematic titles for covers and dividers.
• Use relevant or user-required images and meaningful alt text. Do not insert unrelated assets merely to exhaust the folder.
• Keep TODOs, diagnostics, raw markup, component labels, and accidental source text out of rendered slides.
• Count all title, divider, hero, focus, and appendix slides within the requested range.
• Use \(LaTeX\) for inline MathJax formulas and \[LaTeX\] for display formulas.

Treat layout variety, component variety, dark/light alternation, and hero cadence as design heuristics. Use them when they improve hierarchy and pacing; allow deliberate repetition for comparisons, timelines, tutorials, and other content that benefits from a stable visual grammar.

Step 7: Assemble, Review, Validate, and Export

Gate: content.html, template.css, and index-template.html exist.

7.1 Source Gate

Before building, validate the project source and TCS contract only:

python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --source-only --profile standard-project

Fix source/TCS errors before compiling. This is a project-directory gate; do not use the legacy single-file invocation for standard-slide delivery.

7.2 Assemble and Render

python3 ${SKILL_DIR}/scripts/html_compiler.py <project_path> --all

Require root index.html, matching slide counts in output/svgs/, output/pngs/, and output/browser_pngs/, plus output/overview.png, output/dom-audit.json, output/render-fidelity.json, and output/compile-manifest.json. Rerun after every source change. Diagnose compilation failures and retry up to five times.

dom-audit.json is the browser-layout truth: it records settled-DOM blockers found before conversion plus theme-opted-in composition telemetry/review items. Those composition measurements support rather than replace visual judgment. render-fidelity.json records review-only differences between browser PNGs and SVG-route PNGs. compile-manifest.json is the current-source receipt: it fingerprints inputs, toolchain, assembled HTML, and published artifacts.

7.3 Perform Visual Review

Follow ${SKILL_DIR}/workflows/visual-review.md and ${SKILL_DIR}/references/visual-review.md.

1. Inspect output/overview.png, then every browser-rendered PNG at a projection-like scale; the overview routes attention but is not a substitute for page review.
2. Use matching output/pngs/ and render-fidelity.json only to diagnose conversion-route differences.
3. For every page, identify its vertical mode (centered cluster, top-to-bottom, split anchors, image hero, or intentional breathing). Fix content pages stranded at the top even when a footer makes the raw content span look full.
4. Fix blocking visual problems and pronounced composition/readability defects, re-run the source gate, rebuild with --all, and repeat up to three visual iterations.

Evaluate rhythm and diversity in context. Do not change a clear repeated layout solely to satisfy a numeric quota, and do not add filler merely to consume whitespace.

7.4 Final Visual Gate

python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --require-build --artifact-profile visual

This gate requires a current compile-manifest.json, all visual artifacts, and zero browser DOM-audit blockers. Fix hard errors such as stale/missing artifacts, TCS violations, missing files, broken classes/references, invalid structure, and DOM blockers. Treat render-fidelity and diversity/density findings as review prompts, not automatic failures.

7.5 Export PPTX

python3 ${SKILL_DIR}/scripts/html_compiler.py <project_path> --all --include-pptx
python3 ${SKILL_DIR}/scripts/validate_project.py <project_path> --require-build --artifact-profile delivery

When PPTX is requested, use this same-build delivery sequence instead of a later standalone --format pptx export. Deliver root index.html, visual artifacts, receipts, and output/slides.pptx.

Editing an Existing Deck

1. Read content.html, template.css, index-template.html, theme documentation, and current rendered output.
2. Edit semantic content in content.html; edit reusable presentation rules in template.css; preserve TCS.
3. Re-run the source gate, rebuild with --all, visually review affected pages, and pass the final visual gate. When PPTX is requested, rebuild with --all --include-pptx and pass the delivery profile.
4. Re-run planning only when the request changes the narrative, theme, or deck structure.

Dependencies

pip install -r ${SKILL_DIR}/requirements.txt
cd ${SKILL_DIR}/scripts/html_to_svg
npm install
npx playwright install chromium

Open root index.html for local preview, but use the compiler's synchronized outputs for final review.