Motion Audit Skill (SKILL.md)

What this is

A ready-to-paste SKILL.md that audits every animation, transition, or transform in a generated file against the 5-level motion framework from the Motion Decision Tree.

Invoke /motion-audit and Claude rates every motion by level, flags violations, and fixes them inline.

How to install

Step 1: Create the skill folder

mkdir -p ~/.claude/skills/motion-audit

Step 2: Paste the file below as SKILL.md

touch ~/.claude/skills/motion-audit/SKILL.md

Step 3: Invoke it

After any generation with interactive elements, type:

/motion-audit

---

The full SKILL.md

---
name: motion-audit
description: Audit the most recent generation against the 5-level motion system.
  Classifies every animation by level, flags violations, and fixes them inline.
  Use after Claude generates any page, component, or section with interaction.
---

## The 5 motion levels

| Level | Name | Job |
|-------|------|-----|
| 0 | None | Clarity is enough |
| 1 | Micro-motion | Interactive feedback (hover, press, focus) |
| 2 | Scroll reveal | Pacing long narrative pages |
| 3 | Scroll-linked illusion | One cinematic moment per page |
| 4 | Real-time 3D | User control is the value |

Default level: 0. Promote only when a specific job requires it.

## How to audit

Read the most recently generated or edited file. Find every:

- CSS transition
- CSS animation / @keyframes
- Transform (scale, rotate, translate, skew)
- JS animation library call (Framer Motion, GSAP, Motion One, anime.js)
- Scroll-based trigger (Intersection Observer, scroll listeners, scrub)
- Video autoplay or scroll-driven playback

For each one:

1. **Name the motion**. Example: "fade-up on scroll", "scale(1.05) on hover".
2. **Classify it by level (0–4)**.
3. **Check it against the approved patterns for that level**.
4. **Flag the violation if present**.
5. **Propose and apply the fix inline**.

## Approved patterns by level

### Level 0: None
No motion. No transitions. No transforms on content elements.

### Level 1: Micro-motion (approved only)
- opacity: 1 → 0.7 on hover, 150ms ease-out
- translateY(0) → translateY(-1px) on hover, 150ms ease-out
- underline reveal on link hover, 150ms
- scale(1) → scale(0.98) on button press, 100ms ease-out
- color or background-color on focus, 200ms

### Level 2: Scroll reveal (approved only)
- opacity: 0 → 1, translateY(16px) → translateY(0), 500ms ease-out
- Trigger at 50% viewport intersection
- Stagger: max 3 items, 80ms between
- Once only, never loop or repeat

### Level 3: Scroll-linked illusion (approved only)
- Video scrub tied to scroll position
- Frame sequence tied to scroll position
- Sticky section with changing inner content
- Must have static poster fallback
- Under 2MB video assets (1MB mobile)

### Level 4: Real-time 3D (approved only)
- User can rotate, inspect, or configure
- 2D fallback for mobile and prefers-reduced-motion
- 60fps performance budget on mid-range devices

## Specifically flag these violations

- Scroll-triggered animations on hero content
- Scroll-triggered animations on body paragraphs
- scale() values above 1.02 on hover
- rotate() or skew() on hover
- Bouncy, elastic, or cubic-bezier(0.68, -0.55, ...) easing
- Animation durations above 600ms
- More than 3 items in a stagger sequence
- Multiple Level 3 moments on the same page
- Level 4 used for decoration instead of user control
- Parallax backgrounds
- Blur-to-focus entrance animations
- Auto-playing hero videos without scroll-binding
- Animations that do not respect prefers-reduced-motion

## Output format

For each violation found:

- **VIOLATION**: [motion name]
- **CURRENT LEVEL**: [detected level]
- **SHOULD BE**: [correct level, usually one lower]
- **WHERE**: [file + line or component]
- **FIX**: [specific code change]
- **APPLIED**: [Yes / Needs manual review]

## Final report

After all fixes:

Motion audit summary:

• Total motions reviewed: [N]
• Violations found: [N]
• Violations fixed inline: [N]
• Violations flagged for designer: [N]
• Final motion budget: [count per level]

Then print the approved motion inventory for the page:

Level 0: [count of static elements] Level 1: [list of micro-motion uses] Level 2: [list of scroll reveals, if any] Level 3: [list of scroll-linked moments, max 1] Level 4: [list of 3D experiences, rare]

## Never do

- Do not suggest "add an animation" as a fix.
- Do not replace a violation with a different violation (e.g. downgrading from
  "scale(1.1)" to "rotate(2deg)" instead of removing it).
- Do not recommend scroll reveal on hero content. Hero is always Level 0.
- Do not recommend motion for dashboards, pricing tables, or documentation
  without an explicit project rule allowing it.

## If prefers-reduced-motion is not handled

If the file does not wrap motion in `@media (prefers-reduced-motion: reduce)` or
does not check the `prefers-reduced-motion` media query in JS, flag it as a
separate accessibility violation and fix it.

---

How to customize

For marketing sites with heavy motion

Add a project CLAUDE.md that extends Level 2 with additional approved patterns. The skill reads your project rules first.

For documentation or dashboards

Tighten the skill to Level 0 only. Add this line to the “Never do” section:

- On any page under /docs or /dashboard, reject any motion above Level 1.

For motion-heavy brand pages

Permit Level 3 in specific folders. Add to the “Approved patterns” section:

- Level 3 is permitted on /campaign pages and /product-launch pages.
- All other pages: Level 0–2 only.

Pairs with

• The Motion Decision Tree guide (the full framework)
• The AI Anti-Patterns Gallery (pattern 5 covers motion spam)
• The Taste Skill Starter (your personal taste skill)