# Key Files and References for the Web-Video-Presentation Skill in Garden

> Explore key files and references for the web-video-presentation skill, a Vite React TypeScript scaffold for creating cinematic web presentations. Learn how to convert scripts to video.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-08-30

---

**The web-video-presentation skill provides a complete Vite + React + TypeScript scaffold for converting scripts into cinematic 16:9 web presentations, with core logic residing in `skills/web-video-presentation/` and guided by six canonical reference documents.**

The **web-video-presentation** skill inside the `ConardLi/garden-skills` repository enables agents to generate click-driven presentations suitable for screen recording. It combines a chapter-step cursor model, hard collaboration checkpoints, and a token-based theme architecture. Understanding the file structure is essential for customizing the scaffold, managing the audio pipeline, or extending the theme system.

## Core Architecture Files

### Project Metadata and Documentation

Every skill in the garden starts with its identity documents. The **web-video-presentation** skill defines its package metadata in [`skills/web-video-presentation/manifest.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/manifest.json), which specifies the name, description, and homepage. Human-readable specifications and workflow summaries live in [`skills/web-video-presentation/SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/SKILL.md), while end-user quick-start guides and demo screenshots are located in [`skills/web-video-presentation/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/README.md).

### Scaffolding and Build Configuration

The entry point for project generation is [`skills/web-video-presentation/scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/scripts/scaffold.sh). This bash script performs one-click project initialization and handles theme selection via the `--theme` flag. Once generated, the project relies on [`skills/web-video-presentation/templates/vite.config.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/vite.config.ts) for build tooling configuration, ensuring the Vite bundler correctly processes the React and TypeScript assets.

### React Components and UI Layer

The runtime UI is assembled from several key components within the templates directory. The application bootstrap occurs in [`skills/web-video-presentation/templates/src/main.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/main.tsx), which mounts the React tree. The shell component in [`skills/web-video-presentation/templates/src/App.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/App.tsx) maintains the chapter registry and high-level layout.

Visual rendering happens inside [`skills/web-video-presentation/templates/src/components/Stage.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/components/Stage.tsx), which creates the full-screen 16:9 canvas (1920×1080) that scales responsively while maintaining aspect ratio. Navigation feedback is provided by [`skills/web-video-presentation/templates/src/components/ProgressBar.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/components/ProgressBar.tsx), a hidden UI element that only appears on cursor hover to keep recordings clean.

### State Management and Custom Hooks

Presentation state is managed through a collection of custom hooks in the templates directory:

- **`useStepper`** ([`skills/web-video-presentation/templates/src/hooks/useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/hooks/useStepper.ts)): Implements the global step counter with persistent storage, tracking the current position across the chapter-step cursor model.
- **`useStageScale`** ([`skills/web-video-presentation/templates/src/hooks/useStageScale.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/hooks/useStageScale.ts)): Maintains the fixed 1920×1080 stage dimensions while scaling the output to fit the browser viewport.
- **`useAutoMode`** ([`skills/web-video-presentation/templates/src/hooks/useAutoMode.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/hooks/useAutoMode.ts)): Provides optional auto-play functionality essential for hands-free recording workflows.
- **`useAudioPlayer`** ([`skills/web-video-presentation/templates/src/hooks/useAudioPlayer.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/hooks/useAudioPlayer.ts)): Handles playback of synthesized narration audio synchronized to presentation steps.

### Audio Pipeline and TTS Integration

The skill includes a complete text-to-speech workflow. Narration extraction is handled by [`skills/web-video-presentation/templates/scripts/extract-narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/extract-narrations.ts), which scans all [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) files throughout the project and aggregates them into [`audio-segments.json`](https://github.com/ConardLi/garden-skills/blob/main/audio-segments.json).

Audio synthesis is orchestrated by [`skills/web-video-presentation/templates/scripts/synthesize-audio.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/synthesize-audio.sh), which loops over segments and delegates to TTS providers. Built-in provider implementations include [`skills/web-video-presentation/templates/scripts/tts-providers/minimax.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/tts-providers/minimax.sh) and [`skills/web-video-presentation/templates/scripts/tts-providers/openai.sh`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/tts-providers/openai.sh). Extensibility instructions are documented in [`skills/web-video-presentation/templates/scripts/tts-providers/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/tts-providers/README.md).

### Theme System and Tokens

Visual styling follows a token-based architecture. Each theme resides in its own subdirectory under `skills/web-video-presentation/themes/`, containing two critical files:

- **[`tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/tokens.css)**: Defines the design system variables including colors, fonts, and spacing (e.g., [`skills/web-video-presentation/themes/paper-press/tokens.css`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/themes/paper-press/tokens.css)).
- **[`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json)**: Provides human-readable metadata describing the theme's mood and intended use case (e.g., [`skills/web-video-presentation/themes/paper-press/theme.json`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/themes/paper-press/theme.json)).

## Reference Documentation

The skill enforces a four-phase workflow through six canonical reference documents stored in `skills/web-video-presentation/references/`:

| Document | Purpose | Phase |
|----------|---------|-------|
| [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) | Implementation guide for building individual chapters | Phase 2.4 |
| [`SCRIPT-STYLE.md`](https://github.com/ConardLi/garden-skills/blob/main/SCRIPT-STYLE.md) | Converting source articles into [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) format | Phase 1.2 |
| [`OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/OUTLINE-FORMAT.md) | Creating structured [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) documents | Phase 1.2 |
| [`THEMES.md`](https://github.com/ConardLi/garden-skills/blob/main/THEMES.md) | Theme selection criteria and creation guidelines | Checkpoint Plan |
| [`AUDIO.md`](https://github.com/ConardLi/garden-skills/blob/main/AUDIO.md) | Audio synthesis workflow and TTS configuration | Phase 3 |
| [`RECORDING.md`](https://github.com/ConardLi/garden-skills/blob/main/RECORDING.md) | Screen capture settings and export procedures | Phase 4 |

Optional structural inspiration is available in `skills/web-video-presentation/references/EXAMPLES/`, though these serve as reference implementations rather than copy-paste templates.

## Workflow Implementation

### Phase 1: Outline and Script Development

Begin by consulting [`references/OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/references/OUTLINE-FORMAT.md) to structure the [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) file. Convert this into a full script using the conventions in [`references/SCRIPT-STYLE.md`](https://github.com/ConardLi/garden-skills/blob/main/references/SCRIPT-STYLE.md), ensuring the narrative flow matches the intended visual pacing.

### Phase 2: Chapter Development

During implementation, agents must read [`references/CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/references/CHAPTER-CRAFT.md) for every chapter created. Each chapter requires registration in [`templates/src/registry/chapters.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/registry/chapters.ts) and must export a [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) file defining the step count and spoken text for that segment. The `useStepper` hook consumes this configuration to advance the presentation state.

### Phase 3: Audio Synthesis

After authoring narrations, run the extraction and synthesis pipeline:

```bash

# Extract narration metadata from all chapters

npm run extract-narrations

# Generate audio using default MiniMax provider

npm run synthesize-audio

# Or use OpenAI TTS

PRESENTATION_TTS=openai npm run synthesize-audio

```

These commands invoke the scripts in `templates/scripts/` to produce synchronized audio assets.

### Phase 4: Recording

Final video capture follows the procedures in [`references/RECORDING.md`](https://github.com/ConardLi/garden-skills/blob/main/references/RECORDING.md), utilizing the clean 16:9 canvas rendered by the `Stage` component and the auto-play capabilities provided by `useAutoMode`.

## Quick Start Example

Initialize a new presentation project and start the development server:

```bash

# 1. Scaffold a new project with the paper-press theme

bash skills/web-video-presentation/scripts/scaffold.sh ./my-video --theme=paper-press

# 2. Remove starter example (optional)

rm -rf my-video/src/chapters/01-example

# Edit my-video/src/registry/chapters.ts to remove the example import

# 3. Install dependencies

cd my-video
npm install

# 4. Start development server

npm run dev

```

The development server typically starts on `http://localhost:5173`. The `Stage` component automatically scales the 1920×1080 canvas to fit the browser, while `useStepper` manages navigation state.

## Summary

- **Core scaffold**: Generated by [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh) and built with Vite configuration from [`templates/vite.config.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/vite.config.ts).
- **UI components**: [`Stage.tsx`](https://github.com/ConardLi/garden-skills/blob/main/Stage.tsx) renders the 16:9 canvas; [`ProgressBar.tsx`](https://github.com/ConardLi/garden-skills/blob/main/ProgressBar.tsx) provides hover-only navigation feedback.
- **State management**: [`useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/useStepper.ts) drives the global step counter; [`useStageScale.ts`](https://github.com/ConardLi/garden-skills/blob/main/useStageScale.ts) maintains aspect ratio across viewports.
- **Audio pipeline**: [`extract-narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/extract-narrations.ts) aggregates text; [`synthesize-audio.sh`](https://github.com/ConardLi/garden-skills/blob/main/synthesize-audio.sh) delegates to MiniMax or OpenAI providers.
- **Theming**: Token-based CSS variables in `themes/*/tokens.css` with metadata in `themes/*/theme.json`.
- **Workflow guides**: Six reference documents in `references/` govern the four-phase creation process from outline to final recording.

## Frequently Asked Questions

### What file controls the step navigation in a web-video-presentation?

The `useStepper` hook in [`skills/web-video-presentation/templates/src/hooks/useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/hooks/useStepper.ts) controls the global step counter. It persists state across browser sessions and coordinates with chapter-specific [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) files to determine the total step count for each section.

### How do I add a custom TTS provider to the audio pipeline?

Create a new bash script following the interface defined in [`skills/web-video-presentation/templates/scripts/tts-providers/README.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/scripts/tts-providers/README.md). Place your script in `templates/scripts/tts-providers/` and invoke it by setting the `PRESENTATION_TTS` environment variable to your provider's name before running `npm run synthesize-audio`.

### Where is the 16:9 aspect ratio enforced in the codebase?

The `Stage` component in [`skills/web-video-presentation/templates/src/components/Stage.tsx`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/templates/src/components/Stage.tsx) defines the 1920×1080 presentation canvas. The `useStageScale` hook in [`templates/src/hooks/useStageScale.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/hooks/useStageScale.ts) calculates the CSS transforms necessary to fit this fixed-resolution stage into the browser viewport while preserving the 16:9 aspect ratio.

### Which reference document should I read first when creating a new presentation?

Start with [`skills/web-video-presentation/references/OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/OUTLINE-FORMAT.md) during Phase 1.2 to structure your content architecture. Follow with [`references/SCRIPT-STYLE.md`](https://github.com/ConardLi/garden-skills/blob/main/references/SCRIPT-STYLE.md) to convert the outline into a presentable script before proceeding to chapter implementation.