color-contrast · diff
git:20260624.8a4fc92 to git:20260722.125074b
265 added, 241 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: color-contrast
description: >
Load this skill whenever the project contains text, UI components, icons, form
controls, data visualisations, or focus indicators — in short, almost every
project. Under no circumstances hard-code colour values without verifying
contrast ratios. Absolutely always ensure text meets 4.5:1, large text meets
3:1, and non-text UI elements meet 3:1 against adjacent colours. Test in light
mode, dark mode, and forced-colors (high contrast) mode.
---
# Color Contrast Accessibility Skill
> **Canonical source**: `examples/COLOR_CONTRAST_ACCESSIBILITY_BEST_PRACTICES.md` in `mgifford/ACCESSIBILITY.md`
> This skill is derived from that file. When in doubt, the example is authoritative.
Apply these rules whenever implementing or reviewing colour choices in HTML, CSS,
SVG, or any visual interface element.
---
## Core Mandate
Sufficient contrast between foreground and background colors is a prerequisite
for users to read text, identify UI components, perceive graphical content, and
track keyboard focus. **Color alone must never be the sole means of conveying
- information.**
+ information.** Contrast depends on the colors actually adjacent after opacity,
+ gradients, images, overlays, states, and themes are applied — a passing palette
+ is not proof the finished interface passes.
All visual interface elements that convey information or require user interaction
must meet WCAG 2.2 Level AA contrast thresholds in **light mode, dark mode, and
forced-colors (high contrast) mode**.
---
## Severity Scale (this skill)
| Level | Meaning |
| --- | --- |
| **Critical** | Contrast failure makes content or interaction completely inaccessible |
| **Serious** | Contrast failure significantly impairs access for a disability group |
| **Moderate** | Contrast issue degrades usability but content remains partially accessible |
| **Minor** | Best-practice gap; marginal impact |
+ Prioritize by user impact when time is limited: (1) text/controls required to
+ complete a task, (2) keyboard focus indicators and component states, (3)
+ errors/warnings/required fields/status messages, (4) navigation/links/labels,
+ (5) charts and information-bearing graphics, (6) supporting/secondary content.
+
---
## Critical: Text Contrast (WCAG 1.4.3)
- Normal text and images of text must meet these minimums:
-
| Text type | Minimum (AA) | Enhanced (AAA) |
| --- | :---: | :---: |
| Normal text (below 18pt / 14pt bold) | **4.5:1** | 7:1 |
| Large text (18pt+ or 14pt+ bold) | **3:1** | 4.5:1 |
| Logotypes / purely decorative text | Exempt | Exempt |
| Disabled controls | Exempt | Exempt |
- **"Large text"** means 18pt (≈ 24 CSS `px`) or larger in regular weight, or
- 14pt (≈ 18.67 CSS `px`) or larger in bold weight.
+ **"Large text"** means 18pt (≈ 24 CSS `px`) or larger at normal weight, or
+ 14pt (≈ 18.67 CSS `px`) or larger in bold. WCAG thresholds are pass/fail — do
+ not round 4.499:1 up to 4.5:1. Treat thin or unusual typefaces cautiously — a
+ combination can meet the computed threshold but stay hard to read due to
+ narrow strokes.
- ### Preferred CSS pattern — text colours via custom properties
+ The requirement covers body text, headings, link text, button/form labels,
+ **placeholder text**, text revealed on hover/focus, validation/status
+ messages, and text rendered as an image. Do not extend the logotype/decorative
+ exception to brand colors used for ordinary content.
- ```css
- :root {
- --color-text: #1a1a1a; /* contrast vs #fff: 16.75:1 ✓ */
- --color-text-muted: #595959; /* contrast vs #fff: 7.0:1 ✓ */
- --color-heading: #333333; /* contrast vs #fff: 12.63:1 ✓ */
- --color-link: #0066cc; /* contrast vs #fff: 4.52:1 ✓ */
- --color-background: #ffffff;
- }
+ If CSS specifies only a foreground or only a background, the other side may
+ come from an unknown user preference — always specify both sides of a color pair:
- @media (prefers-color-scheme: dark) {
- :root {
- --color-text: #e8e8e8; /* contrast vs #1a1a1a: 13.61:1 ✓ */
- --color-text-muted: #b0b0b0; /* contrast vs #1a1a1a: 7.0:1 ✓ */
- --color-link: #66aaff; /* contrast vs #1a1a1a: 5.74:1 ✓ */
- --color-background: #1a1a1a;
- }
- }
+ ```css
+ html { background: #ffffff; color: #1b1f23; }
+ .notice { background: #f2f6fa; color: #243447; }
```
- ### Avoid
-
```css
- /* Bad — 2.4:1 contrast, fails 1.4.3 */
+ /* Bad — fails 1.4.3 */
.placeholder { color: #aaaaaa; }
-
- /* Bad — informative text in low-contrast colour */
- .note { color: #888; } /* fails against white background */
+ .note { color: #888; }
```
+ Prefer real text over images of text (WCAG 1.4.5) — it reflows, resizes, and
+ adapts to themes; use an image of text only when the presentation is
+ customizable or essential.
+
---
## Serious: Non-text Contrast (WCAG 1.4.11)
- UI components and graphical objects required to understand or operate the
- interface must have **3:1 contrast** against adjacent colours.
-
- ### Applies to
-
- - Form input borders (text fields, checkboxes, radio buttons, selects)
- - Interactive component boundaries (buttons without text, sliders, toggles)
- - Icons and graphical objects that convey meaning
- - Charts and data visualisation elements that encode information
- - Status indicators (progress bars, meter fills)
-
- ### Does not apply to
+ Visual information needed to identify a UI component or its state, and parts
+ of a graphic needed to understand it, need **3:1 contrast** against adjacent
+ colors. Examples: a checkbox boundary that identifies the control, a check
+ mark communicating checked state, an icon in an icon-only button, a slider
+ thumb/track, an error boundary, and chart lines/sectors/symbols needed to
+ read it.
- - Decorative graphics that convey no meaning
- - Inactive / disabled components
- - Logos and brand marks
- - Graphical elements supplementary to adjacent text
+ This does not mean every decorative border must hit 3:1 — if text, shape,
+ position, or another treatment already identifies the component/state, a
+ low-contrast decorative border isn't necessarily the required information.
+ Does not apply to: purely decorative graphics, inactive/disabled components,
+ logos/brand marks, or graphics supplementary to adjacent text.
- ### Form control pattern
+ Native controls are a strong default — browsers/OS adapt them to user
+ preferences; replacing them creates responsibility for every state and mode:
```css
- /* Checkbox border must contrast 3:1 against its background */
- input[type="checkbox"] {
- --checkbox-border: #767676; /* 4.54:1 against #fff ✓ */
+ .checkbox {
appearance: none;
- width: 1.25rem;
- height: 1.25rem;
- border: 2px solid var(--checkbox-border);
- border-radius: 3px;
+ inline-size: 1.25rem;
+ block-size: 1.25rem;
+ border: 2px solid #59636e; /* test against surrounding background */
+ border-radius: 0.2rem;
}
+ .checkbox:checked {
+ border-color: #005ea8;
+ background-color: #005ea8;
+ }
```
+ Test the unchecked boundary against its background, the checked fill against
+ the surrounding background, AND the check mark against the checked fill — do
+ not rely on a code comment claiming a pair passes; measure the rendered
+ combination. Use `currentColor` for icon strokes so they adapt with the
+ button's text color.
+
---
## Serious: Use of Color (WCAG 1.4.1)
- Color alone must not be the sole means of conveying information, indicating an
- action, prompting a response, or distinguishing a visual element. A second,
- non-color cue must always accompany color.
-
- ### Common failure patterns
+ Color alone must not be the sole means of conveying information, prompting a
+ response, or distinguishing an element. Add a visible text, shape, pattern,
+ icon, or other non-color cue whenever color carries meaning.
```html
- <!-- Bad: required field indicated only by red label color -->
+ <!-- Bad: required/error indicated only by color -->
<label style="color: red;">Email address</label>
- <input type="email">
-
- <!-- Bad: error state communicated only by red border -->
<input type="email" style="border-color: red;">
- ```
- ### Preferred patterns
-
- ```html
- <!-- Good: required field — asterisk + color + screen-reader text -->
- <label>
- Email address
- <span aria-hidden="true" class="required-marker">*</span>
- <span class="sr-only">(required)</span>
- </label>
- <input type="email" aria-required="true">
-
- <!-- Good: error state — icon + text + color + aria-invalid -->
- <div class="field field--error">
- <label for="email">Email address</label>
- <input id="email" type="email"
- aria-describedby="email-error" aria-invalid="true">
+ <!-- Good: icon + text + color + aria-invalid -->
+ <div class="field" data-state="error">
+ <label for="email">Email address <span aria-hidden="true">(required)</span></label>
+ <input id="email" type="email" required aria-invalid="true" aria-describedby="email-error">
<p id="email-error" class="error-message">
- <svg role="img" aria-label="Error" aria-hidden="true">
- <use href="#icon-exclamation"></use>
+ <svg aria-hidden="true" focusable="false" viewBox="0 0 24 24">
+ <path d="M12 3 2 21h20L12 3Zm0 6v5m0 3v.01"></path>
</svg>
- Please enter a valid email address.
+ Enter an email address in the format name@example.com.
</p>
</div>
```
- ### Link distinction from surrounding text
-
- Links within body text must be distinguishable from surrounding text by more
- than color alone. Use underline (the browser default) or another non-color cue.
+ **Links in body text** must be distinguishable from surrounding text by more
+ than color — underlining is the simplest dependable pattern:
```css
- /* Good: underline preserved */
a {
- color: #0066cc;
- text-decoration: underline;
+ color: #005ea8;
+ text-decoration-line: underline;
+ text-decoration-thickness: max(1px, 0.08em);
}
```
- ---
-
- ## Serious: Focus Appearance (WCAG 2.4.13)
+ A documented exception (WCAG technique G183) permits links without a default
+ underline when link text differs from surrounding text by ≥3:1 and gains a
+ non-color cue on hover/focus — this is harder to maintain; prefer persistent
+ underlines in prose. Charts/status indicators need labels, symbols, line
+ styles, or patterns in addition to color — a separate text-equivalent table
+ does not excuse the graphic itself from contrast requirements.
- WCAG 2.2 **2.4.13 Focus Appearance** (Level AAA) requires visible keyboard focus
- indicators that:
+ ---
- 1. Enclose the focused component with an area of at least the **perimeter × 2 CSS px** in thickness.
- 2. Have **3:1 contrast** between focused and unfocused states.
- 3. Have **3:1 contrast** against every adjacent color in the unfocused state.
+ ## Serious: Keyboard Focus Appearance
- ### Preferred CSS pattern
+ WCAG 2.2 AA requires a visible focus indicator (2.4.7). **2.4.13 Focus
+ Appearance is Level AAA** — do not present its area/contrast-change formula as
+ an AA requirement. WCAG 1.4.11 may still apply to an author-created focus
+ indicator as the visual information identifying the focused state.
```css
- :root {
- --focus-ring-color: #0066cc;
- --focus-ring-width: 3px;
- --focus-ring-offset: 2px;
+ /* Start with the browser default; don't remove without a tested replacement */
+ :focus-visible {
+ outline: 3px solid #005fcc;
+ outline-offset: 3px;
}
+ /* Two-color indicator — more robust across light/dark surfaces */
:focus-visible {
- outline: var(--focus-ring-width) solid var(--focus-ring-color);
- outline-offset: var(--focus-ring-offset);
- /* White halo ensures visibility on dark backgrounds */
- box-shadow: 0 0 0 calc(var(--focus-ring-width) + var(--focus-ring-offset))
- #ffffff;
+ outline: 3px solid #ffffff;
+ outline-offset: 2px;
+ box-shadow: 0 0 0 5px #111111;
}
-
- @media (prefers-color-scheme: dark) {
- :root {
- --focus-ring-color: #99ccff;
+ @media (forced-colors: active) {
+ :focus-visible {
+ outline: 3px solid Highlight;
+ box-shadow: none;
}
}
```
- ### C40 two-color focus indicator
-
```css
- /* Works on both light and dark surfaces */
- :focus-visible {
- outline: 3px solid #000000;
- outline-offset: 1px;
- box-shadow: 0 0 0 5px #ffffff;
- }
+ /* NEVER do this without a tested replacement */
+ :focus { outline: none; }
```
- ### Avoid
+ Do not add `:focus:not(:focus-visible) { outline: none; }` as a universal
+ rule — browsers already determine when `:focus-visible` matches, and a
+ blanket suppression is risky. Test the indicator's geometry, clipping, and
+ adjacent colors on every surface and component state.
- ```css
- /* NEVER do this — completely removes focus visibility */
- :focus { outline: none; }
+ ---
- /* NEVER do this without providing an alternative focus style */
- *:focus { outline: 0 !important; }
+ ## Serious: Forced-Colors Mode
+
+ Windows High Contrast Mode / `forced-colors` replaces author colors with
+ system colors. Interfaces break when `background-color`, `box-shadow`, or
+ `color` are the sole means of conveying meaning — `outline` survives
+ forced-colors; `box-shadow` may be suppressed.
+
+ ```css
+ @media (forced-colors: active) {
+ .status-icon, .icon-button svg { fill: none; stroke: currentColor; }
+ [aria-current="page"] { border-block-end: 0.25rem solid currentColor; }
+ [aria-invalid="true"] { border: 3px solid Mark; }
+ }
```
- ---
+ Use native controls and semantic HTML first; add targeted corrections only
+ where testing shows information disappears. Avoid `forced-color-adjust: none`
+ unless preserving author colors is essential and tested against multiple
+ user-selected system palettes — it opts the element out of the mode's protections.
- ## Serious: Forced-Colors Mode (WCAG 1.4.3, 1.4.11)
+ **Testing:** enable Windows High Contrast in Accessibility settings; Chrome
+ DevTools → Rendering → "Emulate CSS media feature forced-colors: active";
+ Firefox `about:config` → `ui.forcedColors: 1`.
- Windows High Contrast Mode and `forced-colors` replace author colors with
- system colors. Interfaces break when CSS `background-color`, `box-shadow`, or
- `color` properties are the sole means of conveying meaning.
+ ---
- ### Use `outline` for focus rings — it survives forced-colors
+ ## Moderate: Themes and Semantic Color Tokens
- ```css
- /* Good: outline is forced-colors-safe */
- :focus-visible {
- outline: 3px solid Highlight;
- outline-offset: 2px;
- }
+ Validate complete foreground-background pairs, not isolated colors. Semantic
+ tokens make intended pairings explicit:
- /* Risk: box-shadow may not render in forced-colors mode */
- :focus-visible {
- box-shadow: 0 0 0 3px #0066cc; /* may be suppressed */
+ ```css
+ :root {
+ color-scheme: light dark;
+ --surface: light-dark(#ffffff, #15191e);
+ --text: light-dark(#1b1f23, #f4f6f8);
+ --link: light-dark(#005ea8, #73b7f2);
+ --control-border: light-dark(#59636e, #a7b0ba);
}
+ html { background: var(--surface); color: var(--text); }
+ .card { background: var(--surface); color: var(--text); border: 1px solid var(--control-border); }
```
- ### Restore lost meaning in forced-colors mode
+ `light-dark()` is useful when the project's browser support policy permits
+ it; provide a custom-property fallback for older browsers. See
+ `skills/light-dark-mode/SKILL.md` for a manual theme-selector implementation.
+ **Do not assume CSS color functions guarantee accessibility** — `color-mix()`
+ creates a color between two inputs but doesn't target a WCAG ratio;
+ `contrast-color()` picks from a limited result set in current implementations
+ and doesn't replace validating text/component/state requirements. Treat both
+ as implementation aids, not conformance tests.
+
```css
- @media (forced-colors: active) {
- .button {
- background-color: ButtonFace;
- color: ButtonText;
- border: 2px solid ButtonBorder;
- }
+ /* Bad: hard-coded value that may fail in dark mode */
+ .card { background-color: #ffffff; color: #333; }
+ ```
- /* Restore SVG icon visibility */
- .icon {
- forced-color-adjust: auto;
- }
+ ---
+
+ ## Serious: Variable Backgrounds, Opacity, and Overlays
+
+ For text over a gradient, image, video, or translucent surface, test the
+ **least favorable rendered region** that can occur in normal use. Use an
+ opaque or sufficiently opaque backing surface when the underlying content
+ can't be controlled:
+
+ ```css
+ .hero-title {
+ display: inline;
+ padding: 0.15em 0.35em;
+ color: #ffffff;
+ background: #16202a;
+ box-decoration-break: clone;
}
```
- ### Testing forced-colors mode
+ Be careful with `opacity` on a parent element — it blends text and background
+ with whatever is behind the component, changing both sides of the contrast
+ pair:
- - Enable **High Contrast Mode** in Windows Accessibility settings
- - Chrome DevTools → Rendering → "Emulate CSS media feature forced-colors: active"
- - Firefox: `about:config` → `ui.forcedColors: 1`
+ ```css
+ /* Avoid: reduces opacity of the whole component */
+ .secondary-card { opacity: 0.6; }
+ /* Prefer: explicit, validated colors */
+ .secondary-card { background: #f2f6fa; color: #4d5966; }
+ ```
- ---
+ Automated tools may report variable backgrounds as "incomplete" — that's a
+ limitation of the test, not evidence the content passes.
- ## Moderate: Semantic Color Token Pattern
+ ---
- Centralizing all design-system colors as CSS custom properties makes contrast
- validation and theming manageable at scale.
+ ## Moderate: States That Need Separate Validation
- ```css
- /* Token layer — raw values */
- :root {
- --color-neutral-600: #595959; /* 7.0:1 on #fff */
- --color-neutral-900: #1a1a1a; /* 16.75:1 on #fff */
- --color-brand-500: #0066cc; /* 4.52:1 on #fff — OK for normal text ✓ */
- --color-brand-700: #004c99; /* 7.59:1 on #fff — OK for all text ✓ */
+ Check each component in every state users can encounter: default, hover,
+ keyboard focus, active/pressed, selected/checked, visited, invalid/error,
+ success/warning/informational, disabled/inactive, browser autofill, text
+ selection, and open/expanded/current. Repeat across every supported theme.
- /* Semantic layer */
- --color-text-primary: var(--color-neutral-900);
- --color-text-secondary: var(--color-neutral-600);
- --color-text-link: var(--color-brand-500);
- --color-surface: #ffffff;
- --color-border: #e8e8e8; /* 3:1 for non-text ✓ */
- }
+ **Disabled controls** are excepted from 1.4.3/1.4.11's specific ratios, but
+ the exception is not a design target: keep disabled controls identifiable
+ when practical; do not communicate the disabled state by color alone; explain
+ why a control is unavailable when needed; consider whether disabling is
+ necessary at all (a submit attempt with clear validation can be easier to
+ understand than an unexplained unavailable button).
- @media (prefers-color-scheme: dark) {
- :root {
- --color-text-primary: #e8e8e8;
- --color-text-secondary: #a0a0a0; /* 7.11:1 on #1a1a1a ✓ */
- --color-text-link: #66aaff; /* 5.74:1 on #1a1a1a ✓ */
- --color-surface: #1a1a1a;
- --color-border: #444444; /* 3.1:1 vs #1a1a1a ✓ */
- }
- }
+ ```html
+ <button type="submit" disabled aria-describedby="submit-help">Submit</button>
+ <p id="submit-help">Add at least one contact before submitting.</p>
```
- ```css
- /* Good: references semantic token — works in all themes */
- .card {
- background-color: var(--color-surface);
- color: var(--color-text-primary);
- border: 1px solid var(--color-border);
- }
+ ---
- /* Bad: hard-coded value that may fail in dark mode */
- .card {
- background-color: #ffffff;
- color: #333;
+ ## Moderate: User Contrast Preferences
+
+ `prefers-contrast` and `forced-colors` address different situations — neither
+ is a light/dark theme selector. Use `prefers-contrast: more` as an
+ enhancement; the default presentation must already meet the conformance target:
+
+ ```css
+ @media (prefers-contrast: more) {
+ :root { --text-muted: var(--text); --control-border: currentColor; }
+ a { text-decoration-thickness: 0.15em; }
+ :focus-visible { outline-width: 4px; }
}
```
---
- ## Minor: APCA — Emerging Standard
-
- The **Advanced Perceptual Contrast Algorithm (APCA)** is a candidate replacement
- for the WCAG 2.x contrast ratio formula expected in WCAG 3.0. It models contrast
- perception more accurately for thin strokes, small font sizes, and saturated colors.
-
- **APCA is not yet required.** Teams adopting it today must **continue to meet
- WCAG 2.2 AA requirements** in parallel.
+ ## Minor: APCA — Emerging Standard (Not Yet Required)
- | Content type | Minimum Lc | Recommended Lc |
- | --- | :---: | :---: |
- | Normal body text (16px / 400 weight) | 60 | 75 |
- | Large heading text (24px+ / 700 weight) | 45 | 60 |
- | UI component labels | 45 | 60 |
- | Placeholder / muted text | 30 | 45 |
+ The Advanced Perceptual Contrast Algorithm (APCA) is a candidate replacement
+ for the WCAG 2.x contrast formula in WCAG 3.0, modeling perception more
+ accurately for thin strokes and small text. **APCA is not yet required** —
+ teams experimenting with it must continue meeting WCAG 2.2 AA in parallel.
+ Do not present fixed APCA thresholds as current WCAG requirements; treat
+ experimental methods as supplemental design evidence only.
---
- ## Recommended Contrast-Checking Tools
+ ## Testing
- | Tool | Use case |
- | --- | --- |
- | [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) | Quick manual text contrast checks |
- | [Colour Contrast Analyser (TPGi)](https://www.tpgi.com/color-contrast-checker/) | Desktop app for sampling on-screen colors |
- | [axe DevTools](https://www.deque.com/axe/devtools/) | Browser extension with contrast violation detection |
- | [apcacontrast.com](https://apcacontrast.com/) | APCA-based contrast evaluation |
- | [Stark (Figma/Sketch plugin)](https://www.getstark.co/) | Design-time contrast checking |
+ **Manual:** inspect actual rendered foreground/background colors (not
+ source-code values); measure text pairs without rounding; identify the visual
+ information required to find each component/state and measure it against the
+ relevant adjacent color; tab through and inspect focus on every background;
+ test all themes and component states; test Windows High Contrast/forced-colors
+ emulation; inspect gradients, images, opacity, overlays, sticky content, and
+ text selection manually. Grayscale/color-vision simulations are a review aid,
+ not a replacement for standards-based testing or lived experience.
- ### Testing programmatically with axe-core
+ **Automated:**
- ```javascript
- const axe = require("axe-core");
+ ```js
+ import { test, expect } from "@playwright/test";
+ import AxeBuilder from "@axe-core/playwright";
- axe.run(document, {
- runOnly: {
- type: "rule",
- values: ["color-contrast", "color-contrast-enhanced"]
- }
- }, (err, results) => {
- if (err) throw err;
- console.log("Contrast violations:", results.violations);
- });
+ for (const theme of ["light", "dark"]) {
+ test(`automated accessibility scan: ${theme}`, async ({ page }) => {
+ await page.goto("/");
+ await page.locator("html").evaluate((el, value) => { el.dataset.theme = value; }, theme);
+ const results = await new AxeBuilder({ page })
+ .withTags(["wcag2a", "wcag2aa", "wcag21aa", "wcag22aa"])
+ .analyze();
+ expect(results.violations).toEqual([]);
+ });
+ }
```
+ Automated tools can find many computable text contrast failures but cannot
+ reliably determine every background, required graphical detail, color-only
+ distinction, focus-indicator geometry, or forced-colors failure — use
+ automation to support manual review, not replace it. `focus-visible` and
+ `focus-order-semantics` are **not real axe-core rule IDs** — don't cite them;
+ keyboard focus appearance requires manual testing (see `skills/axe-rules/SKILL.md`
+ for the actual rule set).
+
+ **Design tokens:** maintain an explicit list of approved token pairings and
+ test those pairs when tokens change — don't test every token against every
+ other token, since many combinations aren't valid uses. Runtime tests are
+ still required because component CSS can introduce opacity/overlays that
+ token tests don't cover.
+
---
## Definition of Done Checklist
- * [ ] All normal text meets 4.5:1 contrast in light and dark modes
+ * [ ] All normal text meets 4.5:1 contrast in light and dark modes (or documented exception)
* [ ] All large text meets 3:1 contrast in light and dark modes
- * [ ] All form controls, icons, and data visualisation elements meet 3:1 non-text contrast
+ * [ ] Form controls, icons, and data-viz elements meet 3:1 non-text contrast
* [ ] No information conveyed by color alone — icon + text + color used together
* [ ] Links in body text are distinguishable from surrounding text without color
- * [ ] Focus indicators use `outline`, meet 3:1 contrast, and are visible in all modes
- * [ ] All colour tokens defined as CSS custom properties; no hard-coded values in components
- * [ ] Light mode and dark mode verified with contrast checker
+ * [ ] Focus indicators use `outline`, meet 3:1 contrast, and are visible in all modes/surfaces
+ * [ ] Color tokens defined as CSS custom properties; no hard-coded values in components
+ * [ ] Every supported theme and component state tested (hover, focus, active,
+ selected, visited, error, disabled, autofill, text selection)
+ * [ ] Text over gradients/images/overlays tested at the least favorable region
* [ ] Forced-colors / Windows High Contrast Mode tested — no meaning lost
- * [ ] axe-core `color-contrast` rule passes in CI
- * [ ] Disabled controls clearly distinguished from enabled controls beyond opacity alone
+ * [ ] axe-core `color-contrast` rule passes in CI (manual review still required)
+ * [ ] Disabled controls clearly distinguished from enabled controls beyond opacity/color alone
+ * [ ] Approved design-token pairings documented and tested
---
## Key WCAG Criteria
* 1.4.1 Use of Color (A) — **Serious if failing**
* 1.4.3 Contrast Minimum (AA) — **Critical if failing for normal text**
+ * 1.4.5 Images of Text (AA)
* 1.4.6 Contrast Enhanced (AAA)
* 1.4.11 Non-text Contrast (AA) — **Serious if failing**
* 2.4.7 Focus Visible (AA)
- * 2.4.13 Focus Appearance (AAA, WCAG 2.2) — **Serious if failing**
+ * 2.4.13 Focus Appearance (AAA, WCAG 2.2) — not an AA requirement
---
## References
* [Full best practices guide](https://github.com/mgifford/ACCESSIBILITY.md/blob/main/examples/COLOR_CONTRAST_ACCESSIBILITY_BEST_PRACTICES.md)
* [WCAG 2.2 Understanding 1.4.1 Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)
* [WCAG 2.2 Understanding 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html)
* [WCAG 2.2 Understanding 1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html)
* [WCAG 2.2 Understanding 2.4.13 Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html)
- * [WCAG 2.2 Technique C40: Creating a two-color focus indicator](https://www.w3.org/WAI/WCAG22/Techniques/css/C40)
+ * [Technique G183: Links identified by color plus another cue](https://www.w3.org/WAI/WCAG22/Techniques/general/G183)
+ * [Technique C40: Two-color focus indicator](https://www.w3.org/WAI/WCAG22/Techniques/css/C40)
+ * [Media Queries Level 5: `prefers-contrast`](https://www.w3.org/TR/mediaqueries-5/#prefers-contrast)
* [APCA contrast tool](https://apcacontrast.com/)
- > **Standards horizon:** WCAG 3.0's proposed **APCA** (Advanced Perceptual
- > Contrast Algorithm) will replace the current luminance-ratio model with a
- > perceptual contrast model that treats light-on-dark and dark-on-light
- > differently. Do not apply APCA to production work until WCAG 3.0 is a
- > published standard. Monitor: <https://www.w3.org/TR/wcag-3.0/> and
- > <https://git.apcacontrast.com/>
+ > **Standards horizon:** WCAG 3.0's proposed APCA will replace the current
+ > luminance-ratio model with a perceptual contrast model. Do not apply APCA
+ > to production conformance work until WCAG 3.0 is a published standard.
+ > Monitor: <https://www.w3.org/TR/wcag-3.0/> and <https://git.apcacontrast.com/>