How to ensure colour is accessible
Check that every colour pairing in your designs meets WCAG 2.1 AA. This guide covers the approved Sitka pairings, how to test custom colours, and what to do when a pairing fails.
Objective
By the end of this guide you will know how to validate any colour pairing against WCAG 2.1 AA, use the pre-approved Sitka token pairings, and fix the most common contrast failures.
Understand the two WCAG thresholds you need to meet
WCAG 2.1 defines two thresholds. Sitka requires AA for all text and interactive elements.
| Level | Minimum ratio | Applies to |
|---|---|---|
| AA | 4.5:1 | Normal text (body copy, labels, captions) |
| AA Large | 3:1 | Large text (≥18pt or ≥14pt bold) and UI components |
Check whether your pairing is already in the approved list
The Sitka token pairings have been pre-validated. If you're using only these combinations, you're already compliant — skip to step 5.
--text-primaryon--background (dark)17.8:1AA--text-secondaryon--background (dark)6.1:1AA--nav-active-coloron--background (dark)5.4:1AA--text-primaryon--surface (light)15.3:1AA--text-secondaryon--surface (light)4.7:1AAThe full list is on the Contrast foundations page.
For custom pairings, calculate the ratio
When you need a colour combination not in the approved list, calculate the contrast ratio before using it.
- 1.In Figma: use the Stark plugin → Contrast Checker. Select the text and background layers.
- 2.In the browser: open Polypane or use Chrome DevTools (Inspect → Accessibility → Contrast Ratio).
- 3.Standalone: use WebAIM Contrast Checker at webaim.org/resources/contrastchecker.
- 4.Record the ratio and confirm it meets 4.5:1 (normal text) or 3:1 (large text / UI components).
Fix pairings that fail
When a pairing fails, adjust the foreground colour first — backgrounds affect the whole composition.
Darken the foreground (light mode)
Move the text colour towards the dark end of the neutral scale. A step of 20–30 lightness points is usually enough.
Lighten the foreground (dark mode)
In dark mode, text that's too dark (e.g. --text-tertiary) fails against dark surfaces. Increase lightness or use --text-secondary instead.
Increase font weight
Bold and large text qualifies for the AA Large threshold (3:1 instead of 4.5:1). Increasing weight from 400 to 600 can turn a fail into a pass — but don't use this as an excuse for low contrast.
Change the background
If the text is inside a card on a dark surface, consider using --surface-raised rather than --background. A lighter canvas gives more headroom.
Don't sacrifice readability for brand colour. If the brand colour doesn't pass at a given size, either use a darker tint or increase the font size and weight.
Add contrast checks to your CI pipeline
Manual checking doesn't scale. Add axe or Lighthouse to your CI so new colour violations are caught before they reach production.
# Install axe-core in your test suite
npm install --save-dev @axe-core/playwright
# In your Playwright test
const results = await new AxeBuilder({ page }).analyze();
expect(results.violations).toHaveLength(0);