presentation-builder

# Presentation Builder

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

Based on [zarazhangrui/frontend-slides](https://github.com/zarazhangrui/frontend-slides), restructured for OrchestKit.

## Core Philosophy

1. **Zero Dependencies** -- Single HTML files with inline CSS/JS. No npm, no build tools.
2. **Show, Don't Tell** -- Generate visual previews, not abstract choices. People discover preferences by seeing.
3. **Distinctive Design** -- Avoid generic "AI slop" aesthetics. Every presentation should feel custom-crafted.
4. **Production Quality** -- Well-commented, accessible, performant code.
5. **Viewport Fitting** -- Every slide MUST fit exactly within the viewport. No scrolling within slides, ever.

## Phase 0: Detect Mode

Determine what the user wants:

| Mode | Trigger | Next Phase |
|------|---------|------------|
| **A: New Presentation** | Create slides from scratch | Phase 1 |
| **B: PPT Conversion** | Has a .ppt/.pptx file | Load `Read("${CLAUDE_SKILL_DIR}/references/pptx-conversion.md")` then Phase 2 |
| **C: Enhancement** | Has existing HTML presentation | Read file, understand structure, enhance |

---

## Phase 1: Content Discovery

Before designing, understand the content. Use `AskUserQuestion`:

**Question 1: Purpose**
- Header: "Purpose"
- Options: "Pitch deck", "Teaching/Tutorial", "Conference talk", "Internal presentation"

**Question 2: Slide Count**
- Header: "Length"
- Options: "Short (5-10)", "Medium (10-20)", "Long (20+)"

**Question 3: Content Readiness**
- Header: "Content"
- Options: "I have all content ready", "I have rough notes", "I have a topic only"

If user has content, ask them to share it. If topic only, help structure an outline.

---

## Phase 2: Style Discovery

**This is the "show, don't tell" phase.**

### Step 2.0: Style Path Selection

Ask how the user wants to choose their style:

- **"Show me options"** -- Generate 3 previews based on mood (recommended)
- **"I know what I want"** -- Pick from preset list directly

**Available Presets** (load `Read("${CLAUDE_SKILL_DIR}/references/style-presets.md")` for full details):

| Preset | Vibe | Best For |
|--------|------|----------|
| Bold Signal | Confident, high-impact | Pitch decks, keynotes |
| Electric Studio | Clean, professional | Agency presentations |
| Creative Voltage | Energetic, retro-modern | Creative pitches |
| Dark Botanical | Elegant, sophisticated | Premium brands |
| Notebook Tabs | Editorial, organized | Reports, reviews |
| Pastel Geometry | Friendly, approachable | Product overviews |
| Split Pastel | Playful, modern | Creative agencies |
| Vintage Editorial | Witty, personality-driven | Personal brands |
| Neon Cyber | Futuristic, techy | Tech startups |
| Terminal Green | Developer-focused | Dev tools, APIs |
| Swiss Modern | Minimal, precise | Corporate, data |
| Paper & Ink | Literary, thoughtful | Storytelling |

### Step 2.1: Mood Selection (Guided Discovery)

If "Show me options", ask via `AskUserQuestion`:

**Question: Vibe**
- "What feeling should the audience have?"
- Options (multiSelect: true, pick up to 2):
  - "Impressed/Confident" -- Professional, trustworthy
  - "Excited/Energized" -- Innovative, bold
  - "Calm/Focused" -- Clear, easy to follow
  - "Inspired/Moved" -- Emotional, memorable

**Mood-to-Style Mapping:**

| Mood | Suggested Styles |
|------|-----------------|
| Impressed/Confident | Bold Signal, Electric Studio, Dark Botanical |
| Excited/Energized | Creative Voltage, Neon Cyber, Split Pastel |
| Calm/Focused | Notebook Tabs, Paper & Ink, Swiss Modern |
| Inspired/Moved | Dark Botanical, Vintage Editorial, Pastel Geometry |

### Step 2.2: Generate Style Previews

Generate **3 distinct mini HTML files** in `.claude-design/slide-previews/`:

```
.claude-design/slide-previews/
├── style-a.html   # ~50-100 lines, single title slide
├── style-b.html
└── style-c.html
```

Each preview: self-contained, inline CSS/JS, animated title slide showing typography, colors, and motion style.

### Step 2.3: Present Previews

Show user the 3 options and ask via `AskUserQuestion`:
- "Which style preview do you prefer?"
- Options: Style A, Style B, Style C, "Mix elements"

---

## Phase 3: Generate Presentation

Generate the full presentation based on content (Phase 1) and style (Phase 2).

### File Output

```
presentation.html    # Self-contained presentation
assets/              # Images if any (PPT conversion)
```

### HTML Architecture

Every presentation follows this structure:

```html
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Presentation Title</title>
    <!-- Fonts from Fontshare or Google Fonts -->
    <style>
        /* Theme variables in :root */
        /* Base styles + viewport fitting (see rules/viewport-fitting.md) */
        /* Slide container styles */
        /* Animations */
        /* Responsive breakpoints */
    </style>
</head>
<body>
    <div class="progress-bar"></div>
    <nav class="nav-dots"><!-- JS generated --></nav>
    <section class="slide title-slide">...</section>
    <section class="slide">...</section>
    <!-- More slides -->
    <script>
        /* SlidePresentation class with navigation */
    </script>
</body>
</html>
```

### Critical: Viewport Fitting

**Every slide MUST fit exactly in the viewport.** Load: `Read("${CLAUDE_SKILL_DIR}/rules/viewport-fitting.md")`

Quick checklist:
- Every `.slide` has `height: 100vh; height: 100dvh; overflow: hidden;`
- All font sizes use `clamp(min, preferred, max)`
- All spacing uses `clamp()` or viewport units
- Content respects density limits (load `${CLAUDE_SKILL_DIR}/rules/content-density.md`)
- Breakpoints exist for heights: 700px, 600px, 500px
- When content doesn't fit: **split into multiple slides, never scroll**

Also see `responsive-patterns` skill for advanced clamp()/container query patterns.

### Required JavaScript Feature