Color Contrast Checker User Guide

The checker is a single page that grades one colour pair against WCAG 2.1. It is built for the moment in a design or code review when somebody asks whether a particular grey on a particular cream is good enough, and the answer needs to be a number rather than an opinion.

• Route: /tool/contrast-checker/.
• Input: one text colour and one background colour, both as hex.
• Output: the ratio to two decimals, five Pass/Fail badges, a live specimen of the pair, and a link that carries the pair.
• Standard: WCAG 2.1, using the sRGB relative-luminance formula.
• Privacy: everything is computed in the browser. No upload, no account, no storage.
• Cost: free, with no sign-in step.

It is not a page scanner and not a palette generator. If you need every failing element on a live URL, that is the analyzer. If you need ramps, tints, shades or colours pulled out of an image, that is basic tools. The checker exists because those tools are the wrong size for a single yes-or-no question.

Open /tool/contrast-checker/. It loads on a default pair — text #1A1400 on background #F7F3E6 — and grades it immediately, so there is no empty state to get past.

1. Set the text colour. Type a hex value into the Text colour field, or click the swatch beside it and pick from your operating system's colour dialogue.
2. Set the background colour. Same two ways, in the second field.
3. Read the big number. It updates on every keystroke and shows the ratio to two decimals, for example 9.22:1.
4. Read the five badges. Each row names a rule and its threshold, and flips to Pass or Fail. Body text at AA — 4.5:1 — is the one most contracts point at.
5. Act on the result. If body AA fails, press Make it pass AA and the text colour moves until it clears 4.5:1. Either way, press Copy link to put the pair on your clipboard as a URL.

That is the whole loop. Everything below is detail about what each control changes and where the numbers stop being trustworthy.

On a wide screen the working area is two columns over a full-width strip. Controls sit on the left, the result sits on the right, and the preview runs underneath both.

Below 720px the layout collapses to one column in the order controls, result, preview, and the swap button rotates a quarter turn so its arrows point up and down between the two stacked fields. Nothing is hidden on a narrow screen; only the arrangement changes.

The page follows the site theme. Pass and Fail badges use separate ink colours for light and dark surfaces, so the badges on a contrast page do not themselves fail the rule they are teaching.

Each colour has two controls that stay in step with each other: a native swatch and a hex field. Use whichever suits the moment — the swatch for exploring, the field for pasting a value out of a stylesheet or a design file.

What the hex field accepts

Hex only, in three or six digits, with or without a leading hash. All four of these are the same colour to the checker:

#1A1400
1A1400
#f00      (expands to #FF0000)
f00

When the field loses focus, a value it understood is rewritten in canonical form: uppercase, six digits, with a hash. So f00 becomes #FF0000 the moment you tab away. Nothing else is accepted — rgb(26, 20, 0), hsl(), CSS colour names such as rebeccapurple, and eight-digit hex with an alpha channel are all rejected.

The half-typed value trap

A value the field cannot parse does not blank the readout. The checker falls back to pure black for an unreadable text colour and pure white for an unreadable background, then grades that instead. So while you are mid-way through typing #1A, the page is happily reporting a real ratio for black on your background. It looks like an answer and it is not yours. Finish typing, or tab out to make the field normalise, before you believe the number.

Why the swatch looks different here

Most of the Auric Artisan site replaces the browser's colour input with a custom picker. This tool opts out on purpose, so you get the plain native swatch. The reason is honesty: the checker writes colour values into the swatch programmatically — on swap, on Make it pass AA and when restoring a shared link — and the custom picker cannot see those writes. It would keep showing the old colour while the value underneath had changed. A colour tool whose swatch lies is worse than one with a plain swatch.

What swap actually changes

The contrast ratio is order-independent: dark on light and light on dark give the same number. Swapping therefore never changes the ratio or the five badges. What it does change is the preview, which repaints the other way round, and Make it pass AA, which only ever moves the text colour — so after a swap the fix acts on what used to be your background. Use swap when you want to test the inverted version of a component, or when you want the fix to adjust the other colour of the pair.

The large number is the WCAG 2.1 contrast ratio, printed to two decimal places with the :1 suffix — 4.53:1, 9.22:1, 21.00:1. It shows an em dash until the first grading runs, which happens as soon as the page is ready.

• Range: 1:1 for two identical colours up to 21:1 for pure black on pure white. Nothing can go outside that.
• Updates: on every keystroke in a hex field and on every movement of a swatch. There is no Calculate button and no delay.
• Direction: none. The formula takes the lighter and darker of the two colours, so which one is the text makes no difference to the number.
• Announcement: the number is a polite live region, so a screen reader reads the new ratio when it changes.

One rounding detail is worth knowing. The badges compare the full unrounded ratio against the threshold, but the number on screen is rounded to two decimals. A pair measuring 4.4996 will print 4.50:1 next to a Fail badge for body AA. That is not a bug; the badge is right and the display is rounded. If a pair lands that close to a threshold, treat it as failing and give yourself margin.

Grades are inclusive: a ratio exactly equal to the threshold passes. A true 4.5 reads as Pass.

Every pair is graded against five thresholds at once, so you never have to choose a mode before you get an answer. Each row names the rule, states its number, and carries a badge that reads Pass or Fail.

Which row applies to you

Pick the row by what you are colouring, not by which badge is greenest.

• Paragraphs, labels, table cells, form help text: body text. Use the 4.5:1 row, and read the 7:1 row as your stretch goal.
• Headings and display type: large text, but only if the size qualifies — see below.
• Borders of inputs, toggle states, icon buttons, focus rings, the meaningful parts of a chart: the UI and graphics row at 3:1. Note that the comparison for these is against the adjacent colour, which may not be the page background you typed in.

What counts as large text

Large text means at least 18.66px if the weight is bold, or at least 24px otherwise. It is a size threshold, not a heading rule. An <h2> set at 20px in a light weight is body text as far as WCAG is concerned and must clear 4.5:1, no matter what the tag says. Check the computed size before you let yourself use the 3:1 row.

What is out of scope

WCAG 2.1 exempts inactive controls, pure decoration, text that is part of a logo, and text inside a picture of something else. The checker does not know which of those you are testing — it grades whatever pair you give it — so a Fail on a disabled button's label is not automatically a defect. Everything a person has to read or operate is in scope; the rest is a judgement call you make, not one the tool makes.

The panel under the controls is painted in the pair you are testing and holds three specimens:

• A 24px bold line — "Large text looks like this" — sitting at the large-text size threshold.
• A 16px paragraph at a realistic measure, so you can judge the pair over a few lines rather than a few words.
• An "Interface element" chip with a two-pixel border in the text colour, so you can see how the pair reads as a control outline rather than as type.

Look at it. The ratio is a floor, not a verdict, and the panel is where the difference shows up. The WCAG 2.1 formula ignores font weight entirely, ignores size past the large-text threshold, and does not model the way light text on a dark background appears to bloom and thicken. Pairs that pass at 4.6:1 in a thin weight are routinely tiring to read; pairs that fail at 4.3:1 in a heavy weight can look perfectly crisp — and still fail an audit.

The panel is a specimen of your pair only. It always shows your two colours, in both light and dark site themes, and it will not quietly substitute the theme's own ink for your text colour. If the preview ever looks like it is showing a colour you did not type, treat that as a bug worth reporting rather than a result.

Make it pass AA is the primary button in the action row. It is hidden whenever the pair already reaches 4.5:1, so its presence is itself a signal: if you can see the button, body text is failing.

What it does

1. It looks at the background and decides which way to travel: toward black when the background is light, toward white when the background is dark.
2. It walks the text colour along a straight line toward that endpoint in small steps, checking the ratio at each step against the unchanged background.
3. It stops at the first step that reaches 4.5:1 and writes that colour into both the hex field and the swatch. If no step gets there, it uses the pure endpoint — black or white.
4. It re-grades, which makes the button disappear, and writes the outcome into the status line. For gold #D3AF37 text on the default cream background it reads Adjusted text to #836C22 (4.58:1).

The reported hex is now in the text field, ready to select and copy, and the address bar settles on the new pair a moment later.

What it will not do

• It only targets 4.5:1. There is no option to aim at large-text 3:1 or at AAA 7:1. If you need 7:1, use the button as a first move and keep darkening by hand.
• It never touches the background. Only the text colour moves. If the background is the colour you are allowed to change, press swap first, fix, then swap back.
• It does not preserve your hue or saturation. The path is a straight line in sRGB toward black or white, so the result is usually a desaturated relative of your original. Treat it as a target to aim at, not a colour to ship.
• It is a coarse scan, not a solve. It takes the first sample that clears the bar out of roughly fifty along the line, so the answer is close to minimal but not exactly minimal.

The mid-grey surprise

The direction is chosen from the background's relative luminance, which is not the same as how light the colour looks. A mid grey such as #808080 has a relative luminance of about 0.216, which counts as dark, so the text is pushed toward white rather than black even though the background looks like the middle of the range. That is the correct WCAG behaviour and it will occasionally surprise you. If you wanted the other direction, set the text colour toward black yourself and watch the ratio as you go.

A practical way to use it

Press the button to find out how far the pair has to move, note the reported ratio, then walk your brand colour back toward its original hue a few digits at a time, watching the number stay above 4.5. You end up with a colour that is yours and that passes, rather than with a grey the tool chose.

Every time the checker re-grades, it rewrites the address bar with the current pair. The colours are carried as query parameters with the hash removed:

/tool/contrast-checker/?fg=1A1400&bg=F7F3E6

fg is the text colour and bg is the background. Load that URL and the checker restores both and grades them at once. Bookmark it, paste it into a pull request, put it in a bug report — it is a complete description of the test.

Copy link

The Copy link button copies the current address to the clipboard and writes "Share link copied." into the status line. If the clipboard is unavailable — an insecure context, or a browser permission you declined — it prints the full URL into the status line instead so you can select and copy it by hand. Either way you get the link.

Partial links

Only the parameters that parse as hex are applied. A link carrying ?fg=D3AF37 and nothing else sets the text colour and leaves the background at the page default. That is deliberate, because the site search sends exactly that shape when its answer card is about a single colour. A colour-pair answer sends both, for example:

/tool/contrast-checker/?fg=D3AF37&bg=0D0D0D

Two things the URL does not do

• It does not create history entries. The address is replaced rather than pushed, so the browser's back button will not step you through the colours you tried. If you want a pair back later, copy its link at the time.
• It does not reload the page. The rewrite is silent and slightly delayed while you type, so the address settles a moment after the number does.

You do not have to navigate to the checker by hand. Several parts of the site link into it, and one of them — site search — hands it a pair already loaded. The rest are plain links that open the checker on its default pair.

What is kept between visits

Nothing. The checker has no local storage, no saved history, no library of previous pairs and no account state. The query string is the only persistence there is. Close the tab without copying the link and the pair is gone — so if a result matters, copy the link before you move on. The corollary is the good news: there is nothing to clear, nothing to sync and nothing leaves your machine.

The checker can be driven entirely from the keyboard, which matters more than usual for a tool whose subject is accessibility.

• Tab order runs through the text swatch and its hex field, the swap button, the background swatch and its hex field, then the action buttons.
• Focus stays visible. The focus ring is drawn around the whole hex row rather than the bare input, so you can always see which field you are in.
• The ratio is announced. It is a polite live region, so a screen reader reads the new number after you change a colour, without interrupting what it is saying.
• The status line is announced. The line that reports the adjusted colour or the copied link is a status region, so the outcome of both buttons is spoken as well as shown.
• The swap button is labelled "Swap text and background colours" — the arrow glyph is not left to be guessed at.
• The FAQ entries are native disclosures. Tab to a question and press Enter or Space to open it.

There are no custom keyboard shortcuts on this page, and no shortcut is needed: with seven focusable controls at most — two swatches, two hex fields, swap, and the two action buttons — tabbing is faster than remembering a key.

The checker is honest about being small. Knowing where it stops is the difference between using it well and trusting it too far.

Model limits

• WCAG 2.x only. There is no APCA or Lc score, no WCAG 3 draft measure, no colour-difference metric and no colour-vision simulation anywhere in this tool. The number it gives you is the one an auditor will quote, and nothing more.
• No alpha, no compositing. Hex values only, with no alpha channel. Text at 70% opacity, or a colour sitting over an image or a gradient, has to be flattened to its effective colour before you can test it here.
• One pair at a time. There is no batch mode, no palette import and no matrix of every colour against every other colour.
• The formula ignores weight and spread. A pass is a floor. The preview is there because the number cannot see everything that makes text readable.

Traps worth remembering

• A half-typed hex silently grades against black or white instead of your colour.
• A displayed 4.50:1 can sit beside a Fail badge, because the badge uses the unrounded ratio.
• Make it pass AA aims at 4.5:1 and nothing else, moves only the text colour, and does not keep your hue.
• The fix picks its direction from relative luminance, so mid greys travel toward white.
• Back and forward will not walk through the colours you tried; only the copied links survive.
• The UI and graphics row is measured against the adjacent colour in your real design, which may not be the background you typed here.

Where to go next

• Check a whole page — the analyzer takes a URL and reports every contrast failure on it, with the elements named. Use the checker to settle one pair; use the analyzer to find the pairs you did not know about.
• Build a palette — ramps, tints and shades, and colour extraction from an image, for when the fix has told you a colour must move and you want a family that moves with it.
• Learn the rules — plain-language articles on contrast, colour vision and readable type, including WCAG contrast and accessible colour.
• The full tool list — everything else on the site, if the checker is not the tool you actually needed.