# What Is CHAPTER-CRAFT.md in the Web Video Presentation Skill? A Developer's Guide

> Understand CHAPTER-CRAFT.md's role as the architectural contract for web video presentations. Learn how it enables theme-aware, video-first content creation for developers.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: developer-guide
- Published: 2026-09-02

---

**CHAPTER-CRAFT.md serves as the authoritative architectural contract that defines how individual chapters must be engineered to produce video-first, theme-aware presentations rather than static slide decks.**

In the `ConardLi/garden-skills` repository, the `web-video-presentation` skill relies on [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) located at [`skills/web-video-presentation/references/CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/CHAPTER-CRAFT.md) to enforce strict development standards. This file operates not as runtime code, but as a comprehensive technical specification that ensures every chapter behaves like a polished video segment, maintaining consistency across themes and playback modes.

## Architectural Responsibilities of CHAPTER-CRAFT.md

The guide establishes seven core mandates that transform static content into dynamic video presentations.

### Enforcing Video-First Design Principles

[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) requires developers to adopt a **video-first mindset**, explicitly forbidding PowerPoint-like headers, footers, or dense text blocks that break immersion. Every chapter must render as a fluid video page where content flows cinematically rather than appearing as discrete slides.

### Mandating Visual Dynamism

Each chapter must contain **1–2 animated graphics** implemented via CSS, SVG, Canvas, or JavaScript. This requirement ensures the screen displays continuous *action* rather than static prose, preventing viewer disengagement during playback.

### Step-Driven Navigation Architecture

The specification centers on a global **`step` counter** that drives all visual reveals. Navigation—whether triggered by click or arrow key—advances this single integer, which determines which elements appear on screen. The guide enforces strict **"one item = one step"** granularity, explicitly forbidding the revelation of entire bullet lists in a single transition.

### Separation of Narration and Visuals

[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) mandates a strict architectural boundary between spoken content and visual enhancements. The [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) file provides linear narration, while the visual layer enriches this with supplementary data, charts, or animations. Crucially, the **visual density must exceed the spoken density**, ensuring viewers receive additional value beyond the audio track.

### Theme Token Compliance

All styling must derive from the skill's design token system. Developers must use primitive classes such as `.hero-num`, `.rule`, `.card`, and `.stage-frame` rather than hard-coded HEX values or font names. This constraint guarantees **theme portability**, allowing the same chapter to render correctly across different color schemes and brand identities.

### Engineering Constraints and Isolation

The guide imposes specific technical limitations to ensure reliability:

- **No timers**: `setTimeout` and `setInterval` are strictly prohibited to prevent synchronization drift.
- **Folder isolation**: Each chapter lives in its own directory with isolated CSS prefixes.
- **Narration parity**: Every chapter must include a [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) file exporting an array whose length equals the highest `step` index used in the component code.

### Pre-Deployment Checklist

Before shipping, developers must run a self-check checklist defined in [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md). This validation ensures compliance with requirements such as "≥ 1 visual animation," "step-wise reveal granularity," and "zero hard-coded colors."

## Implementing CHAPTER-CRAFT.md Standards

The following implementation demonstrates compliance with the architectural rules. The component uses the `useStep()` hook to react to the global counter and implements theme-aware classes.

```tsx
// src/chapters/01-intro/Chapter01.tsx
import { useStep } from '@/hooks/useStep';
import './chapter01.css';

export default function Chapter01() {
  const step = useStep();   // global step counter

  return (
    <section className="stage-frame">
      {/* Step 0 – hero title */}
      {step >= 0 && <h1 className="hero-num">Welcome</h1>}

      {/* Step 1 – animated bar */}
      {step >= 1 && (
        <div className="bar">
          <div className="bar-fill" />
        </div>
      )}

      {/* Step 2 – supporting text */}
      {step >= 2 && (
        <p className="text-large">
          In this video we'll explore…
        </p>
      )}
    </section>
  );
}

```

The corresponding narration file must match the step count exactly:

```ts
// src/chapters/01-intro/narrations.ts
export const narrations = [
  "Welcome to the tutorial.",
  "Here's the growth bar rising.",
  "Now let's dive into the details."
];

```

## Relationship to Other Skill Files

[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) operates within an ecosystem of files that collectively define the web video presentation skill:

- **[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md)** ([`skills/web-video-presentation/references/CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/CHAPTER-CRAFT.md)): The development guide specifying architectural contracts.
- **[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)**: High-level description of the skill's purpose and capabilities.
- **[`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md)**: Linear narrative script providing the spoken content for each step.
- **[`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md)**: Information pool used to enrich visual layers with additional context.
- **`chapter/**/*.tsx`**: Concrete chapter implementations following the guide's constraints.
- **`chapter/**/narrations.ts`**: TypeScript files exporting narration arrays synchronized to step indices.

## Summary

- [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) functions as the **architectural contract** for the web-video-presentation skill in `ConardLi/garden-skills`.
- It mandates **video-first design** that avoids traditional slide deck metaphors.
- Navigation relies on a **pure `step` counter** without hidden state or timers.
- Visual density must exceed audio density, with **1–2 animations per chapter**.
- **Theme tokens** must replace hard-coded values to ensure cross-theme compatibility.
- Each chapter requires a matching **[`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts)** file with length parity to the step count.

## Frequently Asked Questions

### Why does CHAPTER-CRAFT.md prohibit timers like setTimeout?

According to the source specification, timers create hidden state and synchronization drift between the visual layer and the global `step` counter. By forcing all animations to be CSS-driven or step-triggered, [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) ensures that chapters behave as **pure functions of `step`**, making them deterministic and easier to debug across different playback speeds.

### How does the narrations.ts file relate to the step counter?

The [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) file must export an array where the index corresponds to the `step` value. If your chapter uses steps 0, 1, and 2, the array must contain exactly three strings. This **length parity** ensures that the video player can synchronize spoken audio with visual transitions without null-checking or index boundary errors.

### Can I use custom fonts or colors outside the theme system?

No. [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) explicitly forbids hard-coded HEX values, font names, or CSS variables outside the token system. All styling must use primitive classes like `.hero-num` or `.stage-frame` that map to theme variables. This constraint guarantees that chapters remain **portable across different visual themes** without code modification.

### What happens if I reveal multiple elements in a single step?

This violates the "one item = one step" rule. The specification requires granular reveals where each navigation action displays exactly one new visual element. Batching multiple items into a single step creates "wall-of-text" effects that resemble static slides rather than dynamic video content, breaking the immersive experience the skill aims to achieve.