# htmlslides Skill Complete guide for AI agents to create HTML presentations compatible with htmlslides.ai. > This document is the English public entry point served at `https://www.htmlslides.ai/skill?lang=en`. > The reusable skill folder also contains assets, references, and scripts under > `content/htmlslides-skill/`. --- ## 0. Workflow - Discuss First, Then Build Do not jump straight to writing HTML. First align with the user on the deck's topic, audience, length, design direction, source material, and hard constraints. If the user has already specified those points, make reasonable assumptions and build. Keep the conversation practical: ask at most 1-3 decisive questions at a time. Then create a single HTML file or a `.hslides` package and include playback handoff instructions in the delivery. ## 1. Required Reading For Agents Before building, use these folder resources when relevant: - `assets/starter.en.html` - safe starter deck with a player-safe `.slide-stage`. - `assets/starter.zh.html` - same pattern with Chinese copy and font fallback. - `references/viewport-safety.en.md` - required reading for any dense slide, card grid, table, diagram, footer, or screenshot-heavy slide. - `references/authoring-patterns.en.md` - reusable layout patterns and anti-patterns. - `references/packaging.en.md` - `.hslides` packaging, resource paths, and file-size rules. - `scripts/validate-htmlslides-deck.mjs` - deterministic viewport validator. Run it before delivery. ### template reference workflow When the user gives you an authorized online template reference URL such as `/api/templates/official/{id}/reference?token=...`, use that first. If the prompt also includes an authorized `.hslides` package URL such as `/api/templates/official/{id}/download?token=...`, download it as the template asset source: - Fetch the authorized reference URL directly. The response includes `htmlContent`, `styleContent`, `agentContract`, and public template metadata. - Read `agentContract` first when present. Treat `agentContract.slideMap` as the compact source-of-truth for source slide titles, page types, layouts, surfaces, transitions, and animation recipes. Treat `agentContract.templateRuleChecklist` as the template rule checklist you must satisfy before coding. - Download the authorized `.hslides` package URL when provided. Inspect root `index.html`, root `style.md`, and local assets such as `fonts/`, `images/`, `videos/`, or `audio/`. Use this package for concrete assets and local font files. - Read `htmlContent` as the visual and structural reference: slide rhythm, page-type skeleton, layout proportions, type hierarchy, component styling, animation language, and asset reference style. - Read `styleContent` as the template design contract, similar to a `design.md`: palette, typography, layout grammar, best-fit cases, avoid notes, component vocabulary, and spacing rhythm. - Before writing HTML, produce a compact intermediate plan: - `template analysis map`: list the source slide types, rhythm, layout grids, repeated components, and animation patterns. - `design contract`: extract the exact palette, type scale, spacing rules, component treatments, and responsive constraints you will preserve. - `deck outline`: map the user's topic to new slide titles and page types before coding. - Do not copy sample data-title labels, navigation words, or placeholder content from the template. Labels like `Home` must be replaced with unique, topic-specific slide titles; every slide's `data-title` must be meaningful and unique. - Keep main slide titles to 1-2 lines whenever possible; never exceed 3 lines. If a translated or CJK title wraps longer, rewrite it into a shorter title plus subtitle or widen the title region instead of preserving the template's narrow Latin title column. - For CJK or mixed Chinese headings, do not reuse Latin display rules blindly. Avoid `text-transform: uppercase` on headings that contain CJK text, and keep heading `line-height` at least `1.08` (often `1.12`-`1.25` reads better) unless the validator proves it works. - Deliver a .hslides package by default for template-based work and preserve the template font choices and asset model when possible: keep `@font-face` rules, copy required font files into `fonts/`, and reference local assets with relative paths. - Use the template as reference material, then create a new deck for the user's topic instead of only replacing sample text. - Fallback: if the authorized URLs are unavailable and the user provides a `.hslides` file, treat `.hslides` as a local ZIP archive with a renamed extension. Inspect root `index.html`, root `style.md`, and local `fonts/`, `images/`, `videos/`, or `audio/` references before generating the new deck. ## 2. HTML Format Specification An htmlslides presentation is a single HTML file, or a `.hslides` ZIP package, where each slide is a `
` element. Minimal shape: ```html My Presentation

My Presentation

``` Core rules: - One HTML file contains all slides. - Each `
` is one slide page. - Always add `data-title` for thumbnail navigation and speaker view. - The player owns deck-level playback: paging, keyboard, wheel/swipe, thumbnails, autoplay, speaker view, fullscreen, and low-power mode. - Each slide must fit the iframe's real viewport. Do not rely on vertical scrolling. ## 3. Player Motion Protocol Use declarative attributes when you want the website player to animate the deck: - `data-transition="slide|fade|none"` on `
`. - `data-animate="cascade|hero|quote|directional|pipeline"` on `
`. - Add `data-anim` to elements that should enter when the slide appears. - For quotes, use `data-anim="line"` on each line. - For directional comparison pages, use `data-anim="left"`, `data-anim="divider"`, and `data-anim="right"`. - For pipeline pages, use `data-animate="pipeline"` and `data-anim="step"` on each step. Do not write custom deck navigation JavaScript unless the HTML must also work standalone outside htmlslides. ## 4. CSS Best Practices - **Design for a 1920x1080 canvas (primary technique):** On landscape frames (desktop, fullscreen, preview modal) the player renders your deck at 1920x1080 and scales it to fit, so a deck that fits that canvas never clips there. Portrait frames are filled (reflow with `@media (max-aspect-ratio: 1/1)`), and standalone/embedded viewing gets no scaling — so still make the deck responsive. The robust way to cover all three: a frame-proportional root unit so every rem-based size scales with the frame — `:root { font-size: clamp(5px, min(0.833vw, 1.481vh), 16px); }` (keep structural sizes in vh/vw). See `references/viewport-safety.en.md`. - **Safe stage first:** Let `section.slide` only fill the real player viewport. Put actual content in `.slide-stage` or an equivalent container and use it to manage top, side, and bottom spacing. The htmlslides player places controls outside the iframe and can compress iframe height. The deck should not reserve a second full control-bar height. - **Adaptive slides:** Use `width: 100%; height: 100dvh;`, but never assume the viewport is 16:9. A standalone file, embed, modal preview, and fullscreen player may all receive different shapes. - **Overflow:** Use `overflow: hidden` by default so every slide remains a PPT-like canvas. If a slide cannot fit, reflow, reduce content, tune type, or split it into more slides. - **Height budget:** Reserve a height budget for top chrome, bottom foot, and the main content before styling. The main content must stop above the foot. Avoid large vh margins, large `min-height` blocks, or `overflow: visible` as a way to let content spill naturally. - **Breakpoint principle:** Do not rely on `max-width` alone. A short-but-wide player such as `min-aspect-ratio: 4 / 3` plus `max-height` should compress type, line height, gaps, padding, and card heights while preserving the horizontal structure. A narrow or portrait viewport should reflow to one column. - **Dense slides:** Flow diagrams, tables, code, card grids, and feature/icon grids need their own compact responsive rules. Use `clamp()` to cap heading, body, icon, gap, padding, and card height. If the slide still does not fit, split it into more slides. - **Effective player viewport:** Design against the iframe's real viewport, not the physical device screen. Modal previews and embeds can be much shorter than 16:9. ## 5. Deterministic Validation - Required Before Delivery Run the validator before telling the user the deck is ready: ```bash node content/htmlslides-skill/scripts/validate-htmlslides-deck.mjs path/to/index.html ``` The validator checks multiple player viewports, including `1070x523` compact-modal, and reports the slide index, viewport, element selector, and overflow amount. Any failure means the deck is not done. Fix by reducing copy, tightening type/line-height/gaps, reducing card or chart height, changing the layout, or splitting the slide. ## 6. Packaging For local assets, package as `.hslides`: ```text my-deck.hslides/ index.html images/ videos/ audio/ ``` Use relative paths from `index.html`, for example ``. Keep packages under 50MB. ## 7. Delivery Checklist - The deck uses one coherent visual system. - Every slide has `data-title`. - Slides do not require vertical scrolling. - Dense slides have compact-height media queries. - Footers remain visible and are not overlapped. - The deterministic viewport validator passes. - The final response explains playback options: upload it to htmlslides as an HTML or .hslides file, or store the HTML or .hslides file in the user's own GitHub repository and open that GitHub file URL through htmlslides.