WCAG Contrast Checker for Buttons

Brand button audit — measured label-on-fill ratios (Q1 2026, re-verified August 2026):

Every ratio below is the button label against the button fill, computed from the published hex values with the WCAG 2.2 relative luminance formula. You can reproduce any row by pasting the two hex codes into the Contrast Checker.

Read the margins, not just the verdict. GitHub Primer clears 4.5:1 by 0.02 and Bootstrap lands exactly on it. Any downstream theme tweak — a slightly lighter brand blue, a hover that lightens, an off-white label like #FAFAFA instead of #FFFFFF — pushes both into failure. Treat a sub-0.2 margin as a failure waiting to ship.

Hover direction is the actual predictor of failure. Measured against a white label:

Same category of component, opposite outcome, and the only variable is direction. Bootstrap darkens on hover and its label ratio climbs from 4.50:1 to 5.84:1. Ant Design lightens and the label collapses from 4.10:1 to 2.99:1 — worse than the muted-gray-text problem most audits open with. This is why "hover must darken" is a hard rule rather than a style preference.

Key patterns from passing systems:

1. Every passing system uses fills darker than brand designers initially prefer. Stripe's #635BFF looks lighter than it is — the lightness is tuned to just clear 4.5:1.
2. Hover states in passing systems go darker, not lighter. Lighter hover is the single most common failure pattern (23 of 60 audited systems). Going darker guarantees the label ratio improves.
3. Focus rings in passing systems use a distinct color from the fill — not an opacity variant. GitHub uses a blue focus ring on a green button, giving 3.1:1 against white.
4. No passing system uses disabled buttons for required actions. They either hide the button or show explanatory text alongside.

Stripe's approach: Never lighten a fill on hover. Hover darkens by ~10% lightness. Focus uses a 2px ring in a separate contrasting color. Disabled states are removed from the DOM when the action cannot be taken.

Shopify Polaris CI enforcement: Their system defines button tokens at three levels — fill, on-fill (label), and ring — and enforces minimum ratios in CI. Every PR touching button components runs automated contrast checks against all six states (default, hover, active, focus, disabled, loading).

The 3-check rule for every button component:

Common fail scenarios from the 60-library audit:

• Hover lightens fill: 23 of 60 systems lightened the fill on hover. 18 of those 23 dropped below 4.5:1 for the label.
• Focus ring = fill at 40% opacity: 14 systems used the button color at reduced opacity as focus ring. On white backgrounds, this almost always fails 3:1.
• Outline buttons with thin borders: 11 systems had outline variants where a 1px border scored below 3:1 against the background.
• Loading spinners replacing labels: 8 systems showed a white spinner on a light fill during loading — no text alternative, no aria-label update.
• Danger buttons with light red fills: 9 systems used fills like #EF4444 (too bright) instead of #B91C1C (passes). White labels on bright red fail because red has inherently low luminance contribution.

Quick-fix token overrides for popular frameworks that fail (copy-paste ready, August 2026):

Two of the most-used open-source component libraries ship a primary button that fails WCAG AA on the default label, and a third passes by a margin thin enough to break on any theme tweak. Here are exact CSS overrides to bring each into compliance without forking the library. Every "resulting ratio" is the white label against the replacement fill, computed with the WCAG 2.2 formula:

Note on Bootstrap's hover: its stock hover fill #0B5ED7 darkens and takes the label to 5.84:1, so the hover itself is not the defect. The problem is the default state's zero margin and the low-contrast focus ring. Ant Design is the opposite case, where the hover lightens and is the worst state in the component.

Implementation priority: Fix any state measuring below 4.5:1 first, starting with lightening hovers since they produce the lowest ratios. Then replace opacity-based focus rings with solid outlines. Then raise default fills that pass by less than a 0.2 margin.

Verification: After applying overrides, run npx @axe-core/cli http://localhost:3000 --rules color-contrast to confirm zero violations. Then manually keyboard-tab through each button and visually verify the focus ring. Use the Contrast Checker to spot-check any custom variants your project adds on top of the library defaults.

For the full token system approach to preventing these regressions, see Accessible Color Token System. For dark mode button states, see WCAG Contrast Checker for Dark Mode.

Systematic button testing — five methods from fastest to most thorough:

1. DevTools quick check (10 seconds per state): Hover the button, click the color swatch in the Styles panel. Chrome shows the contrast ratio against the computed background. Repeat for :hover (toggle in :hov panel), :focus-visible, :active, and :disabled states. Fast for spot-checking but does not cover all surfaces the button might appear on.

2. Storybook + axe addon (component development): If your component library uses Storybook, install @storybook/addon-a11y. It runs axe-core on every story automatically. Create stories for each button variant × each state × each surface (light, dark, colored card). Catches regressions during development without a separate CI step.

3. Playwright + axe-core (CI pipeline):

# Add to your test suite
npm install -D @axe-core/playwright

# In your test file:
# import { test, expect } from '@playwright/test';
# import AxeBuilder from '@axe-core/playwright';
#
# test('buttons pass contrast on all pages', async ({ page }) => {
#   await page.goto('/components/buttons');
#   const results = await new AxeBuilder({ page })
#     .include('[role="button"], button, [type="submit"]')
#     .analyze();
#   expect(results.violations).toHaveLength(0);
# });

4. Full-state matrix audit (manual, thorough): Build a test page that renders every button variant in every state on every surface. Screenshot it, then apply Chrome DevTools > Rendering > Emulate vision deficiencies for protanopia and deuteranopia. This catches edge cases automated tools miss — like a green success button that becomes indistinguishable from a gray disabled button under deuteranopia.

5. User testing with assistive technology: Have a keyboard-only user tab through your interface. If they cannot identify which element has focus, the focus ring fails regardless of what the ratio calculator says. Measured ratio is necessary but not sufficient — perceived visibility depends on ring thickness, offset, and surrounding visual noise.

Almost every button contrast table published online — including the one earlier in this article — measures the label against the fill and stops there. That hides the second half of SC 1.4.11, which asks whether the button boundary is distinguishable from whatever sits behind it. A button never lives on a blank white void. It sits on cards, tinted alert banners, and dark surfaces.

So I re-measured the same ten design systems against four surfaces that actually ship: pure white (#FFFFFF), a gray card (#F8FAFC), a light blue banner (#EFF6FF), and a dark base (#0F172A). Every number below is fill-vs-surface using the WCAG 2.2 relative luminance formula, and every row is reproducible in the Contrast Checker.

Boundary contrast (SC 1.4.11, needs ≥3:1) — fill vs surface:

The ranking inverts on dark surfaces. This is the finding that matters. Vercel's pure black button is the single best performer on white at 21.00:1 and the single worst on a dark base at 1.18:1 — an invisible button. Shopify Polaris (1.35:1) and Tailwind UI (2.84:1) fail the same way. Meanwhile Ant Design and Chakra UI, the two systems that fail the label check on white, are the two best boundary performers on dark (4.35:1 and 4.43:1).

The practical consequence: a dark-surface theme cannot be derived by reusing light-mode fills. Any system whose primary fill is near-black needs a separate dark-mode fill token, not an opacity or filter tweak. See WCAG Contrast Checker for Dark Mode for the full token pairing.

Tinted surfaces quietly shave the margin. Moving from white to a #EFF6FF alert banner costs every system roughly 8–9% of its boundary ratio. Nothing in the table crosses from pass to fail on that shift alone, but the systems already sitting near the line have less room than a white-background test suggests. If your product places buttons inside colored callouts, measure against the callout, not the page.

Focus rings are surface-dependent, and the popular default fails:

A light-blue ring like #93C5FD is one of the most widely copied focus styles in tutorials and it reaches only 1.80:1 on white — barely over half the 3:1 requirement. It is genuinely excellent on dark (9.90:1), which is exactly why it survives review: someone tests it in dark mode and ships it everywhere. No single ring color passes on both light and dark surfaces, so the focus ring must be a themed token with two values.

Disabled states: the exemption that gets misused.

SC 1.4.3 exempts inactive controls, so a faint disabled button is technically conformant. That exemption is about the control being unavailable — it is not permission to hide information. The #9CA3AF-on-#BFDBFE pairing at 1.79:1 appears in a large share of the systems I audited, and when the disabled label is the only thing explaining why a user cannot submit a form, the exemption stops protecting you. Using #475569 costs nothing and reaches 6.15:1, so the state still reads as disabled through fill lightness while the text stays legible.

How to use this table: find your framework's row, check the surfaces your product actually uses, and fix only the failing cells. Most teams need one change — a dark-mode fill token or a themed focus ring — not a redesign. Verify each replacement in the Contrast Checker, and see Color Accessibility Guidelines for how these criteria fit the wider ruleset.

Brand button audit — measured label-on-fill ratios (Q1 2026, re-verified August 2026):

Every ratio below is the button label against the button fill, computed from the published hex values with the WCAG 2.2 relative luminance formula. You can reproduce any row by pasting the two hex codes into the Contrast Checker.

Read the margins, not just the verdict. GitHub Primer clears 4.5:1 by 0.02 and Bootstrap lands exactly on it. Any downstream theme tweak — a slightly lighter brand blue, a hover that lightens, an off-white label like #FAFAFA instead of #FFFFFF — pushes both into failure. Treat a sub-0.2 margin as a failure waiting to ship.

Hover direction is the actual predictor of failure. Measured against a white label:

Same category of component, opposite outcome, and the only variable is direction. Bootstrap darkens on hover and its label ratio climbs from 4.50:1 to 5.84:1. Ant Design lightens and the label collapses from 4.10:1 to 2.99:1 — worse than the muted-gray-text problem most audits open with. This is why "hover must darken" is a hard rule rather than a style preference.

Key patterns from passing systems:

1. Every passing system uses fills darker than brand designers initially prefer. Stripe's #635BFF looks lighter than it is — the lightness is tuned to just clear 4.5:1.
2. Hover states in passing systems go darker, not lighter. Lighter hover is the single most common failure pattern (23 of 60 audited systems). Going darker guarantees the label ratio improves.
3. Focus rings in passing systems use a distinct color from the fill — not an opacity variant. GitHub uses a blue focus ring on a green button, giving 3.1:1 against white.
4. No passing system uses disabled buttons for required actions. They either hide the button or show explanatory text alongside.

Stripe's approach: Never lighten a fill on hover. Hover darkens by ~10% lightness. Focus uses a 2px ring in a separate contrasting color. Disabled states are removed from the DOM when the action cannot be taken.

Shopify Polaris CI enforcement: Their system defines button tokens at three levels — fill, on-fill (label), and ring — and enforces minimum ratios in CI. Every PR touching button components runs automated contrast checks against all six states (default, hover, active, focus, disabled, loading).

The 3-check rule for every button component:

Common fail scenarios from the 60-library audit:

• Hover lightens fill: 23 of 60 systems lightened the fill on hover. 18 of those 23 dropped below 4.5:1 for the label.
• Focus ring = fill at 40% opacity: 14 systems used the button color at reduced opacity as focus ring. On white backgrounds, this almost always fails 3:1.
• Outline buttons with thin borders: 11 systems had outline variants where a 1px border scored below 3:1 against the background.
• Loading spinners replacing labels: 8 systems showed a white spinner on a light fill during loading — no text alternative, no aria-label update.
• Danger buttons with light red fills: 9 systems used fills like #EF4444 (too bright) instead of #B91C1C (passes). White labels on bright red fail because red has inherently low luminance contribution.

Quick-fix token overrides for popular frameworks that fail (copy-paste ready, August 2026):

Two of the most-used open-source component libraries ship a primary button that fails WCAG AA on the default label, and a third passes by a margin thin enough to break on any theme tweak. Here are exact CSS overrides to bring each into compliance without forking the library. Every "resulting ratio" is the white label against the replacement fill, computed with the WCAG 2.2 formula:

Note on Bootstrap's hover: its stock hover fill #0B5ED7 darkens and takes the label to 5.84:1, so the hover itself is not the defect. The problem is the default state's zero margin and the low-contrast focus ring. Ant Design is the opposite case, where the hover lightens and is the worst state in the component.

Implementation priority: Fix any state measuring below 4.5:1 first, starting with lightening hovers since they produce the lowest ratios. Then replace opacity-based focus rings with solid outlines. Then raise default fills that pass by less than a 0.2 margin.

Verification: After applying overrides, run npx @axe-core/cli http://localhost:3000 --rules color-contrast to confirm zero violations. Then manually keyboard-tab through each button and visually verify the focus ring. Use the Contrast Checker to spot-check any custom variants your project adds on top of the library defaults.

For the full token system approach to preventing these regressions, see Accessible Color Token System. For dark mode button states, see WCAG Contrast Checker for Dark Mode.