---
name: css-animation-assistant
description: Specialized assistant for implementing CSS animations in the DWP Hours Tracker frontend, ensuring compliance with performance, accessibility, and maintainability standards.
title: css-animation-assistant
canonical_url: https://skilld.dev/gh/corey-alix/dwp-hours/css-animation-assistant
last_updated: 2026-10-07T01:30:59.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install corey-alix/dwp-hours/css-animation-assistant`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/css-animation-assistant`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/corey-alix/dwp-hours/css-animation-assistant) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/css-animation-assistant`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/css-animation-assistant --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/css-animation-assistant --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# CSS Animation Assistant

## Description

Specialized assistant for implementing CSS animations in the DWP Hours Tracker frontend, ensuring compliance with performance, accessibility, and maintainability standards. This skill guides the creation of efficient, hardware-accelerated animations that enhance user experience without introducing technical debt.

## Trigger

Activate this skill when users request:

- Creating new CSS animations or transitions
- Optimizing existing animations for performance
- Implementing accessibility-compliant animations
- Adding mobile-specific animation features
- Reviewing or refactoring animation code

## Response Pattern

Follow this step-by-step approach when implementing CSS animations:

1. **Assess Requirements**: Analyze the animation purpose, target elements, and user interaction context
2. **Property Selection**: Ensure only hardware-accelerated properties (`transform`, `opacity`, `filter`) are animated
3. **Performance Optimization**: Apply `will-change` strategically and use GPU acceleration techniques
4. **Accessibility Implementation**: Add `prefers-reduced-motion` support and ARIA attributes as needed
5. **Mobile Considerations**: Optimize for touch inputs and reduce complexity on mobile devices
6. **Code Structure**: Use CSS variables, modular keyframes, and utility classes for maintainability
7. **Testing & Validation**: Test across devices, validate with performance tools, and ensure graceful degradation
8. **Documentation**: Add code comments explaining animation purpose, performance impact, and accessibility features

## Lessons Learned

Hard-won patterns from real implementations in this project:

### Multi-phase animations (carousel, slide-in/out)

- **Use inline styles, not CSS classes** for sequenced animation phases. Class-based approaches suffer from specificity conflicts and unreliable style flushing between phases.
- **Force synchronous reflow** with `void element.offsetHeight` between phases to guarantee the browser commits an intermediate position before re-enabling transitions. Double `requestAnimationFrame` is not reliable for this.
- **Filter `transitionend` by `e.propertyName`** (e.g., `=== "transform"`) to prevent double-firing when animating multiple properties (`transform` + `opacity`).
- **Guard against overlapping animations** with an `isAnimating` flag checked at entry and cleared on completion.
- **Always add a `setTimeout` fallback** after the animation duration (+50ms buffer) that runs the same completion logic as `transitionend`. The `transitionend` event will not fire if the element is destroyed mid-animation (e.g., by a re-render) or in test environments without CSS transition support. Without a fallback, `isAnimating` gets stuck `true` and the component deadlocks.
- **Allow re-toggle during animation** — instead of `if (isAnimating) return`, call a `finalizeAnimation()` helper that clears the fallback timer, removes inline styles, and resets the flag, then proceed with the new action. This prevents the component from becoming unresponsive to rapid user clicks.
- **Deduplicate completion logic** — extract a single `onComplete` closure shared by both the `transitionend` handler and the `setTimeout` fallback. Have it clear the timer, remove the event listener, clean up styles, and reset state, so the first to fire wins and the second is a no-op.
- **Clean up inline styles** after animation completes — remove `willChange`, `transition`, `transform`, and `opacity` to avoid stale state.

### Menu and dropdown animations

- **Prefer slide (motion) over fade for menu reveal/hide**. Slide-down (`translateY`) provides stronger spatial context than opacity transitions alone. Combine with a subtle opacity change for polish, but the motion must be the primary effect.
- **Use `translateY(-8px)` as the hidden position** for dropdown menus — small enough to feel natural, large enough to be perceptible.
- **Decelerate on open, accelerate on close** — use a decelerate easing (`cubic-bezier(0, 0, 0.2, 1)`) when revealing and an accelerate easing (`cubic-bezier(0.4, 0, 1, 1)`) when hiding, so elements feel like they arrive gently and leave quickly.

### Accessibility

- **Always provide a `prefersReducedMotion()` check** that skips animation entirely (instant state change) rather than just shortening duration.
- Query `window.matchMedia("(prefers-reduced-motion: reduce)")` at animation time, not at component init, so runtime preference changes are respected.

### innerHTML re-render destroys scroll context on mobile

- **Never call `requestUpdate()` on a parent component to enter/exit edit mode** when an animated child component handles its own card→editor transition. The parent's `renderTemplate()` replaces its entire shadow DOM via `innerHTML`, which destroys the child element (and its scroll position). On mobile single-column layouts the page height briefly collapses to near-zero, causing the browser to clamp `window.scrollY` to 0. By the time the child is recreated and populated, the user is staring at the top of the page.
- **Set properties directly on the existing child element** instead of re-rendering the parent. For example, set `list.editingEmployeeId = id` on the live `<employee-list>` rather than calling `this.requestUpdate()` on `<admin-employees-page>`. The child's `attributeChangedCallback` then runs `transitionCardToEditor()` with the DOM intact and scroll preserved.
- **The actual scroll container matters** — `.employee-grid` has `overflow-y: auto` and `flex: 1`, but its parent chain doesn't establish a fixed-height constraint, so `scrollHeight === clientHeight` (it's never scrollable). The real scroll container is `window`. Always use `window.scrollBy()` and `getBoundingClientRect()` for position correction, never `grid.scrollTop`.
- **Use `getBoundingClientRect().top` before and after re-render** to calculate drift. After the synchronous `requestUpdate()` (innerHTML replacement), read the editor's `getBoundingClientRect().top` — this forces a layout before the browser paints, making the `window.scrollBy(0, drift)` correction invisible to the user. Measured drift is <1px.
- **Cancel and form-cancel handlers need the same treatment** — when exiting inline edit mode, clear `editingEmployeeId` on the existing child component rather than re-rendering the parent. Distinguish between "was inline editing" vs "was showing add form" to decide whether a parent re-render is needed.

### Touch swipe isolation on mobile (Android Chrome)

Touch-driven swipe navigation (e.g., swiping a calendar to change months) must not drag the page. The solution depends on the component's scroll context.

- **Prefer CSS `touch-action: pan-y`** on the swipe container. This tells the browser to handle vertical panning natively (page scrolls normally) and leave horizontal gestures to JavaScript. It's declarative, zero-runtime-cost, and works reliably on Android Chrome hardware — no `touchmove` handler needed.
- **Do NOT combine `overscroll-behavior: contain` with `overflow: hidden`**. On an element that has no scrollable content, `overscroll-behavior: contain` tells the browser "this element is at its scroll boundary, don't chain to the parent." On real Android Chrome hardware, this kills vertical page scrolling entirely when touching the element. Chrome DevTools device emulation does not reproduce this — always test on real hardware.
- **The `touchmove` + `preventDefault()` approach is a power tool, not a default.** Registering a non-passive `touchmove` handler to call `preventDefault()` during horizontal swipes works but forces Chrome to block all native scrolling until the JS handler runs and determines gesture direction. This adds input latency and temporarily freezes vertical scrolling. Make it opt-in via a `preventPageScroll` option (see `SwipeNavigationOptions`), and document that CSS `touch-action: pan-y` is the preferred alternative.
- **Swipe detection needs only `touchstart` + `touchend`** for direction and threshold. The `setupSwipeNavigation` helper records start coordinates on `touchstart`, computes delta on `touchend`, and fires the navigation callback if horizontal distance exceeds the threshold and dominates vertical distance. No `touchmove` tracking needed for the core gesture.
- **Grid `minmax()` can overflow narrow viewports.** A grid like `repeat(auto-fill, minmax(40ch, 1fr))` can push cards past the right edge on a Pixel 7 (412 CSS px). Use `minmax(min(40ch, 100%), 1fr)` to cap the minimum at the container width.
- **DevTools emulation ≠ real device.** Touch event handling, DPR subpixel rounding, and overscroll chaining all behave differently on real Android Chrome. Always validate touch interactions on hardware via `chrome://inspect` remote debugging.

## Examples

Common user queries that should trigger this skill:

- "Add a fade-in animation to the PTO calendar"
- "Optimize the loading spinner animation for better performance"
- "Make the employee form slide in smoothly"
- "Ensure animations work with reduced motion preferences"
- "Create a swipe gesture animation for mobile"

## Additional Context

This skill integrates with the project's CSS Animation Policy and web components architecture. All animations must align with the atomic CSS design principles and use tokens from `tokens.css` for durations and easings. Reference the project's `css.ts` pattern for component-specific styles and ensure animations are tested in both Vitest (unit) and Playwright (E2E) environments.
