| name | user-preference-respect |
| description | Design interfaces that detect and respond to system-level user preferences. Use when implementing dark mode, reduced motion, high contrast, text scaling, or any user preference that affects how the interface renders. Triggers on: user preference, system preference, prefers-reduced-motion, prefers-contrast, prefers-color-scheme, forced-colors, media query, user settings, system settings, accessibility settings, OS settings. |
User Preference Respect
The operating system already knows what the user needs. Your job is
to listen and respond. These preferences exist because people set them
deliberately — ignoring them overrides the user's own accessibility
decision.
The Preferences
prefers-reduced-motion
What it means: user experiences discomfort or harm from motion.
What to do:
- Disable all decorative animation
- Replace slide/fade transitions with instant state changes
- Keep essential motion (loading spinners) but simplify
- Disable parallax, scroll-triggered animation, and auto-advance
- Never override this preference
How to detect: @media (prefers-reduced-motion: reduce)
prefers-contrast
What it means: user needs stronger visual distinction.
What to do:
- Increase contrast beyond WCAG minimums
- Replace subtle shadows and gradients with solid borders
- Make focus indicators bolder and more visible
- Remove transparency and blur effects
- Increase border widths on interactive elements
How to detect: @media (prefers-contrast: more)
prefers-color-scheme
What it means: user prefers light or dark interface.
What to do:
- Provide genuine dark mode (not just inverted colours)
- Ensure all content is legible in both modes
- Test images, charts, icons, and illustrations in both
- Don't use pure black (#000) on dark mode — use dark grey (#1a1a1a)
for less eye strain
- Remember: dark mode is not just aesthetic — it reduces eye
fatigue and helps some people with light sensitivity
How to detect: @media (prefers-color-scheme: dark)
forced-colors
What it means: user has enabled Windows High Contrast or similar.
What to do:
- Don't fight the system colour override
- Ensure borders and outlines define interactive elements
(the system will strip your colours)
- Use transparent borders that become visible in forced-colors mode
- Test that all interactive elements remain distinguishable
- Don't rely on background colour alone to indicate state
How to detect: @media (forced-colors: active)
prefers-reduced-transparency
What it means: user finds transparent elements hard to read.
What to do:
- Replace semi-transparent backgrounds with solid ones
- Remove frosted glass / backdrop blur effects
- Ensure overlays are fully opaque
How to detect: @media (prefers-reduced-transparency: reduce)
Implementation Principles
Progressive Enhancement
- Build the accessible version first
- Add motion, transparency, and visual flourishes as enhancements
- When a preference is detected, you're removing the enhancement,
not degrading the experience
Don't Ask — Detect
- Don't make users configure accessibility settings in your app
when the OS already has the setting
- Detect and respond automatically
- If you offer additional settings, they should layer on top of
system preferences, not replace them
Test Every Preference
- Test with each preference enabled individually
- Test with combinations (reduced motion + high contrast + dark mode)
- Verify that the interface is complete and usable in every state
- Automated tests can check that media queries exist —
manual testing verifies they work
Assessment Checklist
