# What Is the Purpose of the CHAPTER-CRAFT.md File? A Video-First Development Guide

> Discover the purpose of CHAPTER-CRAFT.md in ConardLi/garden-skills. This video-first development guide transforms articles into dynamic visual experiences with React and CSS animations.

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

---

**The [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) file serves as the authoritative chapter-development guide for the Web-Video-Presentation skill, enforcing a video-first methodology that transforms static articles into dynamic, step-driven visual experiences using React, CSS animations, and strict design tokens.**

The [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) file in the **ConardLi/garden-skills** repository defines the canonical standards for creating web-based video presentations. 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), this document mandates a radical departure from traditional slide decks, requiring instead a cinematic, code-driven approach where each chapter behaves like a video clip rather than a static PowerPoint slide.

## Video-First Methodology vs. Traditional Slides

According to the source code analysis, the guide establishes that **each chapter must be a video, not a PPT slide deck**. This philosophical shift impacts every implementation decision in the repository. Rather than displaying static bullet points, chapters in `skills/web-video-presentation/chapters/<Chapter>.tsx` must deliver motion-based storytelling that mimics professional video editing—using code to orchestrate entrances, transitions, and visual reveals.

## Dynamic Visual Elements Requirement

The guide mandates **dynamic visual elements** using CSS, SVG, Canvas, or JavaScript. Specifically, every chapter must include at least one or two animated graphics that move or transform. The document explicitly prohibits static screenshots or "AI-generated visual fingerprints"—recognizable generic patterns produced by image generators—ensuring that all visuals are purpose-built through code.

## Step-Driven Workflow Architecture

A core technical requirement enforced by [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) is the **global step counter** pattern. Instead of rendering all content at once, chapters must use a progressive disclosure system driven by a `step` variable that increments with user interactions (clicks or arrow keys).

In `skills/web-video-presentation/chapters/<Chapter>.tsx`, developers implement this using the `useStep` hook:

```tsx
import { useStep } from '@/hooks/useStep';
import styles from './MyChapter.module.css';

export default function MyChapter() {
  const step = useStep();                       // driven by clicks / arrow keys
  return (
    <section className={styles.stage}>
      {step >= 1 && <div className="hero-num">42</div>}
      {step >= 2 && <svg className="chart">…</svg>}
      {/* Each step adds a new visual, never all at once */}
    </section>
  );
}

```

This approach ensures that content unfolds sequentially, matching the pacing of voice-over narrations defined in companion files.

## Design Constraints and Token Systems

The file stipulates strict **design constraints** to maintain consistency across the presentation ecosystem:

- **Large typography** and **ample white-space** for readability
- **Token-based colors and fonts** defined in `skills/web-video-presentation/themes/*/theme.json`
- Prohibition of arbitrary values—所有 styling must reference the design token system

These constraints ensure that every chapter in the repository shares a cohesive visual language, regardless of who authors the component.

## Narration Synchronization Requirements

The guide requires perfect synchronization between visual steps and audio narration. Each step trigger must correspond to a specific entry in the [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) array:

```ts
// skills/web-video-presentation/chapters/<Chapter>/narrations.ts
export const narrations = [
  "First we see the number 42…",
  "Now the chart animates to show growth…",
];

```

The length of the narrations array must exactly match the number of step checks in the component, ensuring that the spoken word aligns precisely with visual reveals.

## Self-Inspection Checklist

Before any chapter is considered complete, [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) requires developers to run a **self-inspection checklist** that verifies:

- Proper token usage from [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json)
- Appropriate step granularity (neither too fast nor too slow)
- Alignment between narration text and visual animations
- Animation duration limits that prevent user fatigue

This quality gate ensures that all chapters in `skills/web-video-presentation/chapters/` meet the repository's high standards for video-like flow and professional polish.

## Summary

- The [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) file acts as a strict style-and-implementation manual 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)
- It enforces a **video-first paradigm** that rejects traditional slide-based presentations
- Requires **dynamic visuals** using CSS, SVG, or Canvas animations rather than static images
- Implements a **global step counter** via the `useStep` hook for progressive content disclosure
- Mandates **token-based design** referencing [`theme.json`](https://github.com/ConardLi/garden-skills/blob/main/theme.json) files for colors and typography
- Requires **narration arrays** in [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) that sync with visual steps
- Provides a **pre-submission checklist** to verify animation quality and token compliance

## Frequently Asked Questions

### What is the difference between a chapter and a traditional slide?

A traditional slide displays static content all at once, while a chapter in the Web-Video-Presentation skill behaves like a video clip. According to [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md), chapters must use the `useStep` hook to reveal content gradually, incorporate CSS or Canvas animations, and follow strict design tokens—transforming passive reading into an interactive, cinematic experience.

### How does the global step counter work in practice?

The global step counter is implemented through the `useStep` hook imported from `@/hooks/useStep`. In `skills/web-video-presentation/chapters/<Chapter>.tsx`, developers conditionally render JSX elements based on the current `step` value, which increments via user clicks or keyboard navigation. Each step corresponds to a narration string in `skills/web-video-presentation/chapters/<Chapter>/narrations.ts`, ensuring visual and audio synchronization.

### Why does the guide prohibit AI-generated visual elements?

[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) prohibits AI-generated visual "fingerprints" to maintain code-driven authenticity and avoid generic aesthetics. The guide requires developers to build visuals using CSS, SVG, Canvas, or JavaScript animations, ensuring that every graphic is purpose-crafted for the specific narrative rather than relying on stock-like AI imagery that lacks contextual precision.

### Where are the design tokens defined for chapter styling?

Design tokens are defined in `skills/web-video-presentation/themes/*/theme.json`. The [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md) file mandates that all chapters reference these tokens for colors, fonts, and spacing rather than using hardcoded values, ensuring visual consistency across the entire Web-Video-Presentation skill ecosystem.