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

The 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 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, 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 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:

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 array:

// 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 requires developers to run a self-inspection checklist that verifies:

• Proper token usage from 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 file acts as a strict style-and-implementation manual located at 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 files for colors and typography
• Requires narration arrays in 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, 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}