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:

# Animation spec
STATUS: LOCKED
Generated: <date>

## 1. Page-load
choreography: <instant|hero-first|staggered-cascade>
stagger-base-ms: <value>

## 2. Scroll
reveal: <none|fade|fade-slide|fade-scale>
parallax: <off|subtle|moderate|strong>
sticky-headers: <yes|no>
pinning: <yes|no>

## 3. Text
h1: <animation>
h2: <animation>
p: <animation>
blockquote: <animation>

## 4. Blocks
card-hover: <value>
image-hover: <value>
button-press: <value>
button-hover: <value>
link-hover: <value>

## 5. Micro
input-focus: <value>
input-error: <value>
form-success: <value>
custom-cursor: <spec|off>
toast-entrance: <value>

## 6. Intensity
level: <subtle|balanced|lively|dramatic>
multiplier: <numeric>
final-dur-base-ms: <computed>
final-dur-fast-ms: <computed>
final-dur-slow-ms: <computed>

Append to DESIGN-LOCK.md §5: three new lines under Motion:

Scroll-behavior:      <reveal type>
Text-animation:       <text style>
Stagger-base-ms:      <value>
Motion-intensity:     <level (multiplier)>

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.