prefers-reduced-motion

[dgrahn]

Hi all!

While exploring OpenSpec, I noticed that there's a pretty strong animation at the start of openspec init. As someone who lives in a household full of medically complex people, I'm pretty tuned into accessibility challenges. I noticed two challenges with this animation:

1. Flashing -- flashing elements can be a seizure trigger. The flashing occurs on the top- and bottom-left of the interface where the cursor is clearing.
2. Animation -- animated elements can trigger nausea, create sensory overload, etc.

While it is technically possible to check the system-level motion preference, I'm not sure that this is something which is suitable for a CLI tool. I'd propose one of two changes:

1. Remove the animation, replace with cool static-art.
2. Add a --no-animation flag to the CLI which allows users to disable the animation.

I know requests like this can sometimes feel small and silly, but it makes a real difference in the lives of people who use tools. Thanks for considering!

[1code-async]

Task completed.

The enrichment comment has been posted on issue #722. Here's a summary of what was included:

Key findings:

• The animation lives in src/ui/welcome-screen.ts (8-frame ASCII art at 120ms intervals) and src/ui/ascii-patterns.ts
• Progress spinners in src/core/init.ts use ora with a custom 80ms block-character spinner
• The cursor-clearing ANSI escape sequences (\x1b[…A, \x1b[2K) cause the flicker the author describes

Existing workarounds were documented — --no-color, NO_COLOR env var, non-TTY detection, and CI env var all implicitly disable the welcome animation, but none are purpose-built for motion accessibility.

Three implementation approaches were suggested: respecting system prefers-reduced-motion, adding an explicit --no-animation flag, or both. No duplicate issues were found.

---

View full conversation

Powered by 1Code

[1code-async]

Issue Analysis

Thanks for raising this accessibility concern. Here's a breakdown of the relevant code and potential approaches.

Affected Code

Welcome screen animation — src/ui/welcome-screen.ts

• The showWelcomeScreen() function (line 121) runs an 8-frame ASCII art animation at 120ms intervals using setInterval (line 146).
• Each frame cycle uses ANSI escape sequences (\x1b[…A, \x1b[2K) to overwrite previous output (lines 152-154, 173-176), which causes the cursor-clearing flicker described in the issue.
• The animation frames are defined in src/ui/ascii-patterns.ts (lines 31-136) — a diamond/rhombus logo that builds from center outward across 8 frames.

Progress spinners — src/core/init.ts

• A custom PROGRESS_SPINNER with block characters at 80ms intervals (lines 54-57) is used during directory creation and tool setup.
• These use ora spinners throughout the init flow (lines 389-405, 432-476, 195-209).

Existing Workarounds

The codebase already has some implicit animation controls, but no explicit --no-animation flag:

Method	Effect	File
--no-color flag	Sets NO_COLOR=1, disables welcome animation	src/cli/index.ts:65
NO_COLOR env var	Checked by canAnimate(), falls back to static frame	src/ui/welcome-screen.ts:68
Non-TTY / piped output	canAnimate() returns false	src/ui/welcome-screen.ts:65
CI env var	Disables interactive mode entirely	src/utils/interactive.ts:26
OPEN_SPEC_INTERACTIVE=0	Disables interactive mode	src/utils/interactive.ts:24

When animation is disabled, canAnimate() triggers a static fallback that renders a single frame (frame index 3) at welcome-screen.ts:124-129.

Suggested Implementation Approaches

Option A: Respect prefers-reduced-motion system setting

Node.js doesn't natively expose prefers-reduced-motion, but on Linux/macOS this can be detected by querying desktop environment settings (e.g., gsettings on GNOME, accessibility APIs on macOS). The is-reduced-motion or similar npm packages could help. This check could be added to canAnimate() in welcome-screen.ts:63-75.

Option B: Add --no-animation CLI flag

Add a global --no-animation option alongside the existing --no-color in src/cli/index.ts:65. The preAction hook (line 71) could set an environment variable (e.g., OPENSPEC_NO_ANIMATION=1), which canAnimate() and the ora spinner instantiation in init.ts could check.

Option C: Both A and B

Check system prefers-reduced-motion automatically AND provide --no-animation as an explicit override. This is the most accessible approach.

No Duplicate Issues Found

No existing issues in this repository cover animation accessibility, reduced motion, or flashing concerns.

Additional Notes

• The NO_COLOR workaround already available today will disable the welcome animation but also strips all color from output, which is a broader change than necessary.
• The ora spinners used throughout init.ts would also benefit from a no-animation mode (replacing spinners with static progress text).
• The NO_COLOR standard is a good precedent — a similar NO_ANIMATION or OPENSPEC_REDUCE_MOTION env var convention would align with that philosophy.

[alfred-openspec]

Thank you for opening this, Dan. Accessibility isn't an afterthought for us — this should absolutely work out of the box for folks who need reduced motion.

The fix is straightforward since canAnimate() already has fallback logic. We'll make sure it respects prefers-reduced-motion and add a --no-animation flag / OPENSPEC_NO_ANIMATION env var as a manual override too.

Appreciate you taking the time to write such a clear, detailed report. 🙏