Skip to content

Accessibility

A backdrop is the dimming layer behind an overlay — a modal, drawer, or popover — so it has no WAI-ARIA interaction pattern of its own: it is purely decorative, and the overlay it accompanies owns the semantics, following the WAI-ARIA APG Dialog (Modal) pattern. An accessible backdrop stays out of the accessibility tree, lets the overlay above it trap focus and carry the accessible name, and makes the page behind inert — so a keyboard or screen-reader user is never stranded in content the dimming has visually switched off. Together with its overlay it meets WCAG 2.1 AA.

For designers

Section titled “For designers”
  • Any affordance layered over the backdrop — typically the close button — and the overlaid content must maintain accessible contrast against the dimmed surface. Source: WCAG 1.4.3 Contrast (Minimum).
  • The dimming must never be the only signal that the page behind is inactive — the overlay’s presence and the trapped focus already carry that meaning; don’t rely on the backdrop’s tint alone. Source: WCAG 1.4.1 Use of Color.
  • Focus styles on the close affordance must stay visible against the dimmed backdrop, meet contrast requirements, and be clearly distinguishable from hover. Source: WCAG 2.4.7 Focus Visible.
  • Use semantic colour tokens (e.g. foreground/neutral/default) rather than fixed values, so the component adapts correctly across themes and surfaces.

For developers

Section titled “For developers”

The backdrop is purely decorative, so keep it out of the accessibility tree: a standalone <div class="tng-backdrop"> carries no role and is ignored automatically, and when the overlay is a native <dialog> or uses the popover attribute, the browser-generated ::backdrop pseudo-element is never exposed to assistive technology either. The semantics live on the overlay the backdrop accompanies — that surface carries role="dialog", traps focus while it is open, and owns the accessible name — not on the backdrop layer, which must never hold focus or interactive content. While the overlay is open, set inert on the page content behind so focus and pointer events can’t escape behind the dimming, and respect prefers-reduced-motion by dropping the fade animation for users who ask for less motion. The backdrop layer, the dialog it accompanies, and the close affordance each get their role, name, and state in the Labelling elements section below.

Labelling elements

Section titled “Labelling elements”

Give every element the role, name, and state assistive technology needs.

Backdrop element

.tng-backdrop is decorative — it takes no role and needs no accessible name, and a standalone <div class="tng-backdrop"> is ignored by assistive technology automatically. When the overlay is a native <dialog> or uses the popover attribute, the browser’s ::backdrop pseudo-element replaces it and is likewise never exposed. Never add interactive content or tabindex to the backdrop layer.

Dialog / overlay

The overlay the backdrop dims for — usually a modal. It, not the backdrop, carries the semantics: role="dialog" (implied by a native <dialog> opened with showModal(), along with aria-modal="true"), named with aria-labelledby pointing to its visible title, or aria-label when there is none. Focus is trapped inside it while it is open and returns to the trigger on close.

Close affordance

The close button overlaying the backdrop. Its accessible name must read as “Close” — from visible text, or aria-label="Close" when it is icon-only, with the close icon marked aria-hidden="true" so it is not announced twice. Set inert on the page content behind while the overlay is open so this control and the overlay stay the only reachable elements.

Source: WCAG 4.1.2 Name, Role, Value.