agentleFS
AdilSiddiquiHQAdilSiddiquiHQ/a11y-skills/skills/fix-color-contrast/SKILL.md

fix-color-contrast

Skill0 starsChanged 29 days agoMITView on GitHub

Use when text or a UI control is hard to read against its background, or when a palette needs a fix that keeps the brand colour while passing WCAG contrast minimums.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not guess these. They are the whole task:

    line 21
  2. Distinctive:

    Decide which side to move: Prefer darkening the foreground over lightening the background: it preserves the background's role in the design …

    line 59
  3. Distinctive:

    Never fix contrast by removing the colour: If the only way to pass is to make two states identical, the design needs a second cue — see …

    line 73

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fix colour contrast

Criteria: SC 1.4.3 Contrast (Minimum), SC 1.4.6 Contrast (Enhanced), SC 1.4.11 Non-text Contrast, SC 1.4.1 Use of Color

Make text and UI components meet the WCAG 2.2 contrast minimums without replacing the brand colour — adjust lightness, keep the hue.

When to use

  • A contrast checker (axe, Lighthouse, a design review) reports a failure.
  • A palette is being chosen and you want the thresholds applied up front.
  • Someone asks "is this grey readable on white?"

The thresholds, exactly

Do not guess these. They are the whole task:

WhatMinimumCriterion
Body text under 24px4.5:1SC 1.4.3 Contrast (Minimum), AA
Large text: ≥24px, or ≥18.66px bold3:1SC 1.4.3, AA
Icons, borders, focus rings, chart lines, form control outlines3:1SC 1.4.11 Non-text Contrast, AA
Any text (stricter, optional)7:1SC 1.4.6 Contrast (Enhanced), AAA

Anchors worth memorising, on white:

Foreground on #FFFFFFRatioVerdict
#00000021:1passes everything
#7676764.54:1the lightest grey that passes AA for body text
#9494943.03:1passes non-text only; fails as body text
#B0B0B0~2.1:1fails everything for text

Procedure

  1. Compute the ratio. Relative luminance, per WCAG's definition — do not eyeball it, and do not use a "luminosity" helper from a plotting library, which is a different formula and gives wrong answers near the threshold.

    const channel = (c) => {
      const s = c / 255;
      return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
    };
    const luminance = ([r, g, b]) =>
      0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
    const ratio = (a, b) => {
      const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
      return (hi + 0.05) / (lo + 0.05);
    };
    ratio([118, 118, 118], [255, 255, 255]); // 4.54
  2. Decide which side to move. Prefer darkening the foreground over lightening the background: it preserves the background's role in the design and produces the smallest visual change. Only move the background if the foreground colour is fixed by brand.
  3. Search along the lightness axis, keeping hue and saturation. Walk the foreground toward black in small steps and stop at the first value that passes. Stopping at the first passing value keeps the colour as close to the original design intent as possible.
  4. Check the states you forgot. A link that passes at rest fails on :hover, :visited or against a .selected row background. Enumerate states and re-run the check on each pair.
  5. Never fix contrast by removing the colour. If the only way to pass is to make two states identical, the design needs a second cue — see below.
  6. Decide once whether you are targeting AA or AAA. SC 1.4.3 asks for 4.5:1 and is required for conformance. SC 1.4.6 asks for 7:1 and is not required by any AA baseline — but a house rule of 7:1 for body text at design time costs nothing and removes an entire class of complaint from older readers. The mistake is to apply it inconsistently: a palette that advertises AAA and then exempts the muted grey used for timestamps and captions is neither, and the exemptions are always the text people actually struggle with. axe's color-contrast-enhanced rule checks the 7:1 target and ships disabled by default, so an AAA claim needs the rule enabled or it is unchecked.

Verify

// Assert, do not eyeball. This is the check that goes in the test suite.
for (const [fg, bg, min] of [
  [[118, 118, 118], [255, 255, 255], 4.5],  // body text
  [[148, 148, 148], [255, 255, 255], 3.0],  // icon
]) {
  const r = ratio(fg, bg);
  console.log(r.toFixed(2), r >= min ? 'pass' : 'FAIL');
}

Also confirm the colour is not the only signal, which is a separate criterion (SC 1.4.1 Use of Color):

<!-- Fails SC 1.4.1: red text is the only thing marking the error -->
<p style="color:#c00">Enter a valid date</p>

<!-- Passes: an icon and a word carry the meaning, colour is decoration -->
<p style="color:#c00"><span aria-hidden="true">✕</span> Error: enter a valid date</p>

Failure modes

  • Using a contrast tool's "close enough" rounding. 4.49 is a failure. The threshold is not a guideline.
  • Checking only #fff backgrounds. The same grey on a tinted surface (#F6F8FA, a zebra-striped row, a disabled field) is a different ratio. Enumerate the real backgrounds.
  • Testing large text as body text. A 24px heading is allowed 3:1. Flagging it as a failure wastes the reviewer's time and erodes trust in the report.
  • Forgetting translucent overlays. rgba(0,0,0,.6) over an image has no single ratio; it depends on the pixel underneath. Either sample the worst case or state that it cannot be determined statically.
  • Applying "contrast" to a logo or a photograph. Logos and incidental imagery are exempt from SC 1.4.3. Do not report them.
  • Making the focus ring pass contrast and then removing it. SC 2.4.7 is separate and stricter in practice: an indicator that exists but cannot be seen is a failure of its own.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.