Home / All Skills / Design & Motion / page-transition-animation
English (EN)简体中文 (ZH)日本語 (JA)
Design & Motion · iart-ai/web-animation-skills

page-transition-animation

This skill should be used when the user asks to "animate page or route transitions", "add a page transition or crossfade between views", "animate route changes in Next.js App Router", "use the View Transitions API", "AnimatePresence exit doesn't fire on navigation", or "Framer Motion exit animation not working / exit animation before unmount in Next.js". Covers enter/exit page-transition animation with the View Transitions API and Framer Motion, for Next.js App Router and general SPA routing.

L3 Networked · Declare domain & key scopeV1 Commit-PinnedNetwork AccessWrite FileDual-pass Audit
Author iart-aiGitHub iart-ai/web-animation-skills ↗Stars 28License MIT（仓库根 LICENSE 为 MIT License, Copyright (c) 2026 iart.ai；.claude-plugin/plugin.json 的 license 字段同为 MIT）Commit b6dba3eb75
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

First clarify the structural root cause of the failure: App Router navigation immediately swaps out the old route content, whereas AnimatePresence can only execute exit animations when the unmounting child remains mounted and its wrapper persists continuously.

skills/page-transition-animation/SKILL.md
The reason is structural — in the App Router, when navigating, Next.js unmounts the old route's content and mounts the new one almost immediately.
Hardcode the three mandatory prerequisites: persistent wrapper, child key updated on route change, and the old subtree still rendering previous content during exit.

Solution A consists of template.tsx (remounts on every navigation) + AnimatePresence keyed by pathname + FrozenRouter (snapshots LayoutRouterContext so the old tree keeps rendering old content).

skills/page-transition-animation/SKILL.md
const frozen = useRef(context).current;
Provide full code for all three files (template.tsx, page-transition.tsx, frozen-router.tsx) along with explanations of parameters (mode="wait", initial={false}).

Solution B consists of the native View Transitions API (::view-transition-old/new animations with router.push wrapped in document.startViewTransition), or out-of-the-box integration via next-view-transitions.

skills/page-transition-animation/SKILL.md
::view-transition-old(root) { animation: fade 0.25s both reverse; }
Define clear selection criteria: use View Transitions for simple crossfades or morphs, and Framer Motion for fine-grained orchestration and interruptible exits; mandate a capability guard for startViewTransition.

Structure troubleshooting as an ordered checklist (7 items) covering wrapper placement, keys, direct motion descendants, mode="wait", FrozenRouter, 'use client', and single children.

skills/page-transition-animation/SKILL.md
**Stable, changing key.** The animated child needs `key={pathname}` (or similar) so removal is detected.
Break down the issue of exit animations failing to fire into an actionable, step-by-step checklist rather than scattered tips.

Reduce verification to an independently reproducible single-file harness: use two stub pages with ?view=/phase= to freeze transition phases and validate the motion shape isolated from the Next project first.

skills/page-transition-animation/SKILL.md
One file is the right tier for validating motion before wiring the router; don't stand up Next just to eyeball a fade.
Clarify that View Transitions snapshots are transient; screenshots must capture the end state (or simulate it via slowed-down animations).

2Core Capabilities

01Per-route entrance in App Router (template.tsx remounting on each navigation)
02Route exit animations (pathname-keyed AnimatePresence plus FrozenRouter to prevent content flashing)
03Native View Transitions integration (CSS pseudo-elements plus router.push guarded with startViewTransition)
04Single-point integration of next-view-transitions (wrapping layout with ViewTransitions and switching to its Link)
057-point troubleshooting checklist for AnimatePresence not triggering
06Directional slides, crossfades, shared element transitions, and loading.tsx transition variants
07Transition phase freezing harness (?view=b and ?phase=exit)
08Zero-build delivery (verifying transitions in a standalone HTML file with two stub pages without spinning up Next)
09Accessibility criteria: degrading directional slide offsets to a short crossfade under reduced-motion

3External Dependencies

KindDependency / Endpoint
packageframer-motion（AnimatePresence 与 motion，配合 template.tsx 与 FrozenRouter）
packagenext-view-transitions（把 View Transitions 接进 App Router 客户端导航）
apiNext.js 内部模块 LayoutRouterContext（next/dist/shared/lib/app-router-context.shared-runtime）与 usePathname
api浏览器原生 View Transitions API（document.startViewTransition、::view-transition-old/new、view-transition-name）
network交付页从 CDN 取 motion 与 React（产物期引用，不判级；正文未点名具体域）
clinpx / Playwright（宿主侧截图工具）与仓库根 scripts/ 助手（seek-shot.sh、contact-sheet.sh 依赖 ffmpeg）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation
For Agent Runtime
Declare allowed domains and key scope
For Administrators
Least privilege keys, retain request logs
Evidence & Triggers (File Paths & Excerpts)
  • 网络端点: External network access declaration: Zero outbound requests during runtime execution; delivery page imports motion and React from CDN (artifact-phase reference; domains not specified in the body)
  • 本地工作目录: File I/O and artifact output: Zero disk writes within this skill directory; agent writes template.tsx, page-transition.tsx, and frozen-router.tsx into user's Next project
Audit Notes: Grading is based solely on the skill's own directory (skills/page-transition-animation/ = SKILL.md + 0-byte README.md + references/full-examples.md, fully verified via find): zero scripts, zero credentials, zero disk writes, zero runtime outbound network calls (token scan for fetch(/XMLHttpRequest/curl/wget/child_process/process.env/API_KEY|TOKEN|SECRET/.env/eval( yielded zero hits). The CDNs mentioned in the text (motion and React, without explicit domains) appear in the output contract as artifact-phase references, which do not affect grading under batch 4 criteria. Imports of Next internal modules are project dependencies (installed by the user's project) rather than outbound actions by this skill.

5Second-Pass Verification

  • [discrepancy] description 声称的覆盖范围（Next.js App Router 与 general SPA routing）与正文实际覆盖面是否相符 — frontmatter 写 ... for Next.js App Router and general SPA routing.，但正文主体（根因分析、方案 A 的三个文件、7 条排查清单）全部是 App Router 专属；general SPA 只在 View Transitions API 与交付用 stub HTML 两处被顺带覆盖，既无 React Router/Remix 等通用 SPA 路由的接线，也无对应排查清单。属描述略宽于实现（非虚假，但按 description 期望通用方案会落空）。
  • [ok] FrozenRouter 依赖的 Next 内部 import 路径真实性 — SKILL.md 给出 import { LayoutRouterContext } from 'next/dist/shared/lib/app-router-context.shared-runtime'; 并在正文、notes、gotchas、references 四处重复提示 internal、跨版本可能变，references 还专列 FrozenRouter import note across versions 一节；即文档自己对该脆弱性做了标注，非隐瞒。
  • [ok] View Transitions 验收的可行性（快照是瞬态） — 正文承认 snapshots are transient，并给出替代（截结束态或用 emulate slow animations），验收步骤不依赖捕捉瞬态帧；startViewTransition 的能力守卫在正文与完成前清单第 1 条都要求。
  • [discrepancy] Packaged helper 的路径基准与语义 — SKILL.md 的 verify 段仍贴 scripts/seek-shot.sh anim.html 0 1.5 3（时间冻结、仓库根路径），但本 skill 的冻结参数是 ?view= 与 ?phase=（状态与相位），helper 不匹配；scripts/ 也在仓库根而非本 skill 目录。

6Verdict & Scenarios

  • Frames the most common exit-failure issue as a structural root cause with three strict prerequisites rather than fragmented tricks
  • Delivers copy-paste-ready code for both approaches (three tsx files, CSS pseudo-elements with guarded wrapper) along with selection criteria
  • Rich reference materials: references include complete directory layout, directional variants, shared elements, loading.tsx, and a decision matrix
  • Transparent about brittle points: explicitly highlights Next.js internal import paths as version-sensitive across multiple places
    • Best for: Best for: 1) Next.js App Router projects requiring enter/exit transitions for pages and routes (especially where exit animations fail to trigger and the old page vanishes instantly); 2) Teams deciding between Framer Motion and View Transitions; 3) Projects needing shared element transitions (view-transition-name) or directional slide transitions; 4) Developers wanting to prototype and verify transition curves in a single file before wiring them into the project.
    Not for: Not suitable for: 1) Non-Next general SPA routing (mentioned in description but lacks concrete wiring in the body; requires manual implementation); 2) In-page element micro-interactions only (use micro-interaction skills instead); 3) Projects that cannot tolerate private framework internal imports (the FrozenRouter approach carries upgrade risks; use View Transitions instead); 4) Unguarded implementations requiring universal browser support (View Transitions lack universal support and strictly require fallbacks).
    Install Agent-Ready
    ① Verified Mirror 2026-09-28
    Option A · Direct DownloadDownload page-transition-animation.tar.gz
    sha256: 083d4f27aaf44464…
    Option B · Copy Guide for Agent
    install.json
    Agents automatically download and verify mirrors from this JSON guide.
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit b6dba3eb75.