web-animation-view-transitions

这段内容是审核时保存的快照。外部来源才是完整且最新的版本。

---
name: web-animation-view-transitions
description: View Transitions API patterns - same-document transitions, cross-document MPA transitions, shared element animations, pseudo-element styling, accessibility
---

# View Transitions API Patterns

> **Quick Guide:** Use the View Transitions API for native page/state transitions. `document.startViewTransition()` for same-document, `@view-transition { navigation: auto }` for cross-document MPA. Always feature-detect before use and respect `prefers-reduced-motion`. Use the options form `startViewTransition({ update, types })` when you need typed transitions.

---

<critical_requirements>

## CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST feature-detect before using startViewTransition - it is NOT available in all browsers)**

**(You MUST respect prefers-reduced-motion by providing reduced or disabled animations)**

**(You MUST ensure view-transition-name values are unique - duplicate names break transitions)**

**(You MUST clean up dynamically assigned view-transition-name values after transitions complete)**

**(You MUST use named constants for all animation timing values - NO magic numbers)**

</critical_requirements>

---

**Auto-detection:** View Transitions API, startViewTransition, view-transition-name, @view-transition, ::view-transition, pageswap, pagereveal, ViewTransition, view-transition-class, match-element, active-view-transition-type

**When to use:**

- Animating state changes in single-page applications
- Creating smooth page-to-page transitions in multi-page applications
- Implementing shared element (hero) animations between views
- Providing visual continuity during navigation
- Creating custom transition effects (slide, scale, circular reveal)

**Key patterns covered:**

- Same-document transitions with startViewTransition()
- Cross-document MPA transitions with @view-transition CSS
- view-transition-name for shared element animations
- Pseudo-element styling (::view-transition-old, ::view-transition-new)
- Direction-aware transitions with :active-view-transition-type()
- Feature detection and graceful fallbacks
- prefers-reduced-motion accessibility patterns

**When NOT to use:**

- Complex physics-based animations (use animation libraries)
- Animations requiring precise timeline control
- Simple hover/focus effects (use CSS transitions)

**Detailed Resources:**

- [examples/core.md](examples/core.md) - Feature detection, state transitions, promise handling, CSS customization
- [examples/spa.md](examples/spa.md) - Theme switcher, form steps, tab panels, list reordering
- [examples/shared-elements.md](examples/shared-elements.md) - Hero animations, multiple shared elements, MPA shared elements, modals
- [reference.md](reference.md) - Decision frameworks, pseudo-element reference, browser support, anti-patterns

---

<philosophy>

## Philosophy

The View Transitions API provides a native browser mechanism for creating animated transitions between DOM states or pages. It captures "before" and "after" snapshots, overlays them as pseudo-elements, and animates between them.

**Core principles:**

1. **Native over library** - Browser-native transitions are more performant and require less JavaScript
2. **Progressive enhancement** - Always feature-detect and provide functional fallback
3. **Snapshot-based** - Old state is captured as a screenshot, new state as a live representation
4. **CSS-driven** - Customize animations through pseudo-element CSS, not JavaScript
5. **Accessibility-first** - Always respect prefers-reduced-motion user preferences

</philosophy>

---

<patterns>

## Core Patterns

### Pattern 1: Feature Detection with Fallback

Always check for API support before using View Transitions. See [examples/core.md](examples/core.md) Pattern 1 for full utility.

```typescript
const SUPPORTS_VIEW_TRANSITIONS =
  typeof docu