Focus outlines of form elements on media grid images have a too low color contrast

Created on 13 February 2025, 5 months ago

Problem/Motivation

By placing the checkbox and the two buttons in front of the images on the media grid page it is close to impossible to guarantee that if one of these elements gets into focus that the focus outline has a high enough color contrast. The background aka the images will always be heterogenous and inconsistent.

Discussed and iterated on the issue with @mgifford, @the_g_bomb, @katannshaw, and @drupa11y

Steps to reproduce

  • Go to admin/content/media-grid and try to navigate the media grid by keyboard by tabbing through the focusable elements.

Proposed resolution

  • Try to ensure that the color contrast of the focus colors and the accent colors in dark and light mode is larger than 3:1 against the background, which is close to impossible. The only potential way might be in contrast to the proposed resolution in [#Improve the accessibility of the focus outlines] which recommends only using a single colored solid outline to make an exception and to go with two outline colors in this case, so at least one of them is meeting or is at least close to the required color contrast.

Remaining tasks

User interface changes

API changes

Data model changes

🐛 Bug report
Status

Active

Version

4.0

Component

User interface

Created by

🇩🇪Germany rkoller Nürnberg, Germany

Live updates comments and jobs are added and updated live.
  • Accessibility

    It affects the ability of people with disabilities or special needs (such as blindness or color-blindness) to use Drupal.

Sign in to follow issues

Comments & Activities

  • Issue created by @rkoller
  • 🇨🇦Canada mgifford Ottawa, Ontario

    We can do more to highlight which is the selected image. Right now it is difficult for everyone to see.

  • 🇩🇪Germany rkoller Nürnberg, Germany

    just as an fyi, the images are not focusable, only the three elements on the image, the checkbox, the edit button and the remove button.

  • 🇨🇦Canada mgifford Ottawa, Ontario

    Focus indicators should be highly visible, especially for keyboard-only users, and distinct from hover and checked states to meet WCAG 2.1/2.2 guidelines (notably 2.4.7: Focus Visible and 1.4.11: Non-Text Contrast).

    The .media-library-item--grid.checked element, and you’re looking to clearly distinguish:
    • Focus (keyboard navigation) - Focus styles are too subtle: Low contrast
    • Checked (selected state) - Checked (selected) and focus may overlap visually, creating ambiguity for users.
    • Hover (mouse interaction) - Hover gets stronger visual weight than focus, which undermines keyboard accessibility.

    @rkoller has great points. I'd like to see:
    1. Visibly highlight focus — bold border or shadow with high contrast.
    2. Maintain distinct styles for .checked vs :focus.
    3. Prioritize accessibility over aesthetics for keyboard users.

    This code works:

    /* Default item */
    .media-library-item--grid {
      border-radius: var(--gin-border-xl);
      border: 2px solid transparent; /* prepare for overrides */
      transition: border-color 0.2s ease, box-shadow 0.2s ease;
    }
    
    /* Checked state */
    .media-library-item--grid.checked {
      border-color: #0071bc; /* or your primary theme color */
      background-color: #e6f0fa; /* soft background to indicate selection */
    }
    
    /* Focus state */
    .media-library-item--grid:focus-within {
      border-color: #ffbf47; /* strong yellow or contrasting color */
      box-shadow: 0 0 0 2px rgba(255, 191, 71, 0.8); /* high-contrast ring */
      outline: none;
    }
    
    /* Focused + checked (combined) */
    .media-library-item--grid.checked:focus-within {
      border-color: #004080; /* darker shade of primary for differentiation */
      box-shadow: 0 0 0 3px rgba(0, 64, 128, 0.8);
    }
    
    /* Hover (less prominent than focus) */
    .media-library-item--grid:hover {
      border-color: #cccccc;
      background-color: #f8f8f8;
    }

    The CSS here can definitely be improved.

    Testing Guidance

    • Use Tab to navigate to the element — the focus style should be clearly visible, even on low-quality screens.
    • Confirm that focus is visually different from both hover and checked.
    • Check color contrast of focus styles — ensure at least 3:1 contrast with the background for non-text indicators per WCAG 2.1 1.4.11.

    Accessibility Rationale

    • Keyboard users rely on visible focus indicators for navigation and interaction. If hover gets more attention than focus, it violates WCAG and harms usability.
    • Combining :focus-within and .checked gives you clear visual cues without clutter or confusion.
    • The use of borders and shadows improves non-text contrast and is screen-reader independent.
  • 🇨🇦Canada mgifford Ottawa, Ontario
Production build 0.71.5 2024