frontend-slides

---
name: frontend-slides
description: Create stunning, animation-rich, zero-dependency HTML presentations from
  scratch or by converting PowerPoint files. Enforces viewport-fit (one slide = one
  viewport, no scrolling), distinctive design presets, and a discovery-by-preview
  workflow. Use when the user asks to build a presentation/talk/pitch deck, convert
  a .ppt or .pptx to HTML, improve an existing HTML deck, asks about slide layout,
  slide animations, keyboard/touch navigation, viewport fitting with clamp() and 100dvh,
  presentation themes/style presets, or python-pptx for PPTX extraction.
---

# Frontend Slides

Create zero-dependency, animation-rich HTML presentations that run entirely in the browser.

Inspired by the visual exploration approach showcased in work by zarazhangrui (credit: @zarazhangrui).

## When to Activate

- Creating a talk deck, pitch deck, workshop deck, or internal presentation
- Converting `.ppt` or `.pptx` slides into an HTML presentation
- Improving an existing HTML presentation's layout, motion, or typography
- Exploring presentation styles with a user who does not know their design preference yet

## Non-Negotiables

1. **Zero dependencies**: default to one self-contained HTML file with inline CSS and JS.
2. **Viewport fit is mandatory**: every slide must fit inside one viewport with no internal scrolling.
3. **Show, don't tell**: use visual previews instead of abstract style questionnaires.
4. **Distinctive design**: avoid generic purple-gradient, Inter-on-white, template-looking decks.
5. **Production quality**: keep code commented, accessible, responsive, and performant.

Before generating, read `~/.codex/plugins/ycc/skills/frontend-slides/references/style-presets.md` for the viewport-safe CSS base, density limits, preset catalog, and CSS gotchas.

## Workflow

### 1. Detect Mode

Choose one path:

- **New presentation** — user has a topic, notes, or full draft
- **PPT conversion** — user has `.ppt` or `.pptx`
- **Enhancement** — user already has HTML slides and wants improvements

### 2. Discover Content

Ask only the minimum needed:

- purpose: pitch, teaching, conference talk, internal update
- length: short (5–10), medium (10–20), long (20+)
- content state: finished copy, rough notes, topic only

If the user has content, ask them to paste it before styling.

### 3. Discover Style

Default to visual exploration.

If the user already knows the desired preset, skip previews and use it directly.

Otherwise:

1. Ask what feeling the deck should create: impressed, energized, focused, inspired.
2. Generate **3 single-slide preview files** in `.slide-previews/`.
3. Each preview must be self-contained, show typography/color/motion clearly, and stay under roughly 100 lines of slide content.
4. Ask the user which preview to keep or what elements to mix.

Use the preset guide in `~/.codex/plugins/ycc/skills/frontend-slides/references/style-presets.md` when mapping mood to style.

### 4. Build the Presentation

Output either:

- `presentation.html`
- `[presentation-name].html`

Use an `assets/` folder only when the deck contains extracted or user-supplied images.

Required structure:

- semantic slide sections
- the viewport-safe CSS base from the style-presets reference
- CSS custom properties for theme values
- a presentation controller class for keyboard, wheel, and touch navigation
- `IntersectionObserver` for reveal animations
- `prefers-reduced-motion` support

### 5. Enforce Viewport Fit

Treat this as a hard gate.

Rules:

- every `.slide` must use `height: 100vh; height: 100dvh; overflow: hidden;`
- all type and spacing must scale with `clamp()`
- when content does not fit, split into multiple slides
- never solve overflow by shrinking text below readable sizes
- never allow scrollbars inside a slide

Use the density limits and mandatory CSS block in the style-presets reference.

### 6. Validate

Check the finished deck at these sizes:

- 1920×1080
- 1280×720
- 768×1024
- 375×667
- 667×375

If browser automation is available (e.g. Playwright), use it to verify no slide overflows and that keyboard navigation works.

### 7. Deliver

At handoff:

- delete temporary preview files unless the user wants to keep them
- open the deck with the platform-appropriate opener when useful
- summarize file path, preset used, slide count, and easy theme customization points

Use the correct opener for the current OS:

- macOS: `open file.html`
- Linux: `xdg-open file.html`
- Windows: `start "" file.html`

## PPT / PPTX Conversion

For PowerPoint conversion:

1. Prefer `python3` with `python-pptx` to extract text, images, and notes.
2. If `python-pptx` is unavailable, ask whether to install it or fall back to a manual/export-based workflow.
3. Preserve slide order, speaker notes, and extracted assets.
4. After extraction, run the same style-selection workflow as a new presentation.

Keep conversion cross-platform. Do not rely on macOS-only tools when Python can do the job.

## Implementation Requirements

### HTML / CSS

- Use inline CSS and JS unless the user explicitly wants a multi-file project.
- Fonts may come from Google Fonts or Fontshare.
- Prefer atmospheric backgrounds, strong type hierarchy, and a clear visual direction.
- Use abstract shapes, gradients, grids, noise, and geometry rather than illustrations.

### JavaScript

Include:

- keyboard navigation (arrow keys, space, page up/down)
- touch / swipe navigation
- mouse wheel navigation
- progress indicator or slide index
- reveal-on-enter animation triggers

### Accessibility

- use semantic structure (`main`, `section`, `nav`)
- keep contrast readable
- support keyboard-only navigation
- respect `prefers-reduced-motion`

## Content Density Limits

Use these maxima unless the user explicitly asks for denser slides and readability still holds:

| Slide type   | Limit                                         |
| ------------ | --------------------------------------------- |
| Title        | 1 heading + 1 subtitle + optional tagline     |
| Content      | 1 heading + 4–6 bullets or 2 short paragraphs |
| Feature grid | 6 cards max                                   |
| Code         | 8–10 lines max                                |
| Quote        | 1 quote + attribution                         |
| Image        | 1 image constrained by viewport               |

## Anti-Patterns

- generic startup gradients with no visual identity
- system-font decks unless intentionally editorial
- long bullet walls
- code blocks that need scrolling
- fixed-height content boxes that break on short screens
- invalid negated CSS functions like `-clamp(...)` (use `calc(-1 * clamp(...))` instead)

## Related ycc Skills

- `frontend-patterns` — component and interaction patterns around the deck
- `frontend-design` — visual direction, typography, and composition principles that apply to slides too

## Deliverable Checklist

- presentation runs from a local file in a browser
- every slide fits the viewport without scrolling
- style is distinctive and intentional
- animation is meaningful, not noisy
- reduced motion is respected
- file paths and customization points are explained at handoff