# Animation > Interactive motion brief. Six-section survey (page-load, scroll, text, blocks, micro-interactions, intensity) driven by the user's references from references/animation/ and references/motion/. Outputs brief/animation.md and appends motion tokens to DESIGN-LOCK §5. /build enforces the resulting animations as required elements. - Skill: `dkadts/animation` (Agent Skill) - Install (CLI): `npx skillmds@latest add dkadts/animation` - Raw SKILL.md: https://api.skillmd.com/api/skills/dkadts/animation/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: dkadts (https://skillmd.com/u/dkadts) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dkadts/animation --- # /animation Motion is a first-class design system decision, not an afterthought. This skill runs a dedicated conversation about **what animates, how, and why**, grounded in the user's references. Output feeds `/tokens` and is enforced by `/build`. ## When to use - After `/design-lock` (need ease + duration baseline from §5). - Before `/blocks` if the interactive blocks depend on motion (e.g. a modal reveal style must match section reveals). - Before `/tokens` — this skill adds motion tokens that `/tokens` writes to `tokens.css`. ## Requirements - `DESIGN-LOCK.md` §5 (Motion) is `LOCKED` (has ease + duration). - `brief/05-design.md` is filled (mood — affects motion intensity default). - If `references/animation/` or `references/motion/` contain refs: `references/proposal.md` should mention motion patterns found there. If no motion references exist, still run the skill — but every question defaults to `subtle` and explicitly asks the user to confirm rather than accept. ## Process Six sections, in order. Each section: **show what refs suggest → offer 3-4 options → user picks → record.** ### Section 1. Page-load choreography What appears first on initial page load, in what order, with what stagger? Reference read: any first-frame screenshots or notes in `references/animation/*/notes.md`. Options (present as A / B / C, first option always "match reference X" if a ref exists): - **Instant** — everything visible at first paint, no entrance. - **Hero-first** — hero content fades in over `--dur-slow`, everything else waits until fully loaded then reveals on scroll. - **Staggered cascade** — top-to-bottom stagger with `--dur-base` per element, `stagger-base-ms` between. Ask: `stagger-base-ms` value (30 / 60 / 120 ms). Default 60. ### Section 2. Scroll-driven Behavior as user scrolls: reveal, parallax, pinning, sticky headers. Reference read: `references/motion/` scroll captures, `references/animation/` scroll notes. Ask 4 sub-questions: 1. **Reveal on scroll?** none / fade / fade+slide-up (16px) / fade+scale (0.98→1). Default: fade+slide-up if any ref shows reveal, else none. 2. **Parallax?** yes/no. Only allow yes if a ref explicitly shows parallax AND the mood is not "quiet luxury" (conflict from `/refs`). If enabled, ask depth: subtle (5%) / moderate (12%) / strong (25%). 3. **Sticky section headers?** yes/no. Default no (only enable if a ref shows it). 4. **Pinning (section stays while content animates over it)?** yes/no. Default no. If yes, warn: high complexity, mobile-safety flag. ### Section 3. Text animations Reveal treatment for headlines, quotes, and body copy. Reference read: `references/typography/` motion notes if any, `references/animation/` text captures. Options: - **None** — text appears with parent block, no separate animation. - **Whole-block fade** — heading fades with its section. - **Word-by-word stagger** — each word fades in with `stagger-base-ms/2` offset. - **Line-by-line stagger** — each rendered line fades in (needs a split-lines JS helper). Apply per element: `h1` / `h2` / `h3` / `p` / `blockquote` — user chooses which get animated. **Constraint reminder:** text animations must respect the print-typography rules from `/typography`. Do not animate individual short words (`the`, `and`) separately — they animate with the word they are tied to via ` `. ### Section 4. Block animations Interactive states for cards, images, buttons. Ask 5 sub-questions with defaults matching the mood: 1. **Card hover:** none / lift (translateY -4px) / scale (1.02) / border-glow / image-zoom. Duration: `--dur-fast`. 2. **Image hover:** none / zoom (scale 1.05) / caption-reveal / desaturate-to-color. Duration: `--dur-base`. 3. **Button press:** none / scale (0.98) / darken (background shift). Duration: `--dur-fast`. 4. **Button hover:** underline-grow / bg-fill / arrow-slide / none. 5. **Link hover:** underline / color-shift / both. ### Section 5. Micro-interactions Form focus, error states, cursor. Ask: 1. **Input focus:** border-color shift / border-thickness / label-float / underline-grow. Default: border-color shift. 2. **Input error:** border-red-flash (200ms) / shake (2 iterations, `--dur-fast`) / border-red-static. 3. **Form success:** button-morphs-into-checkmark / thank-you-slide-in / redirect-to-page. 4. **Custom cursor?** yes/no. Default no unless the mood is editorial+experimental. If yes, ask: dot / circle / cross / crosshair, and: mixed-blend-mode difference or plain. 5. **Cookie banner / toast entrance:** slide-up (bottom) / slide-down (top) / fade / none. ### Section 6. Motion intensity Global multiplier that adjusts durations everywhere. - **subtle** (multiplier 0.75) — high-end brand, quiet luxury moods. - **balanced** (multiplier 1.0) — default. - **lively** (multiplier 1.25) — consumer product, playful moods. - **dramatic** (multiplier 1.5) — editorial, cinematic moods. Default based on `brief/05-design.md` mood. Show the calculated final `--dur-base`, `--dur-fast`, `--dur-slow` values after the pick. ## Output **Write `brief/animation.md`** with all decisions, structured for `/build` consumption: ```markdown # Animation spec STATUS: LOCKED Generated: ## 1. Page-load choreography: stagger-base-ms: ## 2. Scroll reveal: parallax: sticky-headers: pinning: ## 3. Text h1: h2: p: blockquote: ## 4. Blocks card-hover: image-hover: button-press: button-hover: link-hover: ## 5. Micro input-focus: input-error: form-success: custom-cursor: toast-entrance: ## 6. Intensity level: multiplier: final-dur-base-ms: final-dur-fast-ms: final-dur-slow-ms: ``` **Append to `DESIGN-LOCK.md` §5:** three new lines under Motion: ``` Scroll-behavior: Text-animation: Stagger-base-ms: Motion-intensity: ``` Update `DESIGN-LOCK.md` §5 STATUS to LOCKED if not already, and log a decision entry in `DESIGN.md`. **Append to `references/approved-manifest.md`** (see /refs for manifest format): every non-`none` / non-`off` decision becomes a required element: ``` [ ] animation:card-hover:lift [ ] animation:text:h1:word-stagger [ ] animation:scroll:fade-slide ``` `/build` will confirm each required animation is present in the generated CSS/JS. ## Reference priority **Rule:** if the user has references, present "match reference X" as option A of every question. Only offer generic alternatives as B/C/D. The user's brand is the anchor. If a reference conflicts with `/refs` proposal or DESIGN-LOCK values, flag it and ask the user which side wins. ## Rules of behavior - **One question, one screen.** Do not batch six pickers. - **Show trade-offs.** For each option, one sentence on cost (bundle size, mobile-safety, complexity). - **Never accept "whatever".** Push for a specific choice — even if it's `none`. - **Respect `/mobile` constraints.** Parallax and pinning have known mobile issues; surface those warnings when the user picks them. ## What NOT to do - Do not invent motion tokens outside DESIGN-LOCK §5. Duration and ease come from there. - Do not enable heavy scroll effects on mobile-first projects unless explicitly overridden. - Do not skip sections silently. Every section produces a value. - Do not touch the copy — animations are added around text, not replacing it. ## Next - `/tokens` — will write motion tokens (`--stagger-base-ms`, `--motion-multiplier`, computed durations) into `tokens.css`. - `/build` — reads `brief/animation.md` and generates matching CSS classes per section; checks each item in the approved-manifest. - `/audit` — verifies every manifest item was applied.