Page Transitions

page-transitions — navigation never feels slower

Stage: Phase 9 — Motion - Reads: design/SYSTEM.md §motion, design/SITEMAP.md, app/ structure - Writes: app-level transition layer (app/template.tsx, optional next.config.ts flag + ViewTransition wrappers)

Standard

A route transition is seasoning on navigation, never a gate in front of it. First-grade means: 150–300ms, content-only (persistent chrome stays still), instant swap under reduced motion, and — because Next 16 View Transitions are EXPERIMENTAL — the site is complete and correct with transitions absent. "No transition" is a valid first-grade answer; dashboards and rapid-navigation flows are better without one.

• Ceiling: 300ms. The moment a transition makes navigation feel slower, cut it, not the duration alone.
• Two-tier architecture. Tier 1 (default, stable APIs): template.tsx entrance animation. Tier 2 (enhancement, experimental): View Transitions for cross-route continuity. Never both animating the same surface — that double-fires.
• anime.js never owns a route transition. Even on a build where DIRECTION.md commissioned the engine for an SVG moment (ultraweb:animejs), navigation stays View Transitions / template.tsx / motion — a third runtime racing the App Router's own commit timing buys nothing Tier 1 doesn't already give for free. A persistent scene never owns one either. The camera move may accompany the cut — that is the point of mapping each route to a window of one clip — but template.tsx / View Transitions / motion still commit the navigation, and a 3D affordance navigates by emitting a real href the DOM nav already reaches. A canvas cannot cross-fade with itself: prefer the View Transitions API, which snapshots it for free, over a hand-rolled preserveDrawingBuffer + drawImage clone.
• Chrome is stable. Header, nav, footer never transition; only the page content wrapped below them.
• Entrance-only in Tier 1. template.tsx remounts on navigation but cannot animate exit — the old page unmounts immediately. Accept it; don't hack exit with AnimatePresence around route children (fragile in App Router).
• The Masked Cut — only when DIRECTION.md justifies a full-bleed transition (award-canon). Cover the swap with one brief full-bleed effect (color-flood, frost, dissolve) and fire the route or heavy swap behind the cover so the load is invisible; an incoming brand-color flood doubles as wayfinding. This is the disciplined form of the full-screen wipe the anti-patterns gate — ONE grammar reused site-wide, reduced-motion → plain crossfade or instant, and never a persistent-canvas SPA just to keep a scene alive across routes — with one commissioned exception, and it is not an SPA: when DIRECTION.md commissions a site-scale scene (ultraweb:set-design), the canvas persists but the App Router still owns navigation. Every route stays a real URL with server-rendered content, <Link> still navigates, the announcer still announces, and the scene is a background that survives the swap — never a router that replaces it. A canvas that intercepts navigation with history.pushState is the banned SPA wearing a commission.
• Shared-Element Lift (award-canon): Browse → Elevate → Read. A picked item lifts into its detail — the same element scales up via a shared-element transition (Motion layoutId for an in-page lift, or Tier 2 View Transitions cross-route) so the reader never loses their place. Even inside a looping/infinite field every card stays a real crawlable <a href> with its own URL (endless field, bounded meaning); browser Back returns to the field at the same scroll position.
• Route-change announcer — REQUIRED whenever routes animate (the AA floor, not an enhancement). A template.tsx entrance or a View Transition is visible but silent: client navigation never fires the browser's native new-document title announcement, so a screen-reader user is never told the page changed. Any animated route flow ships a persistent visually-hidden aria-live="polite" region that speaks the new page's <h1>/title one paint after the route commits — the audible half of accessible client nav, paired with focus reset (app-structure). See Route announcer below.

Process

1. Read SYSTEM.md §motion and SITEMAP.md; pick a strategy from the decision table. Record it in SYSTEM.md §motion.
2. Implement Tier 1: app/template.tsx with a 200–250ms fade + 8px rise. Template, not layout — layouts persist across navigation and would animate exactly once per session.
3. Optionally enable Tier 2: experimental.viewTransition: true in next.config.ts, import { ViewTransition } from "react", wrap the transitioning surfaces. Give shared elements (card image → detail image) matching name props for continuity. <Link transitionTypes={[...]}> scopes animation styles per navigation type (per STACK.md). Behavior beyond these verified facts: check current docs first.
4. When Tier 2 is on, remove the Tier 1 animation from the routes it covers.
5. Ship the route announcer (required for ANY animated route flow, Tier 1 or Tier 2): mount <RouteAnnouncer/> once in app/layout.tsx, below {children} — see Route announcer below. Skip only when the site chose "None" (no route animates at all).
6. Reduced motion: transitions become instant swaps — gate the template animation and View Transition CSS behind prefers-reduced-motion. The announcer is exempt: it carries no motion and stays on under reduced motion.
7. Verify: click every nav path, use browser back/forward, confirm scroll restoration still works, test in a browser WITHOUT View Transitions support (instant swap must look intentional), console clean; and with a screen reader running (NVDA / VoiceOver), confirm each client route change announces the new page title exactly once.

Decision table

Tier 1 — template.tsx (stable, the default)

// app/template.tsx — remounts every navigation; layout.tsx does not
"use client";
import { m } from "motion/react"; // app-level LazyMotion(domAnimation) provider required

export default function Template({ children }: { children: React.ReactNode }) {
  return (
    <m.div
      initial={{ opacity: 0, y: 8 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.25, ease: "easeOut" }}
    >
      {children}
    </m.div>
  );
}

children passed as props stay server components — the client boundary is this wrapper only. Place the template at the segment level that should animate (app root for all routes; a route group to exempt the dashboard).

Tier 2 — View Transitions (experimental enhancement)

// next.config.ts
import type { NextConfig } from "next";
const nextConfig: NextConfig = { experimental: { viewTransition: true } };
export default nextConfig;

import { ViewTransition } from "react";
// list page:  <ViewTransition name={`cover-${post.slug}`}><Image …/></ViewTransition>
// detail page: same name on the destination image → the browser morphs one into the other

Browsers without the View Transitions API get an instant swap — that IS the design for them, which is why the underlying pages must look finished without any transition. This flag is experimental: expect API movement, re-verify against current Next docs at build time, and never let a Tier 2 feature become load-bearing for layout or content.

Route announcer — the accessible half of client navigation

Client navigation swaps content inside one live document, so the browser's native "new page" title announcement never fires — a screen-reader user hears nothing when a route (or a View Transition) changes. Ship ONE persistent visually-hidden live region that speaks the new page. It mounts once in app/layout.tsx (never template.tsx: a region that remounts with the route isn't stable in the DOM when its text changes, so the announcement is dropped).

// components/layout/route-announcer.tsx — render ONCE in app/layout.tsx, below {children}
"use client";
import { useEffect, useState } from "react";
import { usePathname } from "next/navigation";

export function RouteAnnouncer() {
  const pathname = usePathname();
  const [label, setLabel] = useState("");
  useEffect(() => {
    // title/H1 resolve a paint AFTER the route commits; read next frame, latest read wins
    const id = requestAnimationFrame(() => {
      const h1 = document.querySelector("main h1")?.textContent?.trim();
      setLabel(h1 || document.title);
    });
    return () => cancelAnimationFrame(id); // coalesces rapid navigations — no stacked announcements
  }, [pathname]);
  return <div aria-live="polite" role="status" className="sr-only">{label}</div>;
}

polite, never assertive — a route change queues behind the user, it doesn't interrupt them. The region is empty on first paint (the native document-load announcement already covers the first page, so this never double-announces) and speaks only on subsequent client navigations. Prefer the <h1> over document.title: the heading is the page's on-screen name and is reliably in the DOM by the next frame, while document.title (set by each page's generateMetadata/metadata export) resolves slightly later and is the fallback. sr-only (Tailwind) keeps the node in the accessibility tree while off-screen — never hidden/display:none, which drops it from screen readers. Moving keyboard focus to that new heading is the other half of accessible client nav and belongs to ultraweb:app-structure: the announcer says what changed, the focus reset says where you are now.

Anti-patterns

• Motion components directly in layout.tsx — layouts don't remount; the animation plays once, then never again (grep m. / motion. in layout.tsx).
• AnimatePresence in template.tsx/layout.tsx to fake route exit animations — fragile App Router hack; grep for it.
• Transition > 300ms — the user is waiting on chrome.
• Animating the header/nav/footer during navigation — persistent chrome must hold still.
• Tier 1 + Tier 2 both active on one route — double animation.
• Full-screen curtain/wipe overlays — portfolio-only move; requires explicit DIRECTION.md justification.
• Shipping experimental.viewTransition without testing the unsupported-browser path.
• No reduced-motion gate — route change must be an instant swap under prefers-reduced-motion: reduce.
• Animating a route (template or View Transition) with no live-region announcer — the swap is visible but silent to a screen reader. Required, not optional.
• Announcer mounted in template.tsx or a page instead of layout.tsx — it remounts with the route, so the live region isn't stable when its text changes and the announcement is dropped (grep RouteAnnouncer in template.tsx / page files).
• aria-live="assertive" or role="alert" for route announcements — interrupts the user mid-utterance; route changes are polite.

Worked example — Studio Norra, case-study route continuity

Moved to references/example.md — read only when this build's case is genuinely ambiguous; the sections above are the decision material.

Composes with

Moved to references/composes.md — the handoff map; load it when orchestrating this skill against its neighbors.