LSCSS

Guide

Accessibility and CSS

Accessibility is not a QA checkbox added at the end of delivery. It starts in the CSS architecture itself.

Focus visibility, reduced motion, readable spacing, logical properties, colour contrast, and keyboard-safe interaction patterns all depend on how styles are organised.

Where CSS causes accessibility problems

  • focus styles removed with no replacement
  • hover-only interactions
  • animation that ignores reduced motion preferences
  • fixed dimensions that break zoom and text resize
  • visual order that fights source order
  • theme overrides that damage colour contrast

How LSCSS helps

  • state classes keep interaction states explicit
  • theme layers isolate visual overrides safely
  • shallow selectors reduce override chaos
  • logical properties improve international support
  • rare utilities (e.g. screen-reader helpers) stay separate from layout styling

Respect reduced motion

Start with complete, immediate state changes. Add transitions and animations inside prefers-reduced-motion: no-preference in the owning component layer. This keeps the same content and controls available when motion is reduced or the media query is unsupported.

CSS code example
/* Import this partial into layer(components).
 * State changes work immediately unless motion is opted into. */
.status-message {
    background-color: var(--c-surface);
}

.status-message.is_loading {
    background-color: var(--c-surface-alt);
}

@media (prefers-reduced-motion: no-preference) {
    .status-message {
        transition: background-color var(--transition-s);
    }
}

A global animation-duration: 0s rule does not disable transitions, smooth scrolling, or JavaScript-driven motion. Review those separately, include animated pseudo-elements, and never make completing an animation a condition for opening a control or updating its accessible state. Loading status still needs visible text; colour alone does not communicate it.

See the popover and disclosure examples for native controls with capability checks and optional motion. In projects with custom media, define a named preference query in settings and expand it through the same build as other media queries.

Start here

Align base styles and modifiers and state with your product’s focus and keyboard model, then audit contrast and motion on real pages—not only in isolation demos.

Recommended reading

Good accessibility usually looks boring. That is often a sign it is working properly.