contrast ratio
Contrast ratio is the measured difference in relative luminance between text and its background, from 1:1 to 21:1. WCAG asks for at least 4.5:1 for normal text, 3:1 for large text, and 3:1 for the parts of a control that convey what it is.
What it is
A number you can calculate, not a matter of taste. Black on white is 21:1; two similar greys might be 1.8:1. The thresholds that matter are 4.5:1 for body text, 3:1 for large text, and 3:1 for interface parts like a focus ring or the edge of an input.
“Large” has a definition, and it is stricter than people assume: at least 24px, or 18.66px if the weight is 700 or more. A 16px semibold button label is normal text, not large text, however big it looks in the design file.
Why it matters if you are paying for a website
Because it is the single most common accessibility failure on the web, it is the easiest to measure, and it is the one your customers feel without being able to name. Light grey on white looks refined on a calibrated monitor in a dark office and disappears on a laptop on a train.
It is also the criterion most likely to collide with a brand guideline, which is where the interesting decisions live.
The decision this site had to make
The brand blue is #0d87cd. Against white it measures 3.9:1 — comfortably enough for a filled button, an icon or a hero-sized word, and under the line for anything at body size. Which meant one of two things: change the brand colour, or stop using it as a text colour.
The answer was three tokens instead of one. A darker blue for text on the page, a deeper one for a fill sitting under white text, and a third for blue text on a blue-tinted chip, where the tint eats the margin the first one has. The buttons keep the brand colour, the links do not, and the difference is invisible unless you are looking for it.
A second finding came out of the same work: axe cannot be trusted to hold this line. Whenever a gradient or a pseudo-element sits anywhere above a node, it reports the contrast as incomplete rather than failing, and a test suite that asserts only on violations passes. That is why there is a separate script here that computes the ratios itself and fails the build on a real miss.
What contrast ratio is not
It is not a measure of readability on its own — a page can pass every ratio and still be unreadable through tiny type, poor spacing or a busy background image behind the text. The ratio is a floor, not a design review.
Related terms
See also
Want this done, not just defined?
This is the part of the work I get hired for. The page below says what it costs and how it runs.
Accessibility audit (WCAG 2.1 AA)Where I write about this
10 Traits of an Effective Website | Conversion Optimization Guide
An effective website is one that converts visitors into customers. 10 concrete traits that decide the outcome — and how to verify each of them on your own site.