NianToB/resources/skills/local/html-slides/SKILL.md

name, description

name	description
html-slides	Use to create, convert, or improve browser-based HTML slide decks and presentation pages. Best for pitch decks, product introductions, research reports, teaching decks, internal reviews, and PPT/PPTX-to-HTML conversion. Produces a local deck folder with index.html using bundled templates, viewport-safe layout rules, and optional design briefs from the design skill.

html-slides

Create polished HTML slide decks that open in a browser. This is an execution skill: it turns content and a design direction into a working deck folder whose main file is index.html.

Use design first when the user asks for visual direction, brand strategy, product design, or a design review. Use this skill when the user needs the actual HTML deck built or an existing deck converted/improved.

Zhinian Runtime Policy

• Use the project/app-bundled browser runtime for optional preview checks.
• Never run npx playwright install chromium, playwright install chromium, or npm install -g playwright inside a user task.
• If browser preview is unavailable, validate the deck by static file checks and report that browser preview was skipped. Do not block deck delivery on a task-time Chromium download.

What This Skill Produces

• A local folder for each deck.
• index.html as the main entrypoint.
• Any required sibling assets or runtime files copied next to the deck.
• Browser-ready navigation and responsive slide layout.

Do not make a generic landing page unless the user explicitly asks for that. First version scope is HTML presentations, not general website generation.

References

Use these bundled references only as needed:

Reference	Purpose
references/beautiful-html-templates/index.json	Template catalog with mood, tone, formality, density, scheme, and best-fit fields
references/beautiful-html-templates/templates/<slug>/	Template HTML, metadata, and optional runtime/css files
references/beautiful-html-templates/runtime/	Shared deck runtime files
references/frontend-slides/viewport-base.css	Mandatory viewport-fitting CSS for from-scratch decks
references/frontend-slides/animation-patterns.md	Motion patterns matched to audience feeling
references/frontend-slides/scripts/extract-pptx.py	PPTX text/image extraction helper

Template screenshots are intentionally not bundled. Generate title-slide previews from the templates when the user needs to choose visually.

Mode Detection

Choose one mode:

Mode	Trigger	Output path
New deck from content	User gives topic, notes, outline, or full content	Template deck or from-scratch deck
PPTX conversion	User provides .pptx or asks to convert PowerPoint	Extract content, then build an HTML deck
Existing HTML enhancement	User provides an existing HTML deck	Preserve its design system or migrate to one chosen template
Template-based production	User asks for a polished pitch/report deck	Use beautiful-html-templates by default

Template-Based Workflow

Use this path by default for business decks, pitch decks, product introductions, research reports, and internal reviews.

1. Read references/beautiful-html-templates/index.json.
2. Match the brief by mood, tone, formality, density, scheme, best_for, and avoid_for.
3. Pick three candidates unless the user already chose a template or asked for fast execution.
4. Make the candidates genuinely different: one strong match, one safer professional option, one tasteful wildcard.
5. Read only the shortlisted template folders.
6. If the user needs to choose, generate three title-slide previews with their real title/subtitle and ask which direction feels right.
7. Copy the chosen template folder into the user's output folder.
8. Replace placeholder text, numbers, names, dates, and image placeholders with real content.
9. Add or remove slides as needed, updating counters/chrome.
10. If a needed layout is missing, extend the chosen template using the same fonts, palette, spacing, decorative vocabulary, component grammar, and navigation.

Never combine slides from different templates. A template is a closed visual system.

From-Scratch Workflow

Use this when no bundled template fits, when the user asks for a custom single-file style, or when a design brief requires a bespoke direction.

1. Read references/frontend-slides/viewport-base.css and include its full contents in the deck CSS.
2. Read references/frontend-slides/animation-patterns.md for motion choices.
3. Create a deck folder with index.html.
4. Keep all CSS and JS local to the deck unless a copied runtime file is required.
5. Use CSS variables for palette, typography, spacing, radius, and motion.
6. Design distinctive, context-specific visuals. Avoid generic white cards, generic purple gradients, and default-looking layouts.

PPTX Conversion Workflow

1. Extract content:

python3 skills/html-slides/references/frontend-slides/scripts/extract-pptx.py <input.pptx> <output_dir>

If python-pptx is missing, install it into the available Python environment where appropriate.

2. Read <output_dir>/extracted-slides.json.
3. Summarize slide titles, text density, image count, and notes.
4. Choose template or custom direction using the extracted content.
5. Preserve slide order, important text, images, and speaker notes. Put speaker notes in HTML comments if they should not be visible.
6. Split overloaded slides rather than shrinking content until it becomes unreadable.

Viewport And Density Rules

Every deck must work at 1280x720 and 1440x900. Check a mobile narrow viewport when the user expects mobile sharing.

For every slide:

• Use exact viewport slide sections.
• Prevent internal slide scrolling.
• Use responsive type and spacing.
• Constrain images to the viewport.
• Respect prefers-reduced-motion.
• Split content when it does not fit.

Content limits:

Slide type	Maximum content
Title	1 heading, 1 subtitle, optional meta line
Content	1 heading plus 4-6 bullets, or 1 heading plus 2 short paragraphs
Feature grid	6 cards maximum
Code	8-10 lines
Quote	1 quote, max 3 lines, plus attribution
Image	1 main image plus short caption

Quality Bar

• The deck should look authored, not generated.
• Typography must be intentional and consistent.
• Template fonts, palettes, chrome, and decorative elements must be preserved.
• Data slides need clear hierarchy and source/caption space.
• Chinese and bilingual decks should use templates or font stacks that support CJK text.
• Do not use emoji as icons or visual system elements.
• Do not introduce external brand logos or copyrighted imagery unless the user provides or requests them.

Delivery Checklist

Before delivery:

• Open or render the deck locally if tools are available.
• Verify there are no blank slides.
• Verify no slide has visible overflow or unintended scrolling.
• Verify navigation works with keyboard or template runtime.
• Verify relative assets load.
• Verify license files remain in bundled reference sources when copied as part of the skill.

Report:

• Absolute path to the final index.html.
• Template name or custom direction used.
• Slide count.
• Any caveats such as missing user images or skipped optional conversion details.