From 9983e8e1638009f13a146a9f6da892062bc1de1b Mon Sep 17 00:00:00 2001
From: Rudevin Cosejo <101231071+Rudevin17@users.noreply.github.com>
Date: Wed, 29 Jul 2026 05:28:25 +0800
Subject: [PATCH] docs: note that transitions bypass CSS prefers-reduced-motion

Svelte 5 transitions are driven by the Web Animations API, so a global
`@media (prefers-reduced-motion: reduce)` rule that zeroes transition-duration
and animation-duration has no effect on them -- a reader who reaches for the
usual CSS reset gets no warning that it does nothing here.

`prefersReducedMotion` already covers this and is documented on the
svelte/motion page, but nothing on the transition page points to it. This adds
a short Accessibility section that does, reusing the example from the
svelte/motion docs so the two pages stay consistent.
---
 .../docs/03-template-syntax/14-transition.md  | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/documentation/docs/03-template-syntax/14-transition.md b/documentation/docs/03-template-syntax/14-transition.md
index 9b14b7b25b..c0574cd184 100644
--- a/documentation/docs/03-template-syntax/14-transition.md
+++ b/documentation/docs/03-template-syntax/14-transition.md
@@ -41,6 +41,27 @@ Transitions are local by default. Local transitions only play when the block the
 
 A selection of built-in transitions can be imported from the [`svelte/transition`](svelte-transition) module.
 
+## Accessibility
+
+Transitions are driven by the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) rather than by CSS. A global `@media (prefers-reduced-motion: reduce)` rule that zeroes `transition-duration` and `animation-duration` therefore does not reach them, and someone who has asked their operating system for less motion will still see the full animation.
+
+Use [`prefersReducedMotion`](svelte-motion#prefersReducedMotion) to honour the preference:
+
+```svelte
+<script>
+	import { prefersReducedMotion } from 'svelte/motion';
+	import { fly } from 'svelte/transition';
+
+	let visible = $state(false);
+</script>
+
+{#if visible}
+	<p transition:fly={{ y: prefersReducedMotion.current ? 0 : 200 }}>
+		flies in, unless the user prefers reduced motion
+	</p>
+{/if}
+```
+
 ## Transition parameters
 
 Transitions can have parameters.