From fc550573de38873ab101f00264bf98922d280401 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 12 May 2026 20:15:56 -0700
Subject: [PATCH 1/3] docs: spec for prefers-reduced-motion audit (Phase 5)

Single @media block injected via ROOT_TOKEN_STYLES collapses all 77
chat + a2ui motion sites to instant, with targeted static fallbacks
for the six infinite-loop indicators.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 ...026-05-12-prefers-reduced-motion-design.md | 149 ++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md

diff --git a/docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md b/docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md
new file mode 100644
index 00000000..44ad2b75
--- /dev/null
+++ b/docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md
@@ -0,0 +1,149 @@
+# Prefers-Reduced-Motion Audit — Design
+
+**Status:** Approved
+**Date:** 2026-05-12
+**Scope:** `libs/chat` (primitives, compositions, styles, a2ui catalog)
+**Out of scope:** marketing website (`apps/website`), other libs
+
+## Goal
+
+Honor the user's `prefers-reduced-motion: reduce` OS-level setting across every chat surface. WCAG 2.3.3 compliance. No JavaScript involvement — pure CSS.
+
+## Background
+
+`libs/chat` currently has 77 motion declarations across primitives, compositions, styles, and the a2ui catalog: transitions on hover/focus, transform-based drawer slides, mount animations, and six infinite-loop indicators. Zero existing `prefers-reduced-motion` media queries.
+
+The a2ui catalog uses three tokenized durations (`--a2ui-motion-duration-{short,medium,long}`) defined in the optional `chat.css`. Everything else is hardcoded (`200ms ease`, `cubic-bezier(...)`, etc.). No unified chat motion-duration token exists.
+
+## Decisions Locked During Brainstorming
+
+| Decision | Choice |
+|---|---|
+| Scope | `libs/chat` end-to-end (primitives + compositions + a2ui catalog) |
+| Approach | Blanket override via a single `@media (prefers-reduced-motion: reduce)` block |
+| Loop animations | Static fallback (`animation: none`), not slowed or kept |
+| Injection point | `ROOT_TOKEN_STYLES` in `libs/chat/src/lib/styles/chat-tokens.ts` (auto-injected at document root) |
+
+## Architecture
+
+Single CSS block appended to the existing `ROOT_TOKEN_STYLES` constant in `libs/chat/src/lib/styles/chat-tokens.ts`. The chat library already injects this stylesheet into the document head on first component bootstrap. The a2ui catalog renders inside the same document, so a universal selector reaches both lib surfaces.
+
+No new TypeScript, no new file, no consumer migration required. The change is invisible to chat consumers — opt-in by the OS, not the integrator.
+
+## The Media Block
+
+Appended to `ROOT_TOKEN_STYLES` after the existing `@keyframes` definitions:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  /* Universal — collapses all transitions/animations to instant.
+     `!important` overrides component-scoped inline styles; intentional
+     for accessibility. */
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  /* Loop indicators — static fallback instead of frozen mid-loop.
+     Loading state remains accessible via aria-busy / surrounding text. */
+  .tcc__pill[data-status="running"] svg,
+  .ngaf-chat-typing-dot,
+  .ngaf-chat-caret,
+  .ngaf-chat-welcome__pulse,
+  .chat-genui-skeleton,
+  .chat-debug__pill--active {
+    animation: none !important;
+    opacity: 1 !important;
+  }
+
+  /* Spinner SVG: also cancel any inline transform applied by the
+     animation's last frame. */
+  .tcc__pill[data-status="running"] svg {
+    transform: none !important;
+  }
+}
+```
+
+## Components Affected
+
+The universal rule covers all 77 sites without per-component edits. The targeted overrides handle the six infinite loops:
+
+| Selector | Original loop | Static fallback |
+|---|---|---|
+| `.tcc__pill[data-status="running"] svg` | `tcc-spin` (rotate, 0.8s) | No rotation; spinner rests in default orientation |
+| `.ngaf-chat-typing-dot` | `ngaf-chat-typing-dot` (opacity, 1.4s) | Three steady dots at full opacity |
+| `.ngaf-chat-caret` | `ngaf-chat-caret-blink` + `caret-fade-in` | Solid caret while streaming |
+| `.ngaf-chat-welcome__pulse` | `ngaf-chat-pulse` (2s) | Static element |
+| `.chat-genui-skeleton` | `chat-genui-skeleton-shimmer` (1.4s) | Flat placeholder rectangle |
+| `.chat-debug__pill--active` | `chat-debug-pill-pulse` (1.2s) | Static pill |
+
+Mount animations (`chat-debug-panel-enter`, `ngaf-chat-welcome-mount`) and transform-based slides (sidenav drawer, sidebar, popup, interrupt panel, scroll bubble) get the universal `transition-duration: 0.01ms` / `animation-duration: 0.01ms` treatment — they snap to their target state instead of animating.
+
+## Data Flow
+
+None. The CSS media query is reactive at the rendering-engine level. OS setting changes propagate to all open tabs without app involvement. No subscription, no signal, no JavaScript.
+
+## Error Handling
+
+None needed.
+
+- Engines that don't recognize `prefers-reduced-motion` silently ignore the block (very old browsers — well outside ngaf's support matrix).
+- The `!important` flag will override any inline `style="transition: ..."` that future code might write. That's intentional and called out via comment in the block.
+
+## Testing
+
+### Unit test
+
+Extend `libs/chat/src/lib/styles/chat-tokens.spec.ts` with one assertion:
+
+```ts
+it('includes a prefers-reduced-motion media block in ROOT_TOKEN_STYLES', () => {
+  expect(ROOT_TOKEN_STYLES).toContain('@media (prefers-reduced-motion: reduce)');
+  expect(ROOT_TOKEN_STYLES).toMatch(/\*,\s*\*::before,\s*\*::after/);
+  expect(ROOT_TOKEN_STYLES).toContain('animation-duration: 0.01ms');
+  expect(ROOT_TOKEN_STYLES).toContain('transition-duration: 0.01ms');
+});
+```
+
+Smoke-level — verifies wiring, not CSS semantics (jsdom can't simulate the media query reliably).
+
+### Manual verification
+
+Documented in the PR description as a checklist:
+
+1. **macOS:** System Settings → Accessibility → Display → Reduce Motion → on.
+2. **Reload** the chat example at `localhost:4200`.
+3. Confirm:
+   - Sidenav drawer snaps open/closed (no slide-in).
+   - Typing dots are three steady dots (no blink).
+   - Tool-call spinner is a static SVG (no rotation).
+   - Welcome pulse off.
+   - Shimmer skeleton is flat.
+   - Debug panel snaps in (no fade).
+   - Drag-to-reorder pinned threads still works (grip transitions are instant; drop indicator still visible).
+4. **Toggle off**, reload, confirm all motion returns.
+
+Skipping Playwright e2e — the value-add vs. manual verification for "does this *look* right" is low.
+
+## Scope Boundaries
+
+**In scope:**
+- `libs/chat/src/lib/styles/chat-tokens.ts` (CSS block + comment)
+- `libs/chat/src/lib/styles/chat-tokens.spec.ts` (one new assertion)
+- This spec doc + implementation plan
+- PR description with manual verification checklist
+
+**Out of scope (deferred):**
+- Refactoring the 77 hardcoded motion sites to use a unified token (no consumer-facing benefit; large diff).
+- Marketing website motion (`apps/website` — separate phase, scroll/parallax concerns).
+- New design-token surface for motion.
+- JavaScript-side reduced-motion detection (none of our motion is JS-driven).
+- E2E test using Playwright's `prefers-reduced-motion` emulation.
+
+## References
+
+- WCAG 2.3.3 Animation from Interactions
+- MDN: `prefers-reduced-motion`
+- W3C: Understanding Success Criterion 2.3.3

From 0c76c6564fe54ddd01b84ba8b4af05c1886be7b0 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 12 May 2026 20:18:10 -0700
Subject: [PATCH 2/3] docs: implementation plan for prefers-reduced-motion
 audit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Single-task TDD plan: failing spec → export ROOT_TOKEN_STYLES → add
@media block → confirm pass → manual smoke → PR.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../2026-05-12-prefers-reduced-motion.md      | 260 ++++++++++++++++++
 1 file changed, 260 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-05-12-prefers-reduced-motion.md

diff --git a/docs/superpowers/plans/2026-05-12-prefers-reduced-motion.md b/docs/superpowers/plans/2026-05-12-prefers-reduced-motion.md
new file mode 100644
index 00000000..5f8997cb
--- /dev/null
+++ b/docs/superpowers/plans/2026-05-12-prefers-reduced-motion.md
@@ -0,0 +1,260 @@
+# Prefers-Reduced-Motion Audit Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Honor `prefers-reduced-motion: reduce` across `libs/chat` (including a2ui catalog) by injecting one CSS media block at the document root.
+
+**Architecture:** Single `@media (prefers-reduced-motion: reduce)` block appended to the existing `ROOT_TOKEN_STYLES` in `libs/chat/src/lib/styles/chat-tokens.ts`. Universal `*, *::before, *::after` selector collapses all transition/animation durations to `0.01ms` with `!important`. Six targeted overrides replace infinite-loop indicators (spinner, typing dots, caret, welcome pulse, shimmer skeleton, debug pulse) with static fallbacks via `animation: none !important; opacity: 1 !important`.
+
+**Tech Stack:** TypeScript template literals (CSS-in-TS), vitest, Angular 21 (jsdom test environment).
+
+**Reference spec:** `docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md`
+
+---
+
+### Task 1: Add reduced-motion CSS block
+
+**Files:**
+- Create: `libs/chat/src/lib/styles/chat-tokens.spec.ts`
+- Modify: `libs/chat/src/lib/styles/chat-tokens.ts`
+
+**Context for the implementer:**
+
+`ROOT_TOKEN_STYLES` in `chat-tokens.ts` is currently a non-exported `const` (around line 141). The function `ensureChatRootStyles()` injects it as a `<style id="ngaf-chat-root-tokens">` into `<head>` on first chat-component construction. To assert on the content cleanly from a test, **export** `ROOT_TOKEN_STYLES` as a `const`. This is a low-risk addition (it's a CSS string, not behavior).
+
+The `chat-tokens.ts` file has no companion `.spec.ts` yet — you are creating the first one. Use vitest (the chat lib already uses it; see other `.spec.ts` files in `libs/chat/src/lib/primitives/` for patterns).
+
+The six infinite-loop selectors come from the spec table; they appear in:
+- `libs/chat/src/lib/compositions/chat-tool-call-card/chat-tool-call-card.component.ts` → `.tcc__pill[data-status="running"] svg`
+- `libs/chat/src/lib/styles/chat-scroll-bubble.styles.ts` → `.ngaf-chat-typing-dot`
+- `libs/chat/src/lib/styles/chat-message.styles.ts` → `.ngaf-chat-caret`
+- `libs/chat/src/lib/styles/chat-welcome.styles.ts` → `.ngaf-chat-welcome__pulse`
+- `libs/chat/src/lib/primitives/chat-genui-skeleton/chat-genui-skeleton.component.ts` → `.chat-genui-skeleton`
+- `libs/chat/src/lib/compositions/chat-debug/chat-debug.component.ts` → `.chat-debug__pill--active`
+
+Do NOT modify any of those component/styles files. The selectors are stable and the override goes in `chat-tokens.ts`.
+
+---
+
+- [ ] **Step 1: Create the failing test**
+
+Create `libs/chat/src/lib/styles/chat-tokens.spec.ts`:
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { ROOT_TOKEN_STYLES } from './chat-tokens';
+
+describe('ROOT_TOKEN_STYLES — prefers-reduced-motion', () => {
+  it('includes a prefers-reduced-motion media block', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('@media (prefers-reduced-motion: reduce)');
+  });
+
+  it('applies a universal selector inside the media block', () => {
+    expect(ROOT_TOKEN_STYLES).toMatch(/\*,\s*\*::before,\s*\*::after/);
+  });
+
+  it('collapses animation-duration to 0.01ms', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('animation-duration: 0.01ms');
+  });
+
+  it('collapses transition-duration to 0.01ms', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('transition-duration: 0.01ms');
+  });
+
+  it('caps animation-iteration-count to 1', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('animation-iteration-count: 1');
+  });
+
+  it('forces auto scroll-behavior', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('scroll-behavior: auto');
+  });
+
+  it.each([
+    '.tcc__pill[data-status="running"] svg',
+    '.ngaf-chat-typing-dot',
+    '.ngaf-chat-caret',
+    '.ngaf-chat-welcome__pulse',
+    '.chat-genui-skeleton',
+    '.chat-debug__pill--active',
+  ])('includes static-fallback override for %s', (selector) => {
+    expect(ROOT_TOKEN_STYLES).toContain(selector);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd libs/chat && npx vitest run src/lib/styles/chat-tokens.spec.ts`
+
+Expected: FAIL with `SyntaxError: The requested module './chat-tokens' does not provide an export named 'ROOT_TOKEN_STYLES'`
+
+- [ ] **Step 3: Export ROOT_TOKEN_STYLES**
+
+In `libs/chat/src/lib/styles/chat-tokens.ts`, change the declaration:
+
+```ts
+const ROOT_TOKEN_STYLES = `
+```
+
+to:
+
+```ts
+export const ROOT_TOKEN_STYLES = `
+```
+
+(Single keyword addition; nothing else changes about the constant itself.)
+
+- [ ] **Step 4: Run tests again to confirm new failures are on content, not on import**
+
+Run: `cd libs/chat && npx vitest run src/lib/styles/chat-tokens.spec.ts`
+
+Expected: FAIL — all assertions about the `@media` block fail because the block doesn't exist yet. Import error is gone.
+
+- [ ] **Step 5: Add the reduced-motion media block**
+
+In `libs/chat/src/lib/styles/chat-tokens.ts`, locate the `ROOT_TOKEN_STYLES` template literal. It currently ends with:
+
+```ts
+}
+${KEYFRAMES}
+`;
+```
+
+Replace that closing region with:
+
+```ts
+}
+${KEYFRAMES}
+${REDUCED_MOTION_STYLES}
+`;
+```
+
+Then, immediately above the `const ROOT_TOKEN_STYLES = \`` line, add:
+
+```ts
+/**
+ * WCAG 2.3.3 — honor the OS-level "Reduce Motion" preference. Collapses
+ * every transition/animation in the chat lib (and the a2ui catalog,
+ * which renders in the same document) to instant. The `!important`
+ * flag intentionally overrides any inline `style="transition: ..."`
+ * applied by future code — accessibility wins.
+ *
+ * Infinite-loop indicators (spinner, typing dots, caret, etc.) need
+ * explicit `animation: none` because `iteration-count: 1` alone would
+ * freeze them mid-loop, which reads as a bug.
+ */
+const REDUCED_MOTION_STYLES = `
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  .tcc__pill[data-status="running"] svg,
+  .ngaf-chat-typing-dot,
+  .ngaf-chat-caret,
+  .ngaf-chat-welcome__pulse,
+  .chat-genui-skeleton,
+  .chat-debug__pill--active {
+    animation: none !important;
+    opacity: 1 !important;
+  }
+
+  .tcc__pill[data-status="running"] svg {
+    transform: none !important;
+  }
+}
+`;
+```
+
+- [ ] **Step 6: Run tests to verify they pass**
+
+Run: `cd libs/chat && npx vitest run src/lib/styles/chat-tokens.spec.ts`
+
+Expected: PASS — all 12 assertions green.
+
+- [ ] **Step 7: Run the full chat suite to confirm no regression**
+
+Run: `cd libs/chat && npx vitest run`
+
+Expected: PASS — every chat spec passes (the change is additive to one CSS string).
+
+- [ ] **Step 8: Manual smoke verification**
+
+(If the implementer can run the dev server, perform this. Otherwise document in PR description for the reviewer.)
+
+1. `npx nx serve chat-angular` (or the equivalent for the local example app).
+2. macOS: System Settings → Accessibility → Display → **Reduce Motion** → on.
+3. Reload `http://localhost:4200`.
+4. Confirm:
+   - Sidenav drawer snaps open/closed (no slide-in).
+   - Tool-call spinner is a static SVG (no rotation).
+   - Typing dots are three steady dots (no pulse).
+   - Welcome pulse off.
+   - Shimmer skeleton flat.
+   - Drag-to-reorder pinned threads: grip handles still appear; drop indicator visible; row reorders instantly on drop.
+5. Toggle **Reduce Motion** off, reload, confirm motion returns.
+
+If anything above doesn't behave as listed, STOP and report. The fix likely belongs in the targeted-selector list, not the universal rule.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add libs/chat/src/lib/styles/chat-tokens.ts libs/chat/src/lib/styles/chat-tokens.spec.ts
+git commit -m "$(cat <<'EOF'
+feat(chat): honor prefers-reduced-motion across chat + a2ui
+
+Single @media block injected via ROOT_TOKEN_STYLES collapses every
+transition/animation to instant under the user's OS-level "Reduce
+Motion" setting. Targeted overrides replace six infinite-loop
+indicators (spinner, typing dots, caret, welcome pulse, shimmer
+skeleton, debug pulse) with static fallbacks — frozen mid-loop reads
+as a bug.
+
+WCAG 2.3.3 compliance. No JS, no consumer changes, no new tokens.
+
+EOF
+)"
+```
+
+- [ ] **Step 10: Push and open PR**
+
+```bash
+git push -u origin claude/prefers-reduced-motion
+gh pr create --title "feat(chat): honor prefers-reduced-motion across chat + a2ui" --body "$(cat <<'EOF'
+## Summary
+
+- Adds a single `@media (prefers-reduced-motion: reduce)` block to `ROOT_TOKEN_STYLES`
+- Collapses all 77 chat + a2ui transition/animation sites to instant via universal selector
+- Replaces six infinite-loop indicators with static fallbacks (frozen mid-rotation reads as a bug)
+- Zero new tokens, zero consumer-facing API changes
+
+## Spec
+
+`docs/superpowers/specs/2026-05-12-prefers-reduced-motion-design.md`
+
+## Test plan
+
+- [x] Unit: 12 assertions on `ROOT_TOKEN_STYLES` content (vitest)
+- [ ] Manual: macOS → System Settings → Accessibility → Display → Reduce Motion → on
+  - [ ] Sidenav drawer snaps open/closed (no slide)
+  - [ ] Tool-call spinner static
+  - [ ] Typing dots steady (no pulse)
+  - [ ] Welcome pulse off
+  - [ ] Shimmer skeleton flat
+  - [ ] Drag-to-reorder pinned threads still works
+  - [ ] Toggle off → motion returns
+EOF
+)"
+```
+
+---
+
+## Self-review notes
+
+- **Spec coverage:** every spec section (architecture, components, data flow, error handling, testing, scope boundaries) maps to a concrete step in Task 1.
+- **No placeholders:** every code block is final content the implementer pastes verbatim.
+- **Type consistency:** the only exported symbol is `ROOT_TOKEN_STYLES` (string) — already used in the same file's `ensureChatRootStyles()`. No type drift.
+- **Single-task:** the work genuinely is one TDD cycle. Splitting into two would create artificial granularity.

From 3cb029cf371e130105f0e3cf194c20ce02f171f5 Mon Sep 17 00:00:00 2001
From: Brian Love <brian@liveloveapp.com>
Date: Tue, 12 May 2026 20:22:12 -0700
Subject: [PATCH 3/3] feat(chat): honor prefers-reduced-motion across chat +
 a2ui
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Single @media block injected via ROOT_TOKEN_STYLES collapses every
transition/animation to instant under the user's OS-level "Reduce
Motion" setting. Targeted overrides replace six infinite-loop
indicators (spinner, typing dots, caret, welcome pulse, shimmer
skeleton, debug pulse) with static fallbacks — frozen mid-loop reads
as a bug.

WCAG 2.3.3 compliance. No JS, no consumer changes, no new tokens.
---
 libs/chat/src/lib/styles/chat-tokens.spec.ts | 41 ++++++++++++++++++++
 libs/chat/src/lib/styles/chat-tokens.ts      | 39 ++++++++++++++++++-
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 libs/chat/src/lib/styles/chat-tokens.spec.ts

diff --git a/libs/chat/src/lib/styles/chat-tokens.spec.ts b/libs/chat/src/lib/styles/chat-tokens.spec.ts
new file mode 100644
index 00000000..7121404b
--- /dev/null
+++ b/libs/chat/src/lib/styles/chat-tokens.spec.ts
@@ -0,0 +1,41 @@
+// libs/chat/src/lib/styles/chat-tokens.spec.ts
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { ROOT_TOKEN_STYLES } from './chat-tokens';
+
+describe('ROOT_TOKEN_STYLES — prefers-reduced-motion', () => {
+  it('includes a prefers-reduced-motion media block', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('@media (prefers-reduced-motion: reduce)');
+  });
+
+  it('applies a universal selector inside the media block', () => {
+    expect(ROOT_TOKEN_STYLES).toMatch(/\*,\s*\*::before,\s*\*::after/);
+  });
+
+  it('collapses animation-duration to 0.01ms', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('animation-duration: 0.01ms');
+  });
+
+  it('collapses transition-duration to 0.01ms', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('transition-duration: 0.01ms');
+  });
+
+  it('caps animation-iteration-count to 1', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('animation-iteration-count: 1');
+  });
+
+  it('forces auto scroll-behavior', () => {
+    expect(ROOT_TOKEN_STYLES).toContain('scroll-behavior: auto');
+  });
+
+  it.each([
+    '.tcc__pill[data-status="running"] svg',
+    '.ngaf-chat-typing-dot',
+    '.ngaf-chat-caret',
+    '.ngaf-chat-welcome__pulse',
+    '.chat-genui-skeleton',
+    '.chat-debug__pill--active',
+  ])('includes static-fallback override for %s', (selector) => {
+    expect(ROOT_TOKEN_STYLES).toContain(selector);
+  });
+});
diff --git a/libs/chat/src/lib/styles/chat-tokens.ts b/libs/chat/src/lib/styles/chat-tokens.ts
index 2438b0aa..8cdd66f1 100644
--- a/libs/chat/src/lib/styles/chat-tokens.ts
+++ b/libs/chat/src/lib/styles/chat-tokens.ts
@@ -126,6 +126,42 @@ export const CHAT_HOST_TOKENS = `
 // ROOT_TOKEN_STYLES below so the names match what `animation: ngaf-chat-*`
 // references in component styles (which Angular leaves untouched).
 
+/**
+ * WCAG 2.3.3 — honor the OS-level "Reduce Motion" preference. Collapses
+ * every transition/animation in the chat lib (and the a2ui catalog,
+ * which renders in the same document) to instant. The `!important`
+ * flag intentionally overrides any inline `style="transition: ..."`
+ * applied by future code — accessibility wins.
+ *
+ * Infinite-loop indicators (spinner, typing dots, caret, etc.) need
+ * explicit `animation: none` because `iteration-count: 1` alone would
+ * freeze them mid-loop, which reads as a bug.
+ */
+const REDUCED_MOTION_STYLES = `
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+
+  .tcc__pill[data-status="running"] svg,
+  .ngaf-chat-typing-dot,
+  .ngaf-chat-caret,
+  .ngaf-chat-welcome__pulse,
+  .chat-genui-skeleton,
+  .chat-debug__pill--active {
+    animation: none !important;
+    opacity: 1 !important;
+  }
+
+  .tcc__pill[data-status="running"] svg {
+    transform: none !important;
+  }
+}
+`;
+
 /**
  * Token defaults written to `<head>` once on first chat-component
  * construction. Wrapped in `@layer ngaf-chat` so the consumer's unlayered
@@ -138,7 +174,7 @@ export const CHAT_HOST_TOKENS = `
  *     forces dark.
  *   - `[data-ngaf-chat-theme="light"]` forces light.
  */
-const ROOT_TOKEN_STYLES = `
+export const ROOT_TOKEN_STYLES = `
 @layer ngaf-chat {
   :root {
     ${LIGHT_TOKENS}
@@ -155,6 +191,7 @@ const ROOT_TOKEN_STYLES = `
   [data-ngaf-chat-theme="dark"] { ${DARK_TOKENS} }
 }
 ${KEYFRAMES}
+${REDUCED_MOTION_STYLES}
 `;
 
 const STYLE_ELEMENT_ID = 'ngaf-chat-root-tokens';