Mobile and accessibility

Verify small screens first, not last

The principle

A large share of this audience reads technical content on a phone, usually in a spare five minutes rather than at a desk. Building on a 27 inch display and checking mobile at the end means every layout decision was made under conditions no visitor experiences.

Build at 375px. Check the desktop afterwards. The reverse order produces a site that is technically responsive and practically unusable.

The four defects

Horizontal page scroll. A code-heavy site is the most likely kind to have it, because a long unbroken line inside a <pre> pushes the body wider than the viewport. The page then feels broken even though nothing is.

document.documentElement.scrollWidth > document.documentElement.clientWidth

Run that on every template at 375px. It must be false.

The fix is to make code blocks scroll inside their own container:

.scroll-x {
  overflow-x: auto;
  overscroll-behavior-x: contain;
}

overscroll-behavior-x: contain stops a horizontal swipe at the end of a code block from triggering a browser back gesture, which is a subtle but genuinely annoying defect on iOS.

Inputs below 16px. iOS zooms the viewport on focus. The user then has to pinch back out, and on a form with three fields they do it three times.

Tap targets under 44px. Below that, a normal thumb misses often enough to be noticed. This applies to the checkbox in a checklist as much as to a button.

Sticky elements eating the viewport. A sticky header plus a sticky call to action plus a cookie banner can consume 40 percent of a phone screen. Pick one, or make them mutually exclusive.

The implementation

The design tokens do most of the work, because a global rule cannot be forgotten per component:

input, select, textarea, button {
  font-size: max(16px, 1em);
  font-family: inherit;
}

summary {
  min-height: 2.75rem;   /* 44px */
}

Keyboard operability

The principle

Everything interactive has to be reachable and operable from the keyboard, with a visible focus ring, in an order that matches the visual layout.

For a checklist app this is not an edge case: keyboard use is how a power user works through 112 items quickly.

The specific traps

• Focus trapped inside an expanded item. A <details> that renders a focusable element and a custom key handler can swallow Tab.
• Focus rings removed globally. outline: none with no replacement is the most damaging one-line change in CSS.
• Custom controls without roles. A <div> with an onClick is invisible to a screen reader and unreachable by keyboard.

The implementation

:focus-visible {
  outline: 2px solid var(--focus-ring);
  outline-offset: 2px;
}

:focus-visible rather than :focus means the ring appears for keyboard users and not on mouse click, which is the behaviour that makes designers accept it.

For tabs, implement the full ARIA keyboard contract rather than half of it:

const keys: Record<string, number> = {
  ArrowRight: (index + 1) % items.length,
  ArrowLeft: (index - 1 + items.length) % items.length,
  Home: 0,
  End: items.length - 1,
};