Accessibility guide

Accessible Color Systems

Start with a perceptual palette, assign semantic roles, and check actual foreground/background pairs in every theme and state.

From OKLCH shades to semantic roles

Create a palette with the OKLCH Palette, then map shades to surface, body text, links, borders, focus, and error tokens. Avoid using a shade number directly throughout components: semantic names make theme changes auditable.

State / roleLight pairRatioDark pairRatio
Body text#1F2937 / #FFFFFF14.68:1#F8FAFC / #0F172A17.06:1
Default link#1D4ED8 / #FFFFFF6.70:1#93C5FD / #0F172A9.90:1
Border / control#64748B / #FFFFFF4.76:1#64748B / #0F172A3.75:1
Focus indicator#1D4ED8 / #FFFFFF6.70:1#93C5FD / #0F172A9.90:1
Error text + icon#B91C1C / #FFFFFF6.47:1#FDA4AF / #0F172A9.44:1

These ratios use the exact opaque hex colors shown and sRGB relative luminance, rounded to two decimals for display. Confirm the pairs in the Color Contrast Checker when prerequisite issue #5 lands. A passing pair does not prove the full component is accessible: verify text size, focus visibility, surrounding context, and states.

A failing pair and a fix

Muted gray #94A3B8 on white is only 2.56:1 and fails normal-text AA. Replace it with slate #64748B at 4.76:1 for this background. Recheck the replacement wherever it is used; do not assume a token passes on every surface.

Before: muted text on white (2.56:1)

After: slate text on white (4.76:1)

WCAG 2.2 SC 1.4.3 requires 4.5:1 for normal text and 3:1 for large text. SC 1.4.11 requires 3:1 for visual information needed to identify UI components and states. SC 1.4.1 says color is not the only visual means of conveying information. Use text, iconography, or other cues alongside error color. Transparency changes the rendered pair, so evaluate the composited color over the actual background.

References: SC 1.4.3 Contrast (Minimum), SC 1.4.11 Non-text Contrast, and SC 1.4.1 Use of Color.

Copyable light and dark tokens

css
/* Default theme */
:root { --surface: #fff; --text: #1f2937; --link: #1d4ed8; --border: #64748b; --focus: #1d4ed8; --error: #b91c1c; }
/* Dark theme */
[data-theme="dark"] { --surface: #0f172a; --text: #f8fafc; --link: #93c5fd; --border: #64748b; --focus: #93c5fd; --error: #fda4af; }
css
:root {
  --surface: #FFFFFF;
  --text: #1F2937;
  --link: #1D4ED8;
  --border: #64748B;
  --focus: #1D4ED8;
  --error: #B91C1C;
}
[data-theme="dark"] {
  --surface: #0F172A;
  --text: #F8FAFC;
  --link: #93C5FD;
  --border: #64748B;
  --focus: #93C5FD;
  --error: #FDA4AF;
}
body { color: var(--text); background: var(--surface); }
a { color: var(--link); }
.field { border: 1px solid var(--border); }
:focus-visible { outline: 3px solid var(--focus); outline-offset: 2px; }
.error { color: var(--error); }

Payment details

Error: check the expiry date.

The example pairs an error message with a warning symbol and text. The message remains understandable when color is unavailable, the screen is grayscale, or a user has a color vision deficiency.

Color review checklist

  • Check default, hover, focus, disabled, and error states.
  • Test actual rendered pairs in both light and dark themes.
  • Meet 4.5:1 for normal text and 3:1 for large text; check applicable non-text contrast.
  • Do not rely on color alone for errors, status, or selection.
  • Composite translucent layers and gradients over their real backgrounds before measuring.
  • Review focus indicators, zoom, and forced-color modes separately.