Design System Glossary

Colour Contrast

Colour contrast is the difference in brightness between foreground (text, icons) and background elements. It's measured by a ratio: 4.5:1 is readable for most people; 7:1 is readable for people with low vision. Insufficient contrast makes text hard or impossible to read for anyone, especially in bright light or with visual impairments.

The WCAG standard defines specific ratios for each context:

WCAG AA (easier): 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt bold+).
WCAG AAA (harder): 7:1 for normal text, 4.5:1 for large text.

Most Design Systems target AA as a minimum; AAA for critical text like errors or warnings.

In practice, contrast is a design token problem. If you define all text as semantic tokens (color-text-primary, color-feedback-error), you can audit the ratios once in the token library. Any component using those tokens inherits the contrast. Hard-coded colours bypass this and create audit debt.

Tools help: WebAIM's contrast checker, or browser DevTools (most modern browsers show contrast ratio when you inspect an element). The discipline: test all colour pairs, especially in dark mode or when text sits on images. A 4.5:1 on white text on dark background doesn't mean 4.5:1 on a white text on a blue gradient image.

Semantic tokens make this tractable. Define text-on-surface: {dark-grey} and pair it only with surface: {white}. The pair passes contrast audits once; every component using the tokens inherits the guarantee.