Guide to the prefers-contrast CSS Media Query

The prefers-contrast CSS media query allows web applications to detect whether a user has requested an interface with higher or lower contrast in their system settings. This article covers how the feature works, the values it supports, how to implement it using CSS, and best practices for creating accessible web designs that automatically adapt to individual visual needs.

What Is the prefers-contrast Media Query?

Defined in the CSS Media Queries Level 5 specification, prefers-contrast is a user preference media feature. Operating systems such as Windows, macOS, iOS, and Android allow users to adjust system-wide contrast settings to improve readability or reduce eye strain. The prefers-contrast media query exposes these system-level accessibility settings directly to the browser, allowing stylesheets to dynamically adjust text contrast, borders, and background colors.

Supported Values

The prefers-contrast query accepts four values:

• no-preference: The default value. It indicates the user has not configured any specific contrast preferences in their operating system.
• more: Indicates the user has explicitly requested an interface with higher contrast, often to compensate for low vision, aging eyes, or situational impairments like bright glare.
• less: Indicates the user prefers lower contrast, which can benefit individuals sensitive to bright light, visual noise, or migraine triggers.
• custom: Matches when the user has chosen a specific palette of non-standard colors that do not strictly qualify as "more" or "less" contrast (often associated with forced-color modes).

Implementing High-Contrast Adaptations in CSS

Developers can use standard @media rules to adjust styles when a user requests increased contrast.

/* Default component styling */
.button {
  background-color: #2563eb;
  color: #ffffff;
  border: 1px solid transparent;
  padding: 0.5rem 1rem;
}

.card {
  background-color: #f8fafc;
  border: 1px solid #e2e8f0;
  color: #334155;
}

/* Enhancements for users requesting higher contrast */
@media (prefers-contrast: more) {
  .button {
    background-color: #000000;
    color: #ffffff;
    border: 2px solid #ffffff;
    outline: 2px solid #000000;
  }

  .card {
    background-color: #ffffff;
    border: 2px solid #000000;
    color: #000000;
  }
}

In this implementation, the more preference increases the visual definition of interactive elements by introducing prominent borders, darkening text, and strengthening color boundaries.

Key Strategies for Adapting to High Contrast

When catering to prefers-contrast: more, focus on structural clarity and legibility:

1. Exceed Minimum Contrast Ratios: Standard Web Content Accessibility Guidelines (WCAG) require a minimum contrast ratio of 4.5:1 for normal text (AA level). For the more state, aim for AAA compliance, which requires a minimum ratio of 7:1.
2. Add Explicit Borders: Low-contrast designs often rely on subtle drop shadows or light background shifts to separate components. High-contrast styles should replace or reinforce these with distinct, solid borders.
3. Strengthen Focus States: Enhance focus and active rings around links, buttons, and form inputs so keyboard users with visual impairments can track navigation easily.
4. Avoid Relying Solely on Color: Use icons, underlines for links, or bold typography alongside contrast changes to convey state and hierarchy.

Implementation Considerations

While prefers-contrast provides a way to deliver enhanced visibility, base styles must still adhere to standard accessibility guidelines. The media query should enhance an already accessible experience rather than fix an inherently inaccessible default design. Developers should test their implementations across multiple operating systems and browser developer tools to verify that contrast adaptations trigger correctly.