stolinski/s-stack/css-motion-systems

CSS Motion Systems

Overview

This skill provides a production-oriented motion system for web UI work. It is focused on interaction clarity, performance, and accessibility, not decorative animation.

Use this skill to design and implement motion that:

• Preserves spatial continuity between states
• Communicates hierarchy and focus
• Uses performant properties (transform, opacity)
• Provides reduced-motion alternatives
• Uses View Transitions API intentionally for page/state continuity

When to Use

• Building or refining interaction motion in product UI
• Choosing between CSS transition, keyframes, WAAPI, and View Transitions API
• Creating route transitions or list/detail shared element transitions
• Defining motion tokens (duration, distance, easing) for a design system
• Reviewing motion quality, performance, and accessibility

When NOT to Use

• Static content with no interaction/state change
• Cases where motion increases cognitive load without adding clarity
• Situations requiring immediate state updates where any delay harms usability

Motion Goals

Each proposal should satisfy at least one of these goals:

1. Continuity - where things came from and where they go
2. Feedback - action acknowledged with clear response
3. Hierarchy - what changed most and why
4. Focus Guidance - attention moves to the right target

Mechanism Selection

Choose the lightest mechanism that satisfies the interaction:

• CSS transition - state changes on a single element/component (hover, open/close, selected state)
• CSS keyframes - multi-stage timeline or repeated motion (loading, attention pulse, choreography)
• WAAPI - imperative sequencing, playback control, cancel/reverse sync with logic
• View Transitions API - continuity across DOM swaps, route changes, or layout mode changes

Transform Strategy

translate: / rotate: / scale: (individual properties)

Use individual transform properties when:

• You want composable state layers (base styles + state overrides)
• Different interactions control different transform channels
• You need clearer design-token mapping and maintainability

transform: shorthand

Use shorthand when:

• Transform order is intentionally coupled
• You combine multiple functions in one declaration and must preserve exact sequence
• You need functions not exposed as individual props in your target browser strategy

translate3d() and 3D transforms

Use translate3d() only when:

• You need actual 3D/perspective behavior
• You have profiled a measurable compositor benefit in a real bottleneck

Avoid using translate3d() as a blanket "GPU hack". It can increase layer memory and produce jank if overused.

Easing System (Including linear())

Default guidance

• Use cubic-bezier() for most product interactions
• Use linear() for piecewise velocity control and custom motion signatures
• Tokenize easing values and reuse consistently

Where linear() shines

• Spring-like settle without JS spring physics
• Controlled overshoot/settle curves
• Brand motion signatures with explicit velocity shaping

Keep point counts intentional (typically 4-8 points). Prefer readable named tokens over ad-hoc per-component values.

linear() examples by intent

:root {
  --ease-linear-enter-soft: linear(0, 0.08 12%, 0.34 36%, 0.74 66%, 0.93 84%, 1);
  --ease-linear-exit-crisp: linear(0, 0.3 18%, 0.72 58%, 0.9 78%, 1);
  --ease-linear-settle-gentle: linear(0, 0.06 10%, 0.31 32%, 0.72 62%, 0.92 82%, 1);
  --ease-linear-emphasis-pop: linear(0, 0.38 20%, 0.88 62%, 1);
}
 
.chip-enter {
  transition: opacity 180ms var(--ease-linear-enter-soft),
    translate 180ms var(--ease-linear-enter-soft);
}
 
.panel-exit {
  transition: opacity 150ms var(--ease-linear-exit-crisp),
    transform 150ms var(--ease-linear-exit-crisp);
}
 
.shared-element-settle {
  transition: transform 320ms var(--ease-linear-settle-gentle);
}
 
.cta-emphasis {
  transition: transform 170ms var(--ease-linear-emphasis-pop);
}

See: references/LINEAR_EASING_PATTERNS.md

View Transitions API (Deep Use)

Same-document transitions

• Wrap the DOM/state update in document.startViewTransition(() => update())
• Name only meaningful shared elements with view-transition-name
• Style transition pseudo-elements intentionally

Cross-document transitions

• Opt in with @view-transition { navigation: auto; }
• Keep shared element naming consistent across pages
• Ensure entry/exit states remain meaningful when transition is unavailable

Key pseudo-elements

• ::view-transition-old(root) / ::view-transition-new(root)
• ::view-transition-old(name) / ::view-transition-new(name)
• ::view-transition-group(name)

Failure and fallback behavior

• Feature-detect and fall back to standard state updates
• Respect reduced motion by removing spatial travel and keeping clear state change
• Never block core interactions while waiting for transition effects

See: references/VIEW_TRANSITION_RECIPES.md

Performance Rules

• Prefer animating transform and opacity
• Avoid animating layout-affecting props for core interactions (top, left, width, height)
• Minimize long-running infinite animations on large surfaces
• Use will-change sparingly and remove when not needed
• Profile before and after changes (frame stability, long tasks, layer count)

Accessibility Rules

• Support @media (prefers-reduced-motion: reduce)
• Replace big travel/zoom with fade or instant state change when reduced motion is requested
• Keep feedback timing responsive; avoid long delays before state confirmation
• Ensure focus order, focus visibility, and keyboard behavior remain correct during/after transitions

Timing Heuristics

• Micro interactions: 120-180ms
• Component transitions: 180-260ms
• Structural/layout/route transitions: 240-420ms
• Exits generally faster than enters

Interaction Design Heuristics

• Use motion to explain state change, not decorate it
• Stagger only when it improves scannability or hierarchy
• Keep directional logic consistent with layout flow
• Prefer fewer, coherent motion patterns over many unique effects

Output Contract

When using this skill, produce these five sections:

1. Intent - what user perception or behavior the motion should drive
2. Motion Spec - duration, easing token, distance, trigger, affected elements
3. Implementation - concrete CSS/JS/View Transition code
4. Accessibility Fallback - reduced-motion and unsupported API behavior
5. QA Checklist - performance, usability, and cross-device verification

Starter Tokens

Use these baseline tokens and adapt to the product:

See: references/MOTION_TOKENS.css

Review Checklist

Before shipping, run through:

See: references/MOTION_REVIEW_CHECKLIST.md