git:20260908.dae2c1e to git:20260908.71eff1e

- ## How these greps are run

-

- **Define these two helpers first, in the same Bash call as the greps below.**

-

- Every grep in this file used to end in `src/`. A default Next.js app-router or Nuxt 3

- project has no `src/` at all, so those greps matched nothing, and the pipeline read

- "no findings" as a passing gate immediately before delivery. The audit reported a clean

- bill of health on code it had never read.

-

- ```bash

- # Recursion, root and noise directories in one place. The root is the project, not a

- # guessed subdirectory; --include already narrows by file type and the excludes carry

- # the rest. Note the arguments are passed as "$@", never through an unquoted variable:

- # zsh does not word-split those, so the usual $SRC / $EXCL trick silently collapses

- # into a single bogus argument.

- gj() {

- grep -rn \

- --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next \

- --exclude-dir=.nuxt --exclude-dir=.output --exclude-dir=.svelte-kit \

- --exclude-dir=.astro --exclude-dir=dist --exclude-dir=build --exclude-dir=out \

- --exclude-dir=coverage --exclude-dir=vendor --exclude-dir=.venv \

- "$@" .

- }

-

- # Same, for the inventory greps: -h drops the filename and -o prints only the match,

- # so the output can be counted.

- gjo() {

- grep -rhoE \

- --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=.next \

- --exclude-dir=.nuxt --exclude-dir=.output --exclude-dir=.svelte-kit \

- --exclude-dir=.astro --exclude-dir=dist --exclude-dir=build --exclude-dir=out \

- --exclude-dir=coverage --exclude-dir=vendor --exclude-dir=.venv \

- "$@" .

- }

- ```

-

- If the project is a monorepo and the scan is too broad, narrow it by appending a path:

- `gj ':hover' --include='*.css' packages/web` works, because the trailing `.` is only a

- default and grep accepts several roots.

-

- ---

-

- ## Motion Gap Analysis

-

- Run these greps against the project to detect missing animations. Single-file component

- formats (`.vue`, `.svelte`, `.astro`) carry their styles inline, so they are included

- wherever a CSS or JSX pattern is being looked for.

-

- ### Conditional renders without AnimatePresence

-

- ```bash

- gj '{.*&&\s*<\|{.*?\s*:\s*<\|{.*ternary.*<' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -v 'AnimatePresence'

- ```

-

- Look for: `{show && <Component />}` or ternary renders without a wrapping `<AnimatePresence>`. Every conditional mount/unmount needs exit animation support.

-

- ### Hover states without transition

-

- ```bash

- gj ':hover' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.css' --include='*.scss' --include='*.module.css' | grep -vE 'transition|animation'

- ```

-

- Every `:hover` rule must have a corresponding `transition` on the base selector. Instant state flips feel broken.

-

- ### Dynamic lists without stagger

-

- ```bash

- gj '\.map(' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -vE 'stagger|delay.*index|variants|transition.*delay'

- ```

-

- Lists rendered via `.map()` should stagger their entrance. Simultaneous pop-in looks cheap.

-

- ### Style changes without transition

-

- ```bash

- gj 'style={{' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -vE 'transition|transform|opacity'

- ```

-

- Inline style changes (e.g., dynamic background, color) need a CSS transition or motion wrapper.

-

- ### Entries without corresponding exits

-

- ```bash

- gj 'initial=' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -v 'exit='

- ```

-

- Every Framer Motion `initial` + `animate` should have an `exit` prop when inside `AnimatePresence`.

-

- ---

-

- ## Accessibility Audit

-

- ### Reduced motion - MANDATORY

-

- A project with animation MUST have at least one global handler matching its stack. Run all 3 greps:

-

- ```bash

- # Web

- gj 'prefers-reduced-motion' --include='*.css' --include='*.scss' --include='*.ts' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.js' --include='*.jsx' 2>/dev/null

-

- # SwiftUI / UIKit

- grep -rn 'accessibilityReduceMotion\|isReduceMotionEnabled\|reduceMotionStatusDidChangeNotification' --include='*.swift' . 2>/dev/null

-

- # Compose

- grep -rn 'LocalAccessibilityManager\|isReduceTransitions\|TRANSITION_ANIMATION_SCALE\|ANIMATOR_DURATION_SCALE\|areAnimatorsEnabled' --include='*.kt' . 2>/dev/null

- ```

-

- **Zero results across all 3 in an animated project = critical violation.** At least one handler must exist somewhere. Cross-reference `motion-principles/SKILL.md` for canonical implementations per stack.

-

- ### Contrast ratio 4.5:1

-

- - Use browser DevTools (Inspect > color swatch > contrast ratio)

- - Run `npx pa11y <url>` or Lighthouse accessibility audit

- - Check animated text at mid-transition -- fading text must remain readable at every opacity above 0.4

-

- ### Focus visible on all interactives

-

- ```bash

- gj 'outline:\s*none\|outline:\s*0' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.css' --include='*.scss' --include='*.module.css'

- ```

-

- Any `outline: none` MUST be paired with a custom `:focus-visible` style. Removing focus rings without replacement is a WCAG failure.

-

- ### Semantic HTML -- no clickable divs

-

- ```bash

- gj 'onClick' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -E '<div|<span' | grep -v 'role='

- ```

-

- Every `<div onClick>` or `<span onClick>` must either be a `<button>`, an `<a>`, or have `role="button"` + `tabIndex` + `onKeyDown`.

-

- ### ARIA on decorative animations

-

- ```bash

- gj '<motion\.\|<animated\.\|<Lottie\|<Canvas' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' | grep -v 'aria-hidden'

- ```

-

- Purely decorative animations (background particles, ambient motion, Lottie illustrations) must have `aria-hidden="true"` to avoid polluting screen readers.

-

- ---

-

- ## Performance Audit

-

- ### Layout thrashing -- animating layout properties

-

- ```bash

- gj 'transition.*\(width\|height\|top\|left\|right\|bottom\|margin\|padding\)' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.css' --include='*.scss' --include='*.module.css'

- ```

-

- Animating layout properties triggers reflow every frame. Replace with `transform: translate/scale` and `opacity`.

-

- ### Excessive paint triggers

-

- ```bash

- gj 'will-change' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.css' --include='*.scss' --include='*.module.css'

- ```

-

- `will-change` should be rare and scoped. If more than ~5 elements use it permanently, the GPU memory cost outweighs the benefit. Apply it dynamically (add on hover/focus, remove on animation end).

-

- ### Animation library bundle cost

- Check actual impact:

- npx source-map-explorer dist/**/*.js 2>/dev/null || npx vite-bundle-visualizer 2>/dev/null

- Reference sizes (gzipped): framer-motion ~30KB, GSAP ~25KB, popmotion ~5KB, CSS-only = 0KB. If the project only uses fade+slide, a 30KB lib is overkill.

-

- On mobile native, the APK / IPA size matters. A third-party animation library adds typically 500KB-2MB:

- | Library | Size impact (uncompressed) |

- |---|---|

- | Lottie (iOS) | ~600KB |

- | Lottie (Android) | ~900KB |

- | Rive (iOS) | ~1.5MB |

- | Rive (Android) | ~2MB |

- | Native Compose / SwiftUI animations | 0KB (built-in) |

- If the project only uses fades, slides, and springs, native APIs (Compose `animate*AsState` + spring, SwiftUI `withAnimation`) are sufficient. Justify a Lottie / Rive dependency only for genuinely complex pre-designed animations (e.g., onboarding illustrations).

- ### requestAnimationFrame vs setTimeout

- ```bash

- gj 'setTimeout\|setInterval' --include='*.ts' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.js' --include='*.jsx' | grep -iE 'anim\|motion\|scroll\|position\|style\|transform'

- ```

- Animation loops must use `requestAnimationFrame`. `setTimeout`/`setInterval` causes frame drops and doesn't pause in background tabs.

- ## Consistency Audit

-

- ### Duration consistency

-

- ```bash

- gjo 'duration[:"'\''= ]+[0-9.]+' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.css' --include='*.scss' \

- | sed -E 's/^duration[:"'\''= ]+//' | tr -d ' ' | sort -n | uniq -c | sort -rn

- ```

-

- A well-designed project uses 3-5 distinct durations max (e.g., 0.15, 0.25, 0.35, 0.5). If you see 15 different values, extract them into a motion tokens file.

-

- ### Easing inventory

-

- Run all 3 greps to inventory easing values across the codebase:

-

- ```bash

- # Web (CSS / JS / TSX)

- gjo 'ease[A-Za-z]*|cubic-bezier\([^)]+\)|spring\([^)]*\)' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx' --include='*.ts' --include='*.css' --include='*.scss' 2>/dev/null

-

- # SwiftUI

- grep -rnoE '\.spring\([^)]*\)|\.snappy|\.bouncy|\.smooth|\.linear\(|\.easeIn|\.easeOut|\.interpolatingSpring' --include='*.swift' . 2>/dev/null

-

- # Compose

- grep -rnoE 'spring\([^)]*\)|tween\([^)]*\)|FastOutSlowInEasing|LinearOutSlowInEasing|FastOutLinearInEasing|CubicBezierEasing' --include='*.kt' . 2>/dev/null

- ```

-

- Same rule across all stacks: 3-5 named easings max in the design system. Random values scattered across files = visual inconsistency. If the codebase has 12 different `cubic-bezier(...)` values or 8 custom `spring(response:dampingFraction:)` configurations, that's a design-system violation, fix it by centralizing into named tokens.

-

- ### Symmetric enter/exit

-

- Scan for motion components and verify that:

- - Enter duration >= exit duration (never the reverse)

- - Enter uses `ease-out`, exit uses `ease-in`

- - Enter has full choreography (translate + opacity + scale), exit is simpler (opacity only or opacity + slight scale)

-

- ```bash

- gj -A5 'exit=' --include='*.vue' --include='*.svelte' --include='*.astro' --include='*.tsx' --include='*.jsx'

- ```

-

- Compare `animate` and `exit` props side by side. Asymmetric timing (fast exit, slow enter) is correct. The reverse is wrong.

-

- ---