CLAUDE.md

Motion Design Agent System

This file instructs Claude on how to work with this project. Read this file first, then consult docs/spec.md for detailed specifications.

Project Overview

This project implements a Motion Design Agent — a skill system that enables Claude to create animations and motion graphics using industry standards. The system is built on:

• agentskills.io specification for skill file format
• W3C Design Tokens (2025.10) for token interchange
• Material Design 3 as the primary motion baseline
• Lottie Specification v1.0 for animation export
• WCAG 2.1 for accessibility compliance

Directory Structure

motion-design/
├── CLAUDE.md                 # ← You are here. Project instructions.
├── docs/
│   └── spec.md               # Complete specification document
│
├── SKILL.md                  # Root skill (orchestrator)
│
├── tokens/                   # W3C DTCG format tokens
│   ├── motion.tokens.json    # Complete token set
│   ├── easing.tokens.json    # Easing curves only
│   ├── duration.tokens.json  # Duration scale only
│   └── spring.tokens.json    # Spring physics configs
│
├── references/               # Root-level references
│   ├── industry-standards.md
│   ├── design-system-comparison.md
│   └── tool-selection.md
│
├── skills/                   # Sub-skills (agentskills.io compliant)
│   ├── motion-principles/
│   ├── easing/
│   ├── duration/
│   ├── transitions/
│   ├── entrance-patterns/
│   ├── exit-patterns/
│   ├── accessibility/
│   ├── lottie/
│   ├── remotion/
│   └── tools/
│
├── presets/                  # Implementation presets
│   ├── remotion-m3.ts
│   ├── gsap-presets.js
│   └── framer-motion-presets.ts
│
└── templates/                # Starter templates
    ├── lottie/
    └── remotion/

How to Work on This Project

Reading Order

1. This file (CLAUDE.md) — Project overview and instructions
2. docs/spec.md — Complete specification with all details
3. tokens/motion.tokens.json — Token values (if it exists)
4. Individual skill files — As needed for specific tasks

Key Principles

1. Standards First — Every motion value must trace to an industry standard
2. Tokens Over Raw Values — Always reference token names, not hardcoded numbers
3. M3 as Baseline — Material Design 3 is the default; cross-reference others when needed
4. Accessibility Required — Every animation must have a reduced-motion alternative
5. agentskills.io Compliant — All SKILL.md files must have valid YAML frontmatter

When Building Files

Always check docs/spec.md first for the exact content, format, and structure of any file you're creating. The spec contains complete examples of:

• W3C DTCG token format
• SKILL.md frontmatter requirements
• Cross-system comparison tables
• Implementation code examples

Standards Quick Reference

W3C Design Tokens Format

All token files use this structure:

{
  "tokenName": {
    "$value": "<value>",
    "$type": "<type>",
    "$description": "<description with cross-system references>"
  }
}

Types used in this project:

• duration — e.g., "250ms"
• cubicBezier — e.g., [0.2, 0, 0, 1]
• transition — composite of duration + timing + delay
• object — for spring configs (non-standard but practical)

Material Design 3 Baseline

Easing (Primary):

Duration (Primary):

agentskills.io SKILL.md Format

Every SKILL.md must have:

---
name: skill-name
description: What the skill does. When to use it. Must include both WHAT and WHEN.
---

# Skill Title

Content here...

Constraints:

• name: 1-64 chars, lowercase, hyphens only, must match directory name
• description: 1-1024 chars, must include capability AND usage context
• Body: <5000 tokens (put details in references/ subdirectory)

Build Tasks

Task 1: Create Token Files

Location: tokens/

Create these files following W3C DTCG format (see docs/spec.md for complete content):

1. motion.tokens.json — Complete token set with all easing, duration, spring, and transition tokens
2. easing.tokens.json — Just the easing curves (subset of motion.tokens.json)
3. duration.tokens.json — Just the duration scale
4. spring.tokens.json — Spring physics configurations

Validation: Each token must have $value, $type, and $description with cross-system references.

Task 2: Create Root SKILL.md

Location: SKILL.md (project root)

This is the orchestrator that:

• Describes the motion-design agent capability
• Lists all sub-skills with their purposes
• Provides decision frameworks for easing, duration, tool selection
• Defines output requirements (cite standard, use tokens, include accessibility)

See docs/spec.md section "Root Skill: SKILL.md" for complete content.

Task 3: Create Sub-Skills

Location: skills/<skill-name>/SKILL.md

Each sub-skill needs:

1. SKILL.md with proper frontmatter
2. references/ directory with detailed documentation

Sub-skills to create:

Task 4: Create References

Location: references/ (root) and skills/<skill>/references/

Root-level references:

• industry-standards.md — Overview of all standards used
• design-system-comparison.md — M3 vs Fluent vs Carbon vs Apple
• tool-selection.md — When to use which animation tool

Skill-level references contain detailed documentation that would bloat the SKILL.md.

Task 5: Create Presets

Location: presets/

Implementation-ready code files:

1. remotion-m3.ts — TypeScript presets for Remotion with M3 tokens
2. gsap-presets.js — GSAP animation presets
3. framer-motion-presets.ts — Framer Motion variants and transitions

These should import from tokens/ and export ready-to-use configurations.

Task 6: Create Templates

Location: templates/

Starter templates for common use cases:

• lottie/ — Lottie JSON templates
• remotion/ — Remotion composition templates (title cards, lower thirds, etc.)

Validation Checklist

Before considering the project complete, verify:

agentskills.io Compliance

• All SKILL.md files have YAML frontmatter with name and description
• All name fields are lowercase with hyphens, ≤64 chars
• All description fields include WHAT + WHEN, ≤1024 chars
• Directory names match name fields exactly
• Each SKILL.md body is <5000 tokens
• Reference files are one level deep from SKILL.md

W3C Design Tokens Compliance

• All token files use $value, $type, $description
• cubicBezier type uses array format [x1, y1, x2, y2]
• duration type uses string format "250ms"
• Token references use {path.to.token} syntax

Standards Compliance

• M3 is cited as primary baseline
• Cross-system mappings exist for Fluent, Carbon, Apple
• Lottie spec v1.0 referenced correctly
• WCAG 2.1 requirements addressed

Implementation Coverage

• CSS implementation examples
• GSAP implementation examples
• Framer Motion implementation examples
• Remotion implementation examples
• Lottie usage examples
• Reduced motion alternatives for all patterns

Common Operations

Adding a New Token

1. Add to tokens/motion.tokens.json with full W3C DTCG format
2. Include $description with cross-system references
3. Update relevant subset file (easing.tokens.json, etc.)
4. Update any presets that should use the new token

Adding a New Skill

1. Create directory: skills/<skill-name>/
2. Create SKILL.md with valid frontmatter
3. Create references/ subdirectory if needed
4. Add skill to index in root SKILL.md
5. Validate frontmatter constraints

Adding a New Pattern

1. Determine which skill it belongs to
2. Add to appropriate SKILL.md or create reference file
3. Include: token references, code example, accessibility alternative
4. Cross-reference M3 (or other standard) documentation

Updating Token Values

1. Update tokens/motion.tokens.json
2. Verify cross-system mappings are still accurate
3. Update subset files if they exist
4. Presets auto-import, so they'll get new values

Code Style

Token File Naming

motion.tokens.json      # Complete set
easing.tokens.json      # Subset
duration.tokens.json    # Subset

Skill Directory Naming

skills/motion-principles/   # lowercase, hyphens
skills/easing/              # single word OK
skills/entrance-patterns/   # descriptive

Implementation Code

Always import tokens rather than hardcoding:

// ✓ Good
import tokens from '../tokens/motion.tokens.json';
const duration = tokens.motion.duration['medium-1'].$value;

// ✗ Bad
const duration = '250ms';

Always include reduced motion:

// ✓ Good
const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
const duration = prefersReducedMotion ? '0ms' : '250ms';

// ✗ Bad
const duration = '250ms'; // No accessibility consideration

External References

When you need to verify against original sources:

Getting Started

To build out this project:

1. Read docs/spec.md — Contains all the content to generate
2. Create tokens/motion.tokens.json — Foundation for everything else
3. Create root SKILL.md — Orchestrator
4. Create sub-skills in priority order:
   • easing/ and duration/ (core tokens)
   • accessibility/ (required for all)
   • transitions/ and entrance-patterns/ (common patterns)
   • lottie/ and remotion/ (implementation)
   • tools/ (selection guide)
5. Create presets — Implementation-ready code
6. Validate — Run through checklist

The spec.md file contains the complete content for every file. Your job is to generate the files in the correct locations with the correct format.

Questions to Ask

When working on this project, consider:

1. Which standard applies? — Default to M3, but check if platform-specific
2. Is this in the spec? — Check docs/spec.md before creating content
3. Does it have accessibility? — Every animation needs reduced-motion alternative
4. Is it using tokens? — Never hardcode values that exist as tokens
5. Is the skill compliant? — Check frontmatter, naming, token budget

Success Criteria

The project is complete when:

1. ✅ All files from docs/spec.md are generated
2. ✅ All SKILL.md files pass agentskills.io validation
3. ✅ All tokens follow W3C DTCG format
4. ✅ All motion values trace to industry standards
5. ✅ All patterns have accessibility alternatives
6. ✅ Presets import from token files (not hardcoded)
7. ✅ An agent using this skill system can:
   • Select appropriate easing for any animation type
   • Select appropriate duration for any element size
   • Choose the right tool for the job
   • Export Lottie-compliant animations
   • Ensure WCAG accessibility compliance
   • Cross-reference values across design systems