motion-systems

Files (10)

• SKILL.md
• SKILL.md · motion-choreography-patterns/
• CHOREOGRAPHY_PATTERNS.md · motion-choreography-patterns/references/
• INTERACTION_SCENARIOS.md · motion-choreography-patterns/references/
• QA_STORYBOARD_CHECKLIST.md · motion-choreography-patterns/references/
• STAGGER_SYSTEMS.css · motion-choreography-patterns/references/
• LINEAR_EASING_PATTERNS.md · references/
• MOTION_REVIEW_CHECKLIST.md · references/
• MOTION_TOKENS.css · references/
• VIEW_TRANSITION_RECIPES.md · references/

SKILL.md (first lines)

# CSS Motion Systems

Production-oriented motion for web UI - interaction clarity, performance,
and accessibility, not decoration. Skip motion entirely when it adds
cognitive load or delays a state update that must feel instant.

## 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

```css
: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](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

From scott-fryxell/brayness, MIT.

More from scott-fryxell/brayness