The craft

Validation that waits its turn

Validation leans on the platform: native constraints (required, type="email") drive the styling through :user-invalid / :user-valid — the craft detail is the user- prefix, which only matches after someone has interacted, so a pristine field never flags. The display name is required; the email is optional, so leaving it empty stays neutral. The email also uses a pattern to require a dotted domain (type="email" alone accepts a@b) — still pure HTML, still in the native pipeline. Hints and errors are linked via aria-describedby and never rely on color alone (the invalid border also thickens).

The same patience applies to the form as a whole. form:has(:invalid) button { opacity: .5 } reads like a form that knows itself, but an untouched required field already matches :invalid, so the button looks unavailable from first paint, before anyone has done anything: the premature judgement again, moved from the field to the form. A truly disabled submit is the harsher variant. It leaves the focus order, and it takes away the one action that makes the browser focus the first invalid field and say what is wrong with it. So the button here stays live: press Save with the name empty. The browser's message is a supplement, not the plan. It appears only on submit and for one field at a time, it does not rescale if the page is zoomed while it is up, and a screen reader hears that the field is invalid more reliably than it hears why. That is why the hint under each label stays on screen.

/* :invalid matches immediately — a required field is
   "invalid" while empty, so it flags before any input. */
input:invalid {
  border-color: red;
}

/* :user-invalid waits for interaction, so pristine
   fields stay neutral. Thicker border = non-colour cue. */
input:user-invalid {
  border-color: var(--color-error);
  border-width: 2px;
}

<!-- Disabled until every field is valid: the button leaves
     the focus order, and nothing can trigger the browser's
     report of what is wrong. Its CSS-only cousin,
     form:has(:invalid) button { opacity: .5 }, looks dead
     from first paint, because an untouched required field
     already matches :invalid. -->
<button type="submit" disabled>Save</button>

<!-- Always live. Pressing it makes the browser focus the
     first invalid field and say why, and :user-invalid marks
     every field that needs work from then on. The hint stays
     on screen because the native message appears only on
     submit, one field at a time. -->
<form>
  <label for="name">Display name</label>
  <p id="name-hint">Required. Shown publicly.</p>
  <input id="name" required aria-describedby="name-hint" />
  <button type="submit">Save</button>
</form>

• MDN: :user-invalid
• WCAG 3.3.1 Error Identification
• Adrian Roselli: Avoid Default Field Validation

Dark mode from one source of truth

Theming is a place craft pays off quietly. Declaring each colour once with light-dark() keeps the light and dark values together so they can't drift apart — the alternative scatters them across @media (prefers-color-scheme) blocks that someone eventually edits half of. Same result, half the surface area for bugs.

background-color: light-dark(#e6e6fa, #1a1a2e);

background-color: #e6e6fa;

@media (prefers-color-scheme: dark) {
  background-color: #1a1a2e;
}

@property --scheme-probe {
  syntax: '<color>';
  inherits: true;
  initial-value: white;
}

.card { --scheme-probe: light-dark(white, black); }

@container style(--scheme-probe: black) {
  .swatch { border-style: dashed; /* any property */ }
}

• MDN: light-dark()

Native dialog, zero trapping code

A native <dialog> with showModal() gives you focus trapping, Esc-to-close, and an inert background from the platform — the things hand-rolled modals get wrong. The entry animation uses motion tokens, so it disappears automatically under reduced motionReduced motionA system preference (prefers-reduced-motion) asking for less animation — for people with vestibular disorders, motion is physically sickening. Here, animation is an enhancement that bows out on request..

<!-- A div "dialog": now hand-write focus trapping,
     Esc-to-close, an inert background, scroll locking… -->
<div class="modal" role="dialog" aria-modal="true">
  …
</div>

<!-- dialog.showModal() gives focus trapping, Esc, an
     inert background and top-layer stacking, all free. -->
<dialog class="modal">
  …
</dialog>

• MDN: <dialog>

Motion that bows out on request

Three independent animations, one preference. When the OS asks for reduced motion, all of them still — handled globally in preferences.css from a single source of truth, so no component has to remember to opt in. Flip the switch to simulate the preference (your real OS setting works too) and watch every one stop at once.

/* Spins for everyone, including someone who asked
   their OS for reduced motion. */
.spinner {
  animation: spin 1s linear infinite;
}

/* Scale the duration by one variable that flips to 1
   under prefers-reduced-motion (set once, globally),
   so nothing here has to opt in. */
.spinner {
  animation: spin calc(1s * (1 - var(--rm))) linear infinite;
}

• MDN: prefers-reduced-motion
• WCAG 2.3.3 Animation from Interactions

Targets that survive touch and forced colors

Hover styles only apply on devices that can actually hover; touch devices get larger targets via touch-primary(). In forced-colors mode the border keeps the button visible when the background is replaced — a failure mode most buttons never account for.

/* Background alone marks this button. In forced-colors
   mode the fill is replaced and its edges vanish. */
.button {
  border: none;
  background-color: var(--color-primary);
}

/* A border does load-bearing work, so the button keeps
   a visible edge when the background is stripped. */
.button {
  border: 2px solid var(--color-primary-hover);
  background-color: var(--color-primary);
}

• WCAG 2.5.8 Target Size
• MDN: forced-colors

Layouts that expect the worst

Defensive CSS is the habit of assuming real content will be longer, wider, and weirder than the mockup. Designs are composed with tidy placeholder copy; CSS has to survive user names, tokens, and URLs. The classic trap: a grid item's automatic minimum size is its min-content size, not zero — the first unbreakable string forces its column wider than the container and pushes the layout past the viewport, a WCAG 1.4.10 Reflow failure that low-vision users at high zoom hit first. The guard is boring and load-bearing: min-inline-size: 0 at every grid hop, plus a scroll or wrap strategy for content that can't break. (This codebase learned it the hard way during QA, courtesy of an iOS WebKit quirk.)

v2.4.1 · live

https://accessible-by-default.dev/deploys/2026-07-02/a1b2c3d4e5f6a7b8c9d0

/* A grid item's automatic minimum is its min-content
   size, so one unbreakable URL forces the column past
   the viewport — a 1.4.10 Reflow failure. */
.card-body {
  display: grid;
}

/* Two guards: let the column shrink below its content,
   and give the unbreakable line a local scroll. */
.card-body {
  display: grid;
  min-inline-size: 0;
}
.url {
  overflow-x: auto;
}

• Defensive CSS (Ahmad Shadeed)

Break it with content

Layouts don't break in design reviews; they break the day the CMS delivers a title nobody planned for. The habit that catches it early is feeding a component hostile content on purpose: the longest plausible headline, German compound words that refuse to wrap, a right-to-left language. One card survives all four feeds below because the guards were built in — logical properties instead of left and right, min-inline-size: 0 where grids meet text, hyphens: auto riding on an honest lang attribute, and a button sized by its label instead of a designer's optimism.

/* Physical edges don't follow writing direction — in
   an RTL layout the accent lands on the wrong side. */
.card {
  border-left: 4px solid var(--color-primary);
  padding-left: 1rem;
}

/* Logical properties flow with dir/lang, so one rule
   mirrors correctly for LTR and RTL alike. */
.card {
  border-inline-start: 4px solid var(--color-primary);
  padding-inline-start: 1rem;
}

One more content-shaped trap: flattening a list with display: contents so its items can sit on the parent grid. For years that stripped the list's semantics from assistive tech — and Safari has relapsed more than once. Subgrid gets the same alignment without the sacrifice.

/* Flattening a list into the parent grid. For years this
   stripped list semantics from assistive tech (Safari
   still relapses) — the layout wins, the <ul> vanishes. */
ul.cards {
  display: contents;
}

/* Subgrid aligns the items to the page grid while the
   list keeps its box and its semantics. If you must use
   display:contents, re-test with a screen reader. */
ul.cards {
  grid-column: 1 / -1;
  display: grid;
  grid-template-columns: subgrid;
}

• MDN: hyphens
• MDN: logical properties

Loading states the accessibility tree can see

Skeleton screens are a perceived-performance trick for the eyes: grey shapes promise that content is on its way. But placeholders are semantic-free divs — a screen reader finds an empty region with no hint that anything is happening. The craft move costs two attributes: aria-busy="true" marks the region as loading (a state you clear once it settles), and one visually-hidden line says what's coming — the part a screen reader actually reads. A live region is usually the wrong tool here — on a fast connection the "loading" announcement lands after the content it was warning about. And size placeholders to the content they stand in for: a skeleton that shifts the page when real content lands trades one jank for another — that shift is what CLS (Cumulative Layout Shift) measures.

<!-- Skeleton divs only: a screen reader finds an empty
     region with no hint that anything is loading. -->
<div class="card">
  <div class="skeleton-row"></div>
  <div class="skeleton-row"></div>
</div>

<!-- aria-busy flags the loading state (cleared when the
     content lands); the skeleton is aria-hidden, so this
     hidden line is what a screen reader actually reads. -->
<div class="card" aria-busy="true">
  <span class="visually-hidden">Loading recent activity…</span>
  <div class="skeleton-row" aria-hidden="true"></div>
</div>

• MDN: aria-busy

Truncation that keeps a way in

line-clamp cuts a paragraph to a tidy three lines — and for a sighted visitor, everything past the clamp simply stops existing, because the property is visual-only and ships no control to open it. A screen reader still gets the full text, so the two audiences quietly read different documents. The craft move: make the clamp itself the collapsed state of a native <details> — ::details-content normally hides closed content, but overriding its content-visibility leaves a clamped preview showing. One element, expanded state announced for free, nothing duplicated. Browsers without the pseudo-element fall back to an ordinary closed disclosure. And when the content is essential, the honest fix is simpler: don't clamp it.

/* Three lines survive; the rest of the content is gone
   for sighted users, with nothing to open. (A screen
   reader still gets all of it — the two audiences now
   read different documents.) */
.teaser {
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 3;
  overflow: hidden;
}

/* Clamp the closed state of a real <details>: the preview
   is the collapsed disclosure itself — expanded state
   announced natively, nothing duplicated. */
details:not([open])::details-content {
  content-visibility: visible;
  display: -webkit-box;
  -webkit-box-orient: vertical;
  -webkit-line-clamp: 3;
  overflow: hidden;
}

• MDN: -webkit-line-clamp
• MDN: ::details-content

The scrollbar you tint, never thin

Scrollbars are OS territory the page only borrows, and overflow: auto alone ships more than most custom widgets: a thumb whose presence says "this scrolls" and whose size says how much, click-to-jump, the arrow keys, Home, End and Page Down, wheel, trackpad and touch, and a contrast the browser maintains. The craft is to add to that without taking any of it away, and two additions earn their place. On macOS the bar floats above content by default; on Windows, and for anyone who sets "always show", it claims a lane, and when it arrives mid-interaction every line re-wraps around it. scrollbar-gutter: stable reserves that lane up front. And scrollbar-color, standard in all three engines since Safari 26.2, tints the thumb from the page's own tokens instead of the OS grey and turns it to the accent while keyboard focus is inside the region, so the thumb now says which scroller the arrow keys will move. Tinting it comes with a bill: 1.4.11 and 2.5.8 exempt a control only while the browser draws it. A thumb the author colours must clear 3:1, so it is the ink at half strength here, not the frame tint. A thumb the author thins is a target shrunk below 24 pixels that people grab all day, so the width stays auto. The prefixed ::-webkit-scrollbar stays out: non-standard, and Chromium ignores it once the standard properties are set. What a scrollable region needs before any of this is tabindex="0" and a label, so keyboard users can reach it at all.

/* Thinned to 4px and tinted #ddd: non-standard syntax
   (Firefox never read it, Chromium ignores it once the
   standard properties are set), a thumb at 1.3:1 against
   white, and a target the author shrank below 24px. */
.panel::-webkit-scrollbar { width: 4px; }
.panel::-webkit-scrollbar-thumb { background: #ddd; }

/* Reserve the lane so content doesn't reflow when a classic
   scrollbar appears. Tint the thumb from a system colour at
   half strength (3:1, and it follows light and dark), and
   switch it to the link colour while keyboard focus is inside,
   so the thumb says which region the arrow keys move. Width
   stays auto: people grab thumbs. (The region itself gets
   tabindex="0" and a label for keyboard use.) */
.panel {
  overflow-y: auto;
  scrollbar-gutter: stable;
  scrollbar-color: color-mix(in oklab, CanvasText 50%, transparent) transparent;
}

.panel:focus-within {
  scrollbar-color: LinkText transparent;
}

• MDN: scrollbar-gutter
• MDN: scrollbar-color
• WCAG 1.4.11 Non-text Contrast
• WCAG 2.5.8 Target Size (Minimum)
• WCAG 2.1.1 Keyboard

Four ways to hide, and whom they hide from

"How do I hide this?" is the wrong question — the right one is from whom. display: none removes content for everyone: eyes, screen readers, the Tab key. The .visually-hidden pattern removes it for eyes only, which is how labels and hints reach a screen reader without cluttering the layout — but any control inside stays tabbable, so focus can land on nothing visible. aria-hidden is the mirror image: fully visible, silent to assistive tech, and it does not touch the tab order, which is why it must never wrap anything interactive. And inert switches a visible region off for everyone at once — the modern answer for the page behind a modal. Native <dialog> applies it to the whole background for free.

/* "Hidden" by eye only: invisible, but still announced
   by screen readers and still a tab stop — keyboard
   users land on nothing. */
.menu {
  opacity: 0;
}

/* Pick the technique by audience, not by looks:
   gone for everyone      → display: none
   screen readers only    → .visually-hidden
   visible but inactive   → the inert attribute */
.menu[data-closed] {
  display: none;
}

• MDN: inert
• WebAIM: invisible content

Text spacing is the reader's setting

WCAG 1.4.12 grants readers the right to raise line height to 1.5, letter spacing to 0.12em, word spacing to 0.16em, and paragraph spacing to 2em — people with dyslexia or low vision do this through extensions and user stylesheets, and the page has to survive it with no loss of content or function. What breaks is never the text; it's the pixel-perfect box around it. The toggle below does exactly what a reader's override does: the flexible card breathes, the fixed-height one clips sentences mid-thought. The craft is one habit — heights on text containers are floors (min-block-size), never ceilings.

/* A pixel-perfect text box. The moment a reader raises
   line height or letter spacing (WCAG 1.4.12 says they
   may), the last sentences are clipped away. */
.card {
  height: 176px;
  overflow: hidden;
}

/* Set a floor, never a ceiling — the box grows with the
   reader's spacing instead of eating their text. */
.card {
  min-block-size: 176px;
}

• WCAG 1.4.12 Text Spacing