CSS Accessibility Best Practices

How CSS Alone Can Make a Perfectly Semantic Page Unusable

Semantic HTML & Accessibility Basics, earlier in this track, covered the structural side of accessibility — landmark elements, ARIA basics, accessible form labeling. All of that can be done correctly and a page can still be unusable for real people, because CSS controls the visual and interactive presentation layered on top of that structure, and presentation is where a huge share of accessibility either succeeds or quietly fails. A button can be perfectly labeled for a screen reader and still be invisible to a keyboard user who has no idea it is currently focused. Text can sit inside flawless semantic markup and still be unreadable to someone with low vision if its color contrast is too low. An animation can respect every ARIA attribute in the book and still trigger real physical symptoms in a user with a vestibular disorder if it ignores their stated motion preference.

This module covers four specific, concrete CSS-level responsibilities: focus states, color contrast, motion preferences, and touch-aware hover design. Each one is something a design or engineering team can get quietly, invisibly wrong while shipping a page that looks completely fine to the person who built it — because the person who built it was not the person the mistake actually affects.

Never Remove outline Without Replacing It With Something Equally Visible

Every browser ships a default focus ring — that blue (or, in some browsers, a platform-specific color) outline that appears around a link, button, or form field when it receives keyboard focus, typically via the Tab key. It is the single most important visual signal a keyboard-only user has: without it, there is no way to know which element on the page is about to receive the next keystroke or Enter press.

/* Removes the browser's default focus indicator, and replaces it with NOTHING */
*:focus {
  outline: none;
}

This rule, or some variant of it, is written constantly — almost always to "fix" a focus ring that a designer found visually distracting on a mouse click, not realizing it also erases the only visual cue a keyboard user has for every interactive element on the entire page. A mouse user never notices the rule is even there, because they never trigger :focus through clicking in the way a keyboard user triggers it through tabbing — which is exactly why this mistake survives so many rounds of visual review before anyone catches it.

:focus-visible — showing the ring only when it is actually useful

A legitimate complaint behind the "remove the outline" instinct: a mouse click on a button does trigger :focus in most browsers, and some designers find that ring visually noisy for a pointer interaction that already has its own visual click feedback. The real fix for this is :focus-visible — a pseudo-class that matches only when the browser's own heuristic decides the focus indicator is actually needed, which in practice means keyboard navigation, and largely excludes a plain mouse click.

button:focus {
  outline: none; /* remove the default, unconditional ring */
}

button:focus-visible {
  outline: 3px solid #2f6feb;
  outline-offset: 2px;
}

This is the one legitimate pattern for touching the default outline: pair a :focus removal with an equally strong :focus-visible replacement, never remove :focus and stop there.

Designing a custom focus style that is actually visible

A custom focus indicator has to clear a real, testable bar, not just "have some kind of style change." WCAG's Focus Appearance guidance (2.4.11, AAA, but treated as good practice broadly) effectively expects the indicator to have sufficient size and sufficient contrast against both the element and its background.

.btn:focus-visible {
  outline: 3px solid #2f6feb;
  outline-offset: 3px;
  border-radius: 6px;
  box-shadow: 0 0 0 6px rgba(47, 111, 235, 0.25);
}

outline-offset pushes the ring outward from the element's edge rather than hugging it directly — this is a small but genuinely important detail, since a ring that sits flush against a button's border can be hard to distinguish from the border itself, especially at low contrast. Outline (unlike border) never affects layout, since it is drawn outside the box without reflowing anything around it — one more reason it is the right tool for this, rather than reaching for a border change on focus.

WCAG Contrast Ratios — AA vs AAA, and How to Actually Check Them

WCAG defines color contrast as a mathematical ratio between a foreground color's relative luminance and its background's relative luminance, expressed as a number from 1:1 (identical — effectively invisible text) up to 21:1 (pure black on pure white, the maximum possible). The specification sets minimum ratios for text to be considered legible for people with low vision, and it sets different thresholds depending on the compliance level and the text's size.

Level AA (the practical, legally-referenced standard most teams target):
  Normal text                4.5:1 minimum
  Large text (18pt+/14pt+ bold)  3:1 minimum
  UI components & graphics       3:1 minimum (borders, icons, form field outlines)

Level AAA (a stricter standard, not required for general compliance):
  Normal text                7:1 minimum
  Large text                 4.5:1 minimum

"Large text" has a precise legal definition, not a vibe: 18pt (24px) or larger regular weight, or 14pt (roughly 18.66px) or larger if it is bold. Below that, normal text's stricter 4.5:1 threshold applies — which is why a large, bold hero headline can often get away with a lighter gray than the body copy underneath it, and still pass.

Checking contrast for real, not by eye

Contrast ratio is not something to eyeball — two colors that look "close enough" on one monitor can fail outright on another, and the human eye is genuinely bad at judging contrast accurately in isolation. Every real workflow uses a tool.

1. Chrome/Edge DevTools — inspect any element, open the color picker on its
   "color" value in the Styles panel. It shows the computed contrast ratio
   against the background directly, with a pass/fail badge for AA and AAA.

2. WebAIM Contrast Checker (webaim.org/resources/contrastchecker) — paste
   a foreground and background hex value, get the exact ratio and pass/fail
   grid for both text sizes and both compliance levels.

3. Browser extensions (axe DevTools, WAVE) — scan an entire live page and
   flag every element that fails contrast automatically, without checking
   colors one at a time by hand.

/* Fails AA for normal text — roughly 2.85:1 against white */
.subtext {
  color: #999999;
  background: #ffffff;
}

/* Passes AA (4.54:1) — same intent (a muted, secondary gray), corrected value */
.subtext {
  color: #767676;
  background: #ffffff;
}

Contrast applies to more than body text

The 3:1 "UI components & graphics" threshold from the table above is frequently missed entirely, because teams check body text contrast and stop there. It covers things like a form field's border against its background, an icon conveying meaning on its own, and a focus ring's contrast against both the element and the page — the exact focus-style requirement from Part 02.

Respecting Motion Preferences — Not Everyone Wants Your Animation

The CSS Transitions and CSS Animations & Keyframes modules covered how to build motion. This is the missing piece those modules deliberately left for here: some users experience genuine, physical discomfort from motion on screen — dizziness, nausea, or migraine symptoms triggered by parallax scrolling, large sweeping transitions, or auto-playing animation, a condition broadly referred to as vestibular sensitivity. Operating systems expose a system-level setting for this (macOS: Reduce Motion, Windows: Show animations in Windows, Android/iOS equivalents), and CSS can read that exact setting through a media query.

@media (prefers-reduced-motion: reduce) {
  /* Styles here apply only when the user's OS-level setting requests less motion */
}

@media (prefers-reduced-motion: no-preference) {
  /* Styles here apply only when the user has NOT requested reduced motion —
     rarely needed; usually the default (unguarded) styles already cover this case */
}

The standard, robust pattern is not to write every animation twice — it is to write your normal animations as the default, then use the media query to strip or shorten motion specifically for users who asked for less of it. This also means the query is additive protection, not a separate parallel design system to maintain.

.hero-title {
  animation: slide-up-fade 0.6s ease-out;
}

@keyframes slide-up-fade {
  from { opacity: 0; transform: translateY(24px); }
  to   { opacity: 1; transform: translateY(0); }
}

@media (prefers-reduced-motion: reduce) {
  .hero-title {
    animation: none;
  }
}

A near-universal, low-effort baseline pattern many production codebases apply globally, rather than animation-by-animation: shorten essentially every transition and animation duration to something imperceptibly close to instant, for every user who has requested reduced motion, in one sweeping rule.

@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

This matters beyond decorative flourishes. scroll-behavior: auto in the snippet above specifically overrides scroll-behavior: smooth, since smooth-scrolling itself is a motion effect that can trigger the same discomfort as a keyframe animation — a detail commonly missed even by teams who otherwise handle prefers-reduced-motion correctly.

Accessible Hover — Designing for Devices That Have No True Hover State

A touchscreen has no cursor hovering above the surface before a tap lands — there is no equivalent of a mouse resting over an element without clicking it. Any interaction or piece of information that only appears on :hover is, on a touch device, either unreachable entirely or only reachable through an inconsistent, browser-dependent workaround (some mobile browsers fire a synthetic hover state on first tap, requiring a second tap to actually activate the element — a confusing, undocumented behavior that varies across devices).

.info-icon .tooltip {
  display: none;
}

.info-icon:hover .tooltip {
  display: block;
}

/* On a touchscreen, there is no hover — the tooltip's content, whatever
   it explains, is simply never available to that user at all. */

The fix depends on what the hover interaction was actually doing. Two genuinely different categories, requiring two different fixes:

.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 12px 24px rgba(0,0,0,0.12);
}
/* A subtle lift on hover, purely decorative, with no unique information
   or functionality gated behind it. Fine to leave as hover-only — nothing
   is lost on a touch device beyond an animation that never had a touch
   equivalent to begin with. */

/* Bad: the ONLY way to see this content is a mouse hover */
.info-icon:hover .tooltip { display: block; }

/* Fixed: reachable by keyboard focus AND touch tap, not just mouse hover */
.info-icon:hover .tooltip,
.info-icon:focus-within .tooltip,
.info-icon[aria-expanded="true"] .tooltip {
  display: block;
}

:focus-within covers keyboard users tabbing to the icon (or a child of it). aria-expanded toggled by a small amount of JavaScript on tap/click covers touch users and mouse users who click rather than hover — the underlying pattern is: never let a single input method be the only way to reach real content.

The pointer and hover media features — detecting the actual input capability

CSS can query the device's actual pointing capability directly, rather than guessing from viewport width (a phone in landscape and a small laptop window can have the same width, but wildly different input capabilities).

/* Only applies hover-triggered styles on devices with a real mouse-like
   pointer — most touchscreens report (hover: none) and this block is
   skipped entirely for them, avoiding "sticky hover" states that get
   stuck active after a tap on touch devices. */
@media (hover: hover) and (pointer: fine) {
  .card:hover {
    transform: translateY(-4px);
  }
}

Putting Focus, Contrast, Motion, and Touch Together in One Real Component

Each rule so far has been shown in isolation. A real component — here, a dropdown-style "more info" button — needs all four working together, since none of them are optional add-ons layered on afterward; they are baseline requirements the component has to meet from the start.

<button class="info-btn" aria-expanded="false" aria-controls="shipping-info">
  Shipping details
</button>
<div id="shipping-info" class="info-panel" hidden>
  Orders ship within 2 business days via standard ground shipping.
</div>

.info-btn {
  color: #1a1a1a;          /* checked: 15.3:1 against white — comfortably passes AAA */
  background: #ffffff;
  border: 1px solid #767676; /* checked: 4.54:1 — passes the 3:1 UI-component minimum */
  padding: 10px 16px;
  border-radius: 6px;
  transition: background-color 0.15s ease;
}

/* Hover only where a real pointer supports it — no sticky-hover on touch */
@media (hover: hover) and (pointer: fine) {
  .info-btn:hover {
    background: #f2f2f2;
  }
}

/* A strong, offset focus ring — visible for keyboard users, silent for mouse clicks */
.info-btn:focus-visible {
  outline: 3px solid #2f6feb;
  outline-offset: 3px;
}

.info-panel {
  margin-top: 8px;
  transition: opacity 0.2s ease, transform 0.2s ease;
}

/* Reduced-motion users get an instant state change, not a sliding reveal */
@media (prefers-reduced-motion: reduce) {
  .info-btn, .info-panel {
    transition-duration: 0.01ms !important;
  }
}

None of these four rules block or interfere with each other — they layer cleanly, because each one targets a different axis of the same component: what color communicates it, what visible state shows it has focus, how much it is allowed to move, and which input methods can actually trigger its interactive states.

An Austin Fintech Startup Fails Its First Accessibility Audit Three Different Ways

/* Original: a global reset rule nobody revisited since it was written */
button, a, input, select {
  outline: none;
}

/* 1. Focus — restored, using focus-visible so mouse clicks stay clean */
button:focus-visible, a:focus-visible, input:focus-visible, select:focus-visible {
  outline: 3px solid #2f6feb;
  outline-offset: 2px;
}

/* 2. Contrast — the secondary gray token corrected across the design system */
:root {
  --text-secondary: #6b6b6b; /* was #a8a8a8 — now 5.74:1 against white, passes AA */
}

/* 3. Motion — the balance counter's animation respects the OS-level preference */
@media (prefers-reduced-motion: reduce) {
  .balance-counter {
    animation: none;
  }
}

Four Misconceptions About CSS Accessibility

5 Interview Questions — With Complete Answers

CSS Accessibility Mistakes Made Constantly, Even by Experienced Teams

Warnings and Real-World Symptoms This Topic Actually Produces