asymmetric-al/vercel-react-view-transitions
.agents/skills/vercel-react-view-transitions/SKILL.md
React View Transitions and Next.js App Router route continuity. Use for page or route transitions, shared element morphs, React ViewTransition usage, list-to-detail navigation polish, and navigation motion across admin, donor, or missionary surfaces — without fighting motion/react.
$ install --global
skillsauthnpx skillsauth add asymmetric-al/core vercel-react-view-transitionsInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 10, 2026, 3:08 AM92.2s2 files scanned
SKILL.md
- name:
- vercel-react-view-transitions
- description:
- React View Transitions and Next.js App Router route continuity. Use for page or route transitions, shared element morphs, React ViewTransition usage, list-to-detail navigation polish, and navigation motion across admin, donor, or missionary surfaces — without fighting motion/react.
- owner:
- skills-steward
- last_updated:
- 2026-04-04
- status:
- active
- url:
- https://skills.sh/vercel-labs/agent-skills/vercel-react-view-transitions
- repo:
- vercel-labs/agent-skills
- path:
- skills/vercel-react-view-transitions/SKILL.md
- ref:
- 73140fc5b3a214ad3222bcf557b397b3c02d11c1
- license:
- MIT
Vercel React View Transitions (Asymmetric.al monorepo)
Browser-native View Transitions coordinated by React’s <ViewTransition> (see React docs). In this repo they complement — do not replace — motion/react (@asym/lib/motion, docs/ai/skills/motion, docs/ai/skills/anim).
When to Apply
Use this skill when:
- Adding or tuning route-level continuity inside app shells (
MCShell, missionaryAppShell, donor public/dashboard layouts). - Adding shared element morphs (same stable
nameon source + destination). - Reviewing navigation motion so it stays Maia / Zinc: quiet, short, opacity-first, subtle scale/translate.
- Debugging double animation (VT +
motionentrance on the same block).
Do not use this skill when:
- The surface is Payload
/web-studio— keep that path free of extra client boundaries (admin already bypassesMCShellthere). - The task is micro-interaction only (hover, tap, dialog choreography) — use
motion+animinstead. - You need production guarantees — upstream Next docs still mark this area experimental; ship behind the repo flag (below).
Repo Integration (source of truth)
| Concern | Location |
| ------------------------------- | ------------------------------------------------------------------------------------ |
| Next flag | experimental.viewTransition: true in each app next.config.ts |
| Rollout flag | NEXT_PUBLIC_VIEW_TRANSITIONS_ENABLED in @asym/env + .env.example |
| Capability + naming helpers | @asym/lib/view-transitions |
| Route boundary + shared wrapper | @asym/ui/components/view-transitions |
| Global VT animation classes | packages/ui/styles/globals.css (asym-vt-*) |
| Shell insertion | Admin apps/admin/app/mc-shell.tsx <main> |
| | Missionary apps/missionary/components/app-shell.tsx |
| | Donor apps/donor/app/(public)/layout.tsx + donor-dashboard layout |
| Page header vs VT | PageShell quiets motion when inside route VT (useWithinViewTransitionRouteLayer) |
Rollout Rules
View Transitions run only when all are true:
NEXT_PUBLIC_VIEW_TRANSITIONS_ENABLED=true(validated via@asym/env).- Browser supports
document.startViewTransition(seeclientDocumentSupportsViewTransitions()). - User does not prefer reduced motion (
useReducedMotion()from@asym/lib/motion).
Otherwise render plain children — no broken navigation, no hydration tricks.
API Surface (do not invent props)
- Import
<ViewTransition>fromreact(Next 16 bundles the compatible React channel). Load types viaimport {} from "react/experimental"in client files that need canary typings. - Props include
default,enter,exit,share,update, and optionalnamefor shared morphs — see@types/react/canary.d.tsin this repo. - Prefer
default="none"and opt into specific triggers to avoid noisy cross-fades on every Suspense tick (upstream skill guidance). addTransitionTypeexists for typed animations; Next.js-specific automatic transition typing is still evolving — read bundled.next-docs/.../viewTransition.mdxbefore relying on framework wiring.
Placement Rules
- Keep shells stable — wrap the changing
<main>/ content column only, not<html>or full provider trees. <ViewTransition>must be the first DOM wrapper for enter/exit on that subtree (no extra parentdivabove it for those triggers — ourRouteMainViewTransitionBoundaryputs the optionalclassNameon an inner div inside<ViewTransition>).- Shared elements: one mounted
nameat a time. Use deterministic builders in@asym/lib/view-transitions(e.g.worker-hero:${id}). - Payload admin: never wrap
/web-studiocontent with the route boundary (already excluded inMCShell).
Avoiding Double Animation with motion/react
- Route VT owns screen-to-screen continuity.
- motion/react owns hovers, presses,
AnimatePresence, dialogs, staggered cards, feed reactions. - If both animate the same header block, pick one:
PageShellalready disables its header motion whenuseWithinViewTransitionRouteLayer()is true. Apply the same pattern elsewhere (context lives in@asym/lib/view-transitions/context).
Accessibility
- Respect
prefers-reduced-motion(wrappers return plain children; CSS@media (prefers-reduced-motion: reduce)zeroes VT animations inglobals.css). - Never animate focus rings; do not delay validation or error feedback.
Triggers
- Page transitions, route transitions, shared element transitions, React
ViewTransition, Next.js App Router view-transition work, list/detail navigation polish acrossapps/admin,apps/donor,apps/missionary.
Workflow
- Confirm
experimental.viewTransitionis enabled for the target app. - Decide if the change needs the env flag on in dev (
NEXT_PUBLIC_VIEW_TRANSITIONS_ENABLED=true). - Add or reuse stable transition names for shared elements.
- Wrap only the swapping region with
RouteMainViewTransitionBoundary. - Tone down overlapping motion on the same surface.
- Verify Payload
/web-studio, auth redirects, and reduced motion.
Checklist
- [ ] Used
@asym/uiboundaries instead of one-off per-app VT wrappers - [ ] Shared element
nameis deterministic and matches on both ends - [ ] No VT wrapper around Payload admin or entire provider tree
- [ ] Reduced motion and flag-off paths tested
- [ ] No competing
motionentrance on the same node as route VT - [ ] After editing this skill:
bun run skills:sync&&bun run skills:verify
References
- Upstream provenance:
references/upstream.md - Next.js config note:
.next-docs/01-app/03-api-reference/05-config/01-next-config-js/viewTransition.mdx - Motion stack:
docs/ai/skills/motion/SKILL.md,docs/ai/skills/anim/SKILL.md
Related Skills
asymmetric-al/payload
development
VerifiedTrustedCommunity
Use when working with Payload CMS projects (payload.config.ts, collections, fields, hooks, access control, Payload API). Use when debugging validation errors, security issues, relationship queries, transactions, or hook behavior.
473SKILL.mdUpdated Apr 10, 2026
asymmetric-al/triage-ci-flake
testing
VerifiedTrustedCommunity
Use when CI tests fail on main branch after PR merge, or when investigating flaky test failures in CI environments
473SKILL.mdUpdated Apr 10, 2026
asymmetric-al/generate-translations
tools
VerifiedTrustedCommunity
Use when new translation keys are added to packages to generate new translations strings
473SKILL.mdUpdated Apr 10, 2026
asymmetric-al/repo-entry
data-ai
VerifiedTrustedCommunity
Pointer to the canonical agent instruction and skill system for this monorepo
473SKILL.mdUpdated Apr 10, 2026