GuideUpdated Mar 20, 2026

Building accessible design systems that scale

A product-docs style walkthrough of primitives, tokens, and CSS-first theming.

ARAlex RiveraMarch 18, 20268 min read

Overview

A production design system speeds up delivery and keeps accessibility a default. Pair unstyled accessible primitives with semantic tokens and you get a foundation that scales across products.

Tip

Recommended

Start from primitives that already own keyboard and ARIA — then layer visual tokens, not the other way around.

Primitives

Primitives should own focus traps, keyboard navigation, and ARIA roles. You style the surface; behavior stays consistent out of the box.

tokens.css

:root {
  --primary: #2563eb;
  --radius: 0.75rem;
  --border: oklch(0.9 0 0);
}

Tokens

Keep colors, radius, and spacing in CSS variables. Light and dark modes swap tokens without shipping a theme runtime.

Warning

Avoid hardcoding hex in components. Raw values break when product teams remap brand tokens later.

Ship checklist

Keyboard paths verified for every interactive primitive
Light and dark themes swap via CSS variables only
Focus rings visible at 375 / 768 / 1280 viewports