Skip to content

Responsive Web Guidelines

Applies to all web frontend project types (currently only frontend-react). Builds on the User Experience Guidelines's Web section (mobile-first, WCAG 2.1 AA, no horizontal scroll at 320 px, CLS < 0.1) — those rules are not repeated here.

Supported browsers and device form factors are an architectural decision, not a style preference: record them in an ADR.

Prefer CSS Over Hand-Rolled JavaScript

The browser's own layout and animation engine is faster, more battery-efficient, and needs no testing than an equivalent JavaScript implementation. Reach for CSS first; only fall back to JavaScript when CSS genuinely cannot express the behavior (e.g., complex, data-driven interactions).

Instead of... Use...
JS-computed responsive breakpoints CSS Grid / Flexbox with minmax(), auto-fit
JS resize listeners to adapt a component to its container Container queries (@container)
JS-driven show/hide/fade/slide transitions CSS transition/animation, @starting-style
JS scroll-position calculations scroll-snap-*, position: sticky
JS-toggled dark/light theme classes prefers-color-scheme media query + CSS custom properties
JS form validation styling :invalid, :user-invalid, :has() selectors

Layout

  • Use CSS Grid for two-dimensional layouts (page shells, dashboards); Flexbox for one-dimensional layouts (toolbars, nav lists, form rows).
  • Use relative units (rem, %, fr, ch) for sizing; reserve px for borders and hairlines.
  • Use container queries, not only viewport media queries, for components reused at different container widths (e.g. a card that appears both in a wide grid and a narrow sidebar).

Stable Test Hooks

  • Every interactive or content-bearing element a test needs to target gets a stable data-testid attribute, separate from CSS classes and visible text (both of which change for styling/copy reasons unrelated to test stability). See TypeScript Coding Guidelines for the naming convention.
  • Never select elements in tests by CSS class or DOM structure — both are refactoring hazards.

Directives

  • Prefer native CSS (Grid, Flexbox, container queries, transitions/animations) over equivalent hand-rolled JavaScript
  • Use relative units for sizing; reserve px for borders/hairlines
  • Every test-targeted element has a stable data-testid, independent of CSS classes and visible text
  • Supported browsers and device form factors are documented in an ADR, not left as an implicit assumption