What is the color-contrast skill?
color-contrast is a skill in mgifford/accessibility-skills that requires 4.5:1 contrast for normal text, 3:1 for large text and non-text UI elements, and a visible focus indicator at 3:1, checked across every theme. It runs automated axe-core scans for computable failures and calls for manual checks of color-only meaning, variable backgrounds and forced-colors mode.
color-contrast is one skill in mgifford/accessibility-skills. It applies to nearly any project with text, icons, form controls or data visualization, checking rendered color pairs against WCAG 2.2 contrast thresholds rather than a palette in isolation.
The skill is organized by severity: critical text-contrast failures, serious issues such as missing non-text contrast or a color-only distinction, and moderate gaps like an untested theme or component state.
What changes in the agent's output
- Normal text gets checked against a 4.5:1 ratio and large text against 3:1, measured on the actual rendered foreground and background pair.
- Non-text elements such as checkbox borders, icon-only buttons and chart lines get a 3:1 check, since WCAG 1.4.11 covers more than body copy.
- Links in body text get an underline or a brightness difference of at least 3:1, so color is never the only signal separating a link from plain text.
- A forced-colors media query gets tested, since Windows High Contrast replaces author colors with system ones and can hide a background-only cue.
Testing it runs
Playwright paired with axe-core scans for computable text contrast failures across themes. The skill is explicit that automation catches text contrast but still needs a manual pass for graphical details, focus geometry and forced-colors behavior.
Who the color-contrast skill is for
Best for
- Any UI with text, icons, charts or form controls going into light and dark themes.
- Teams that need every interactive state, not only the default, checked for contrast.
- Projects already testing with Windows High Contrast or the forced-colors media query.
Not for
- If your job is mostly building tonal elevation and three-tier color tokens for dark mode, the dark-mode-design-expert skill is the better fit for that.
- When the task is a full WCAG 2.2 quick reference with axe-core automation, the accessibility-testing skill is the better fit for that.
- If your job is mostly checking every theme for missing tokens and switch regressions, the theme-audit skill is the better fit for that.
Use it with UiChemy
Contrast fixes apply to colors already chosen for a page. Once a palette passes, UiChemy AI to WordPress carries that front-end build into an editable WordPress page.
How to install Color Contrast Skill for AI Coding Agents
npx skills add mgifford/accessibility-skills --skill color-contrastInstall just this skill
Run
npx skills add mgifford/accessibility-skills --skill color-contrastto add color-contrast on its own.Or install the full set
Run
npx skills add mgifford/accessibility-skillswithout a --skill flag to pull in every accessibility skill in the repository.Ask for a contrast check by name
Mention contrast, WCAG or a specific color pair in your prompt and the agent pulls in color-contrast to check it.
Check that it loaded
Ask the agent to check a button's text against its background and confirm it reports a measured ratio against the 4.5:1 or 3:1 threshold rather than a visual impression.
Key features
- Text contrast thresholdsNormal text under 18pt needs 4.5:1 contrast and large text needs 3:1, measured against the actual rendered background rather than assumed from a static mockup.
- Non-text contrast ruleCheckbox boundaries, slider controls, icon-only buttons and chart elements get a 3:1 check under WCAG 1.4.11, since contrast failures are not limited to body text.
- Use of color checkStatus, errors and links need a non-color signal, such as an underline, icon or label, alongside any color coding, so color alone never carries required meaning.
- Focus indicator ruleKeyboard focus needs a visible indicator, commonly a three-pixel outline with a three-pixel offset or a two-color ring, rather than relying on the browser default or none at all.
- Forced-colors mode testingWindows High Contrast and the forced-colors media query get tested directly, since author background colors and box shadows can disappear under system color overrides.
- Semantic token validationApproved foreground and background token pairs get documented and retested whenever a token changes, since component CSS can still introduce an opacity or overlay that breaks a pairing.
- Variable background testingText over a gradient, image or translucent surface gets checked at its least-favorable rendered region, not just wherever it happens to look fine first.
- Automated axe-core scansA Playwright and axe-core scan with the WCAG 2.2 AA tag set runs across themes, catching computable text contrast failures before a manual review starts.
Frequently asked questions
What is the color-contrast skill?
It is a skill in mgifford/accessibility-skills that checks text, icons, form controls and data visualization against WCAG 2.2 contrast thresholds, covering normal and large text, non-text UI elements, focus indicators and forced-colors mode across every theme a project supports.
How do I install the color-contrast skill?
Run npx skills add mgifford/accessibility-skills --skill color-contrast to add just this skill, or drop the --skill flag to install the full accessibility skill set from the same repository in one pass.
What contrast ratio does color-contrast require for text?
Normal text under 18pt, or 14pt bold, needs 4.5:1 contrast against its background. Large text at or above that size only needs 3:1. Both ratios get measured against the actual rendered colors rather than values picked from a palette.
Does color-contrast check anything besides text?
Yes. WCAG 1.4.11 covers non-text contrast, so checkbox borders, slider controls, icon-only buttons and chart elements each get a 3:1 check, separate from the text contrast rules that apply to body copy and headings.
How does color-contrast handle forced-colors mode?
It tests directly against the forced-colors media query and Windows High Contrast settings, since those modes replace author background colors and box shadows with system colors, which can hide a cue that relied only on a background difference.
Does color-contrast rely only on automated tools?
No. A Playwright and axe-core scan catches computable text contrast failures across themes, but the skill calls for a manual pass as well, since automation cannot judge every graphical detail, focus geometry issue or forced-colors failure on its own.
What does color-contrast require for keyboard focus indicators?
A visible focus indicator, commonly a three-pixel solid outline with a three-pixel offset or a two-color ring for busy backgrounds, rather than removing the browser's default outline without a tested replacement in place.