How to Inspect and Debug CSS prefers-contrast Media Queries in Safari Web Inspector

Modern operating systems—such as macOS and iOS—provide system-wide accessibility toggles (such as “Increase contrast” under Apple Display settings) that enhance visual legibility for individuals with low vision, contrast sensitivity, or situational impairments like bright sunlight. In responsive web design, tailoring typography, borders, and interactive outlines to these accessibility preferences is essential for meeting Web Content Accessibility Guidelines (WCAG) AAA standards. Through the CSS Media Queries Level 5 prefers-contrast media feature, web developers can adjust interface contrast dynamically based on user preferences. Safari Web Inspector includes dedicated media feature emulation, allowing engineers to preview and debug high and low contrast styling directly within the browser on macOS.

Understanding the CSS prefers-contrast Media Feature

The prefers-contrast media feature detects whether a user has requested an interface with increased or decreased contrast levels relative to adjacent background surfaces. It evaluates to four standardized values:

• no-preference: The user has not configured any accessibility contrast preferences. The standard design system baseline is applied.
• more: The user has explicitly enabled increased contrast (e.g. macOS “Increase contrast” enabled). Borders should be sharpened, subtle grey text darkened to pure black (or brightened in dark modes), and decorative low-contrast gradients replaced with solid fills.
• less: The user prefers reduced contrast (helpful for individuals with migraines or photophobia triggered by harsh white-on-black text).
• custom: The user is utilizing a specific, non-standard palette (such as Windows High Contrast Mode or forced colour palettes).

Implementing Accessible Styles with prefers-contrast

In modern CSS, subtle shadows and faint borders that appear elegant on high-end displays can become completely illegible for users with visual impairments. Using @media (prefers-contrast: more), you can reinforce interactive affordances without compromising the default design for other users.

/* Standard baseline component styling */
.card {
    background-color: #ffffff;
    border: 1px solid #e5e7eb;
    box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
    color: #4b5563;
}

.button-primary {
    background-color: #3b82f6;
    color: #ffffff;
    border: 2px solid transparent;
}

/* High contrast accessibility adjustments */
@media (prefers-contrast: more) {
    .card {
        /* Eliminate subtle box shadows in favour of distinct solid borders */
        box-shadow: none;
        border: 2px solid #000000;
        color: #000000;
    }

    .button-primary {
        background-color: #000000;
        color: #ffffff;
        border: 2px solid #ffffff;
        outline: 2px solid #000000;
        outline-offset: 2px;
        font-weight: 700;
    }

    /* Sharpen link text and ensure explicit underlines */
    a {
        text-decoration: underline !important;
        text-underline-offset: 4px;
        font-weight: 600;
    }
}

/* Reduced contrast styling for sensitive visual conditions */
@media (prefers-contrast: less) {
    .card {
        background-color: #f9fafb;
        border-color: #d1d5db;
        color: #374151;
    }
}

Enabling Safari Web Inspector for Accessibility Auditing

To access media emulation tools in Safari, ensure developer features are visible on macOS:

• Open Safari on macOS.
• Go to Safari > Settings > Advanced.
• Tick Show features for web developers.
• Right-click any page element and choose Inspect Element to launch Web Inspector.

Emulating prefers-contrast Using Web Inspector Device Controls

Safari Web Inspector allows web developers to toggle contrast preferences instantly without altering macOS system-wide preferences:

• In Web Inspector, look for the Develop menu bar or the Elements tab header bar.
• Locate the Media Features Emulation icon (often displayed as a small gauge or eye icon in the toolbar).
• Under the prefers-contrast dropdown menu, choose more or less.
• Observe how the active page DOM instantly recalculates styles matching @media (prefers-contrast: more).

Auditing Computed Properties and Contrast Ratios

With high contrast emulation active in Web Inspector, audit the CSS cascade:

• Select an altered component (such as .button-primary) in the DOM tree.
• In the Styles panel on the right sidebar, verify that the @media (prefers-contrast: more) rule block is active and overrides lower-specificity utility classes.
• Inspect the Computed panel to verify that colours resolve to accessible values.
• In Safari Web Inspector’s Accessibility tab (or Color Picker inspector), observe the calculated contrast ratio against the background. WCAG AAA requires a minimum contrast ratio of 7:1 for normal text and 4.5:1 for large text.

Validating prefers-contrast Evaluation via JavaScript Console

To programmatically test whether the browser correctly detects contrast changes:

// Evaluate prefers-contrast state in the Web Inspector Console
const contrastQuery = window.matchMedia('(prefers-contrast: more)');
console.log('High contrast active:', contrastQuery.matches);

// Listen for live contrast emulation changes
contrastQuery.addEventListener('change', (e) => {
    console.log('prefers-contrast status changed to:', e.matches ? 'more' : 'standard');
});

Testing Native System Contrast Toggles in macOS

To verify end-to-end integration with native operating system accessibility controls:

• Open System Settings > Accessibility > Display on macOS.
• Toggle the switch labelled Increase contrast.
• Notice how window borders and button outlines sharpen system-wide.
• Switch back to Safari: WebKit immediately dispatches a media query change event and applies high-contrast styling across open browser tabs without requiring a page refresh.

Leveraging prefers-contrast in Safari Web Inspector ensures that digital products are welcoming, visually distinct, and accessible to learners and professionals of all visual abilities.