From b842e4e871785d4bda5acaf6a74a2fb9e98e5add Mon Sep 17 00:00:00 2001
From: npeter83 <npeter83+claude@gmail.com>
Date: Sun, 18 Oct 2026 21:40:52 +0200
Subject: [PATCH] fix(ui): a looping pulse stops for reduced motion; the e2e
 waits for skeleton bones, not for any pulse

- Seven looping pulses (a running job's dot, the scheduler's progress bar, a queued download, the
  download tray, a playlist upload, a channel's full-history action, the setup wizard's test mail)
  ran regardless of prefers-reduced-motion, which docs/DESIGN.md promises to respect: each is
  motion-safe now, held by a contract test.
- The a11y suite's "settled" wait took every aria-hidden pulse for a loading skeleton, so the
  Scheduler legend's running dot, which pulses for good, kept it waiting until it timed out. A
  skeleton bone now says it is one (data-skeleton) and the wait looks for that.
---
 frontend/e2e/a11y.spec.ts                     |  7 ++--
 frontend/src/components/Channels.tsx          |  4 ++-
 frontend/src/components/DownloadButton.tsx    |  5 ++-
 frontend/src/components/DownloadTray.tsx      |  2 +-
 frontend/src/components/RunStatusDot.tsx      |  2 +-
 frontend/src/components/Scheduler.tsx         |  2 +-
 frontend/src/components/SetupWizard.tsx       |  4 ++-
 frontend/src/components/ui/Skeleton.tsx       |  1 +
 .../src/components/usePlaylistActions.tsx     |  2 +-
 .../src/lib/reducedMotion.contract.test.ts    | 34 +++++++++++++++++++
 10 files changed, 52 insertions(+), 11 deletions(-)
 create mode 100644 frontend/src/lib/reducedMotion.contract.test.ts

diff --git a/frontend/e2e/a11y.spec.ts b/frontend/e2e/a11y.spec.ts
index d62b31e1..42830509 100644
--- a/frontend/e2e/a11y.spec.ts
+++ b/frontend/e2e/a11y.spec.ts
@@ -13,11 +13,10 @@ import { gotoPage, openApp, openFirstVideo } from "./helpers";
 // Chromium only (playwright.config.ts leaves it out of the other projects).
 const TAGS = ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa", "wcag22aa"];
 
-/** Wait until nothing is loading: no QueryState spinner and no skeleton bone left. */
+/** Wait until nothing is loading: no QueryState spinner and no skeleton bone left. A bone says it is
+ *  one (`data-skeleton`): a pulse alone is not loading — a running job's dot pulses as long as it runs. */
 async function settled(page: Page): Promise<void> {
-  await expect(
-    page.locator('[role="status"] .animate-spin, [aria-hidden="true"].animate-pulse'),
-  ).toHaveCount(0);
+  await expect(page.locator('[role="status"] .animate-spin, [data-skeleton]')).toHaveCount(0);
 }
 
 async function violations(page: Page): Promise<string[]> {
diff --git a/frontend/src/components/Channels.tsx b/frontend/src/components/Channels.tsx
index 125709fe..fc1e6c85 100644
--- a/frontend/src/components/Channels.tsx
+++ b/frontend/src/components/Channels.tsx
@@ -515,7 +515,9 @@ export default function Channels() {
       id: "backfill",
       label: t("channels.backfillEverything"),
       title: t("channels.backfillEverythingHint"),
-      icon: <History className={`h-4 w-4 ${deepAll.isPending ? "animate-pulse" : ""}`} />,
+      icon: (
+        <History className={`h-4 w-4 ${deepAll.isPending ? "motion-safe:animate-pulse" : ""}`} />
+      ),
       onSelect: () => deepAll.mutate(),
       disabled: deepAll.isPending,
     },
diff --git a/frontend/src/components/DownloadButton.tsx b/frontend/src/components/DownloadButton.tsx
index e12c2f84..f68d5f38 100644
--- a/frontend/src/components/DownloadButton.tsx
+++ b/frontend/src/components/DownloadButton.tsx
@@ -54,7 +54,10 @@ export default function DownloadButton({
       >
         {/* The state is in the glyph: downloaded or queued is the accent, a running one pulses. */}
         <Download
-          className={clsx((downloaded || inQueue) && "text-accent", inQueue && "animate-pulse")}
+          className={clsx(
+            (downloaded || inQueue) && "text-accent",
+            inQueue && "motion-safe:animate-pulse",
+          )}
         />
       </IconButton>
       {open && (
diff --git a/frontend/src/components/DownloadTray.tsx b/frontend/src/components/DownloadTray.tsx
index 9937cfca..bee55acc 100644
--- a/frontend/src/components/DownloadTray.tsx
+++ b/frontend/src/components/DownloadTray.tsx
@@ -98,7 +98,7 @@ function Progress({ job }: { job: QueueJob }) {
             style={{ width: `${job.progress}%` }}
           />
         ) : (
-          <span className="block h-full w-full animate-pulse bg-accent/60" />
+          <span className="block h-full w-full motion-safe:animate-pulse bg-accent/60" />
         )}
       </span>
       {bytes && <span className="w-8 shrink-0 text-right tabular-nums">{job.progress}%</span>}
diff --git a/frontend/src/components/RunStatusDot.tsx b/frontend/src/components/RunStatusDot.tsx
index cb3ba7f5..a1657c38 100644
--- a/frontend/src/components/RunStatusDot.tsx
+++ b/frontend/src/components/RunStatusDot.tsx
@@ -4,7 +4,7 @@
 // Interrupted is a ring, not a fill: the job did not fail, but its work did not finish either — set
 // apart from a skipped run (the same colour, filled) and from a failure.
 const DOT_CLASS = {
-  running: "bg-accent animate-pulse",
+  running: "bg-accent motion-safe:animate-pulse",
   ok: "bg-success",
   error: "bg-danger",
   skipped: "bg-warn",
diff --git a/frontend/src/components/Scheduler.tsx b/frontend/src/components/Scheduler.tsx
index 1b1cd714..e4d501cf 100644
--- a/frontend/src/components/Scheduler.tsx
+++ b/frontend/src/components/Scheduler.tsx
@@ -238,7 +238,7 @@ function JobProgress({ p }: { p: SchedulerJob["progress"] }) {
           />
         ) : (
           // Indeterminate: total unknown, so a slim moving sliver instead of a fill.
-          <div className="h-full w-1/3 rounded-full bg-accent animate-pulse" />
+          <div className="h-full w-1/3 rounded-full bg-accent motion-safe:animate-pulse" />
         )}
       </div>
     </div>
diff --git a/frontend/src/components/SetupWizard.tsx b/frontend/src/components/SetupWizard.tsx
index 6989b7f2..03f01ba8 100644
--- a/frontend/src/components/SetupWizard.tsx
+++ b/frontend/src/components/SetupWizard.tsx
@@ -259,7 +259,9 @@ export default function SetupWizard() {
                     onClick={sendTest}
                     disabled={testState === "sending" || !testTo.trim()}
                   >
-                    <Send className={`w-4 h-4 ${testState === "sending" ? "animate-pulse" : ""}`} />
+                    <Send
+                      className={`w-4 h-4 ${testState === "sending" ? "motion-safe:animate-pulse" : ""}`}
+                    />
                     {t("setup.smtp.test")}
                   </Button>
                 </div>
diff --git a/frontend/src/components/ui/Skeleton.tsx b/frontend/src/components/ui/Skeleton.tsx
index 5c1576ff..115fef2c 100644
--- a/frontend/src/components/ui/Skeleton.tsx
+++ b/frontend/src/components/ui/Skeleton.tsx
@@ -13,6 +13,7 @@ function Skeleton({ className, inline = false }: { className?: string; inline?:
   return (
     <Tag
       aria-hidden="true"
+      data-skeleton=""
       className={clsx(
         "rounded-lg bg-fg/8 animate-pulse motion-reduce:animate-none",
         inline && "inline-block align-middle",
diff --git a/frontend/src/components/usePlaylistActions.tsx b/frontend/src/components/usePlaylistActions.tsx
index 0a32a1e0..2e90866e 100644
--- a/frontend/src/components/usePlaylistActions.tsx
+++ b/frontend/src/components/usePlaylistActions.tsx
@@ -269,7 +269,7 @@ export function usePlaylistActions() {
               id: "push",
               label: linked ? t("playlists.pushToYoutube") : t("playlists.exportToYoutube"),
               icon: pushing.has(pl.id) ? (
-                <Upload className="w-4 h-4 animate-pulse" />
+                <Upload className="w-4 h-4 motion-safe:animate-pulse" />
               ) : linked ? (
                 <YouTubeIcon className="w-4 h-4" />
               ) : (
diff --git a/frontend/src/lib/reducedMotion.contract.test.ts b/frontend/src/lib/reducedMotion.contract.test.ts
new file mode 100644
index 00000000..b417ea4f
--- /dev/null
+++ b/frontend/src/lib/reducedMotion.contract.test.ts
@@ -0,0 +1,34 @@
+import { readdirSync, readFileSync } from "node:fs";
+
+import { expect, it } from "vitest";
+
+// docs/DESIGN.md (Motion): `prefers-reduced-motion` is respected. A pulse that loops for as long as
+// something lasts — a running job's dot, a queued download, a skeleton bone — is the motion that rule
+// is about, and seven of them pulsed regardless. Each is `motion-safe:animate-pulse`, or pairs the
+// pulse with `motion-reduce:animate-none` on the same line.
+function sources(): Array<[string, string]> {
+  const walk = (u: URL, prefix: string): Array<[string, string]> =>
+    readdirSync(u, { withFileTypes: true }).flatMap((e) => {
+      if (e.isDirectory()) return walk(new URL(`${e.name}/`, u), `${prefix}${e.name}/`);
+      if (!/\.tsx?$/.test(e.name) || e.name.includes(".test.")) return [];
+      return [
+        [`${prefix}${e.name}`, readFileSync(new URL(e.name, u), "utf-8")] as [string, string],
+      ];
+    });
+  return walk(new URL("../", import.meta.url), "");
+}
+
+it("every looping pulse stops for a reader who asked for less motion", () => {
+  const unguarded = sources().flatMap(([name, src]) =>
+    src
+      .split("\n")
+      .map((line, i) => [line, i + 1] as const)
+      .filter(
+        ([line]) =>
+          /(?<!motion-safe:)\banimate-pulse\b/.test(line) &&
+          !line.includes("motion-reduce:animate-none"),
+      )
+      .map(([, n]) => `${name}:${n}`),
+  );
+  expect(unguarded).toEqual([]);
+});