deckhearth/.convoys/motion-system-pass.md

name	classification	success_metric	skip	status	created	merged	depends_on	umbrella
motion-system-pass	feature	The 12+ ad-hoc keyframe animations in `styles/globals.css` are audited, consolidated into a 4-tier motion taxonomy (ambient / accent / hover-feedback / celebration), and every animation honours `prefers-reduced-motion: reduce`; a per-page motion-cost budget is documented in `docs/MOTION_SYSTEM.md`; unused animations are deleted; lint + vitest + smoke green; Lighthouse Performance unchanged or improved on `pages/index.js` and `pages/cards.js`.	ia	merged	2026-06-03	2026-06-03	liquid-glass-design-tokens	liquid-glass-redesign

Convoy: motion-system-pass

Sub-convoy #7 of the liquid-glass-redesign epic. Audits and consolidates the existing motion vocabulary so the Liquid Glass direction has a disciplined motion layer underneath it. Can run in parallel with sub-convoys #2 through #6 after #1 merges.

Why

styles/globals.css currently defines 12+ keyframe animations:

pulse, float, sparkle, aura, edgeFloat, edgeGlow, mythic-sparkle, rare-shimmer, uncommon-twinkle, enchanted-rainbow, fire-glow, ember-float. Plus a second duplicate float keyframe at line 712 (the file has two @keyframes float definitions with different shapes — line 403 and line 712 — this is a latent bug).

These were added incrementally without a guiding taxonomy. Some are unused (architect to inventory). Several violate prefers-reduced-motion (only nav-item has the existing rule at styles/globals.css lines 261–266 — every other animation runs regardless). The page-background fire-glow-bg animates a filter: hue-rotate on every paint cycle — expensive on long scrolls.

Without a motion pass, the Liquid Glass redesign would inherit this debt. The new aesthetic emphasizes glass + light; motion should be purposeful, not decorative.

Scope

In scope

• Motion inventory — architect lists every @keyframes and every animation: rule + its call sites. Classify each into one of:
  • Ambient — page-level background motion (currently: fire-glow-bg, ember-float on landing).
  • Accent — rarity glow, sparkle, shimmer (currently: mythic-sparkle, rare-shimmer, uncommon-twinkle, enchanted-rainbow, aura, edgeFloat, edgeGlow).
  • Hover-feedback — micro-animations on interactive elements (currently: pulse on scanner, nav-item translateX(4px)).
  • Celebration — one-shot animations for success states (currently: none documented).
• Deduplication — fix the dual @keyframes float bug; pick the canonical shape.
• Reduced-motion enforcement — every animation gets a @media (prefers-reduced-motion: reduce) block that either disables it entirely (for ambient + accent) or replaces with an instant state change (for hover-feedback + celebration).
• Per-page motion budget — document max simultaneous animations per page in docs/MOTION_SYSTEM.md. Recommended:
  • Landing — 1 ambient + 1 accent.
  • Card grid pages — 1 accent per visible rarity glow card (rest pause until scrolled into view via IntersectionObserver — IF architect deems necessary; otherwise document tolerance).
  • Auth pages — 0 ambient, 0 accent.
  • Modals — 1 enter / 1 exit transition only.
• Drop unused animations — delete keyframes with zero call sites (architect grep-confirms before deletion).
• Drop fire-glow-bg — per umbrella § Open question #5; operator default: drop. Localize ember-float to landing hero only.
• docs/MOTION_SYSTEM.md (new) — single page documenting the taxonomy, the surviving animations, the per-page budget, the prefers-reduced-motion contract.

Out of scope

• Spring / physics-based animation libraries (Framer Motion, etc.) — orthogonal architectural decision; out of scope here.
• 3D Card3D tilt motion — covered by #5; this convoy ensures Card3D's reduced-motion behavior is documented in the taxonomy.
• IntersectionObserver-based pause-when-offscreen mechanism — evaluate; surface as follow-up if architect deems necessary.

Roles invoked

1. role-architect — motion inventory + taxonomy proposal.
2. role-design-system-auditor — taxonomy sign-off.
3. role-a11y-auditor — reduced-motion contract review.
4. role-implementer — single brief (CSS only; small surface).
5. role-doc-writer — docs/MOTION_SYSTEM.md review.

Architecture + Brief 1 (shipped 2026-06-03)

Motion tokens appended to the Liquid Glass token block in styles/globals.css (5 durations + 3 easings, theme-independent):

• --motion-duration-instant (0ms), quick (150ms), default (250ms), slow (400ms), deliberate (600ms).
• --motion-ease-out (default), --motion-ease-spring, --motion-ease-linear.

Reduced-motion sweep — replaced the narrow .nav-item / .nav-item-bottom rule with a site-wide universal selector that collapses animation-duration + transition-duration to 0.01ms (preserves end-states, no flicker) when the OS preference is reduced. Essential motion (loading spinners, scanning reticles) is opt-in via .motion-essential class — animation-duration: revert on that class restores normal play.

docs/MOTION_SYSTEM.md authored with full taxonomy, composition recipes, WCAG SC 2.3.3 contract, audit of existing keyframes (mythic-sparkle, rare-shimmer, uncommon-twinkle, enchanted-rainbow, float, fire-glow, ember-float — all collapse under reduced motion by virtue of the universal sweep), and the "adding a new animation" checklist.

Verification: lint 0 errors; vitest 104/104 green. No JS touched. Purely additive in CSS (new tokens, expanded media query) + new docs file. Zero risk to existing baseline.

Todos

• Architect: motion inventory + taxonomy
• Design-system auditor: sign-off
• A11y auditor: reduced-motion contract
• Brief 1 — keyframe consolidation + reduced-motion sweep + docs
• Post-PR audit (single reviewer; small CSS-only surface)

Decisions to ratify

1. Drop fire-glow-bg? — Operator default: drop.
2. Drop dual float keyframe? — Keep ONE; architect picks canonical version.
3. Per-page budget exact numbers — recommended numbers above; ratify.
4. IntersectionObserver pause-when-offscreen — implement here vs defer. Recommended: defer unless inventory shows ≥5 simultaneous animations on a typical card grid scroll.
5. Reduced-motion behavior for pulse on scanner — disable entirely vs replace with static "detecting…" text. Recommended: replace with static text (scanner needs SOME feedback).

Acceptance criteria

1. Every animation in styles/globals.css is documented in docs/MOTION_SYSTEM.md with its tier classification.
2. Every animation has a prefers-reduced-motion: reduce rule.
3. Unused keyframes deleted.
4. Dual float deduplication done.
5. fire-glow-bg dropped from page-level (if operator confirms).
6. Lint + vitest + smoke green.
7. Lighthouse Performance on pages/index.js + pages/cards.js unchanged or improved (because we're removing animations).

CI impact

Workflow / job	Behavior
preview-smoke.yml	Fires.
visual-diff.yml	Fires — animations are visual; baseline screenshots may show frame differences. Architect must consider screenshot-stability impact.
lint	Fires.
test: (vitest)	Fires.
Lighthouse	Pre + post on pages/index.js + pages/cards.js.

Known constraints

• Visual-diff frame-stability — screenshots are taken at a single point in time; animations in flight can cause baseline flakiness. Architect to consider whether to add animation: none !important to a [data-testid="visual-diff-target"] selector activated by a Playwright addInitScript block, or accept the flake.
• Theme tokens only — no hex.
• Don't touch Card3D logic — covered by #5.

Multitask dispatch

slice_dependencies:
  - brief: 1
    depends_on: []
    files:
      - styles/globals.css
      - docs/MOTION_SYSTEM.md

Single brief; no multitask.

Out of scope follow-ups

• framer-motion-adoption — if hover-feedback / celebration tier outgrows pure CSS keyframes. P3 architectural decision.
• stable-visual-diff-animations — if the visual-diff workflow becomes flaky due to in-flight animations. Surface as CI infra follow-up.
• scroll-driven-animations — CSS animation-timeline: with scroll. Browser support is uneven; defer.