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

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 located at 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 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 mandates a strict architectural boundary between spoken content and visual enhancements. The 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 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. 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.

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

// 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 operates within an ecosystem of files that collectively define the web video presentation skill:

• CHAPTER-CRAFT.md (skills/web-video-presentation/references/CHAPTER-CRAFT.md): The development guide specifying architectural contracts.
• SKILL.md: High-level description of the skill's purpose and capabilities.
• script.md: Linear narrative script providing the spoken content for each step.
• 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 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 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 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 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 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.

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