{
    "slug": "colour_contrast",
    "term": "Colour Contrast",
    "category": "accessibility",
    "difficulty": "beginner",
    "short": "The ratio between foreground and background colours — WCAG requires 4.5:1 for normal text and 3:1 for large text at AA level, ensuring readability for low-vision users.",
    "long": "Contrast ratio is calculated from relative luminance: 1:1 (identical) to 21:1 (black on white). WCAG AA requires: 4.5:1 for text under 18pt (or 14pt bold), 3:1 for large text (18pt+ or 14pt+ bold), 3:1 for UI components and graphical objects. WCAG AAA requires 7:1 for normal text. Grey text on white, light text on coloured backgrounds, and disabled-looking active elements are common failures. Tools: Colour Contrast Analyser, browser DevTools accessibility panel.",
    "aliases": [
        "contrast ratio",
        "WCAG contrast",
        "colour accessibility"
    ],
    "tags": [
        "accessibility",
        "css",
        "design"
    ],
    "misconception": "As long as text is readable to most users, contrast is fine — 15% of men have some form of colour vision deficiency; what appears high contrast to some fails completely for others.",
    "why_it_matters": "Low contrast text is unreadable for low-vision users, users in bright sunlight, and the ~10% of the population with colour vision deficiency — it is also a common WCAG audit failure.",
    "common_mistakes": [
        "Grey text that looks 'modern' but fails contrast — #999999 on white is 2.85:1, failing WCAG AA.",
        "Placeholder text as the only hint — placeholder disappears on input and typically has low contrast.",
        "Colour alone to convey meaning — red/green distinction fails for colour-blind users; add icons or text.",
        "Not testing interactive states — focus, hover, and active states must also meet contrast requirements."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "wcag_guidelines",
        "accessibility_aria",
        "css_custom_properties"
    ],
    "prerequisites": [
        "wcag_guidelines",
        "accessible_colour_design",
        "css_custom_properties"
    ],
    "refs": [
        "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum"
    ],
    "bad_code": "/* Common contrast failures:\n.text-muted { color: #999; }         /* 2.85:1 on white — FAIL */\n.subtitle   { color: #aaa; }         /* 2.32:1 on white — FAIL */\n.error      { color: #f00; }         /* 3.99:1 on white — FAIL for normal text */\n.link       { color: #6699cc; }      /* 3.04:1 on white — FAIL */",
    "good_code": "/* WCAG AA passing contrast ratios on white (#fff):\n.text-muted { color: #767676; }      /* 4.54:1 — PASS AA */\n.subtitle   { color: #595959; }      /* 7.0:1 — PASS AAA */\n.error      { color: #d93025; }      /* 4.75:1 — PASS AA */\n.link       { color: #0066cc; }      /* 4.51:1 — PASS AA */\n/* Test at: https://webaim.org/resources/contrastchecker/ */",
    "quick_fix": "Check contrast ratio with the browser DevTools Accessibility panel or Colour Contrast Analyser — body text needs 4.5:1 minimum, large text (18pt+ or 14pt bold) needs 3:1",
    "severity": "high",
    "effort": "low",
    "created": "2026-03-15",
    "updated": "2026-03-22",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/colour_contrast",
        "html_url": "https://codeclaritylab.com/glossary/colour_contrast",
        "json_url": "https://codeclaritylab.com/glossary/colour_contrast.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Colour Contrast](https://codeclaritylab.com/glossary/colour_contrast) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/colour_contrast"
            }
        }
    }
}