Enforcing WCAG color contrast programmatically

WHAT THIS TESTS This checks whether you make accessible contrast the default by construction, rather than hoping developers manually verify each pairing.

A GOOD ANSWER COVERS Shift from raw color primitives to semantic, pre-paired tokens. Instead of exposing every hue and shade for free combination, define semantic roles like text-on-surface, text-on-brand, and text-on-danger whose foreground and background are chosen together and pre-validated, so an invalid pairing is simply not available in the API. Back this with computation: a build or test step calculates the WCAG contrast ratio for every shipped pairing and fails if any falls below the threshold, AA being 4.5 to 1 for normal text and 3 to 1 for large text. Add a lint rule or design-token test that flags new or changed pairs. Surface the measured ratio in documentation next to each token pair so consumers see compliance at a glance. For dynamic or user-chosen colors, validate at runtime and warn or fall back.

COMMON WRONG ANSWERS Exposing all primitives and trusting developers to pick accessible pairs. Checking contrast once in design and never guarding against drift. Eyeballing in Figma with no automated gate. Relying solely on a runtime check in production rather than blocking bad pairs in CI.

LIKELY FOLLOW-UPS What are the AA versus AAA thresholds and large-text rules. How do you handle disabled or placeholder text exemptions. How do you validate user-supplied colors.

ONE CONCRETE EXAMPLE You expose a text-on-warning token pair; a CI test computes its contrast ratio and fails the build when a designer lightens the warning background below 4.5 to 1, forcing the pairing to be fixed before merge rather than discovered by a user with low vision.