Color Accessibility Guidelines

why it matters

Testing & Standards

CI/CD color accessibility gate — GitHub Actions + axe-core (blocks PRs on contrast failures)

# .github/workflows/a11y-contrast.yml
# Blocks PRs that introduce WCAG 2.2 color contrast violations
# Runs against both light and dark mode

name: Color Accessibility Gate
on: [pull_request]

jobs:
  contrast-audit:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        theme: [light, dark]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run build
      - run: npx serve out -l 3000 &
      - run: npx wait-on http://localhost:3000

      - name: Run axe-core contrast audit (${{ matrix.theme }} mode)
        run: |
          npx @axe-core/cli http://localhost:3000 \
            --tags wcag2aa,wcag22aa \
            --rules color-contrast,link-in-text-block \
            --exit \
            --chromedriver-path $(which chromedriver) \
            ${{ matrix.theme == 'dark' && '--chrome-options="--force-dark-mode"' || '' }}

      # Bonus: screenshot CVD simulation for manual review
      - name: Generate CVD simulation screenshots
        if: always()
        run: |
          npx playwright test tests/a11y-screenshots.spec.ts
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: cvd-screenshots-${{ matrix.theme }}
          path: test-results/cvd-*.png

---
// tests/a11y-screenshots.spec.ts
import { test } from '@playwright/test';

const pages = ['/', '/color-accessibility-hub/', '/contrast-checker/'];
const cvdTypes = ['deuteranopia', 'protanopia', 'tritanopia'];

for (const url of pages) {
  for (const cvd of cvdTypes) {
    test(`CVD screenshot: ${url} - ${cvd}`, async ({ page }) => {
      await page.emulateVisionDeficiency(cvd);
      await page.goto(`http://localhost:3000${url}`);
      await page.screenshot({
        path: `test-results/cvd-${url.replace(/\//g, '_')}-${cvd}.png`,
        fullPage: true,
      });
    });
  }
}

---
// Quick browser console audit (paste to spot-check any page)
function luminance(r, g, b) {
  const [rs, gs, bs] = [r, g, b].map(c => {
    c = c / 255;
    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
  });
  return 0.2126 * rs + 0.7152 * gs + 0.0722 * bs;
}
const failures = [];
document.querySelectorAll('*').forEach(el => {
  const s = getComputedStyle(el);
  if (!el.textContent?.trim() || s.display === 'none') return;
  const fg = s.color.match(/\d+/g)?.map(Number) || [0,0,0];
  const bg = s.backgroundColor.match(/\d+/g)?.map(Number) || [255,255,255];
  const l1 = luminance(...fg), l2 = luminance(...bg);
  const ratio = (Math.max(l1,l2)+.05)/(Math.min(l1,l2)+.05);
  const sz = parseFloat(s.fontSize);
  const min = (sz >= 18 || (sz >= 14 && +s.fontWeight >= 700)) ? 3 : 4.5;
  if (ratio < min) failures.push({ el: el.tagName, text: el.textContent.slice(0,30), ratio: ratio.toFixed(2), need: min });
});
console.table(failures);

Copy and paste into your project — free to use.

Pro Tips

• ▸
  Target AAA (7:1) for body copy, not just AA (4.5:1). Real users have cheap screens, sunlight, aging eyes, and low brightness. The WCAG minimum is a legal floor, not a design goal.
• ▸
  Never rely on color alone to convey information (SC 1.4.1). Test by taking a grayscale screenshot — if you lose any meaning, add icons, patterns, labels, or border width changes.
• ▸
  Run axe-core in CI against BOTH light and dark themes. Dark mode failures increased from 54% to 63% in my H1 2026 audit because teams ship dark mode without separate contrast verification.
• ▸
  Links inside paragraphs need more than color. The safest pattern: underline by default, remove on hover. If your design forbids underline, ensure 3:1 contrast between link and surrounding text.
• ▸
  WCAG 2.2 SC 2.4.13 Focus Appearance: 3:1 against adjacent colors + minimum area of 2px perimeter around the component. Use outline: 2px solid; outline-offset: 2px as a safe default.
• ▸
  Avoid pure #000 on #FFFFFF for body text — 21:1 causes halation for the 30% of users with astigmatism. #111827 on white (15.4:1) reads better at no accessibility cost.
• ▸
  Automated tools (axe-core, Lighthouse) catch 30-40% of issues. The other 60% requires manual testing: keyboard navigation, screen reader flow, forced-colors mode, CVD simulation. Budget 2 hours per quarterly audit.
• ▸
  When brand colors fail contrast, create a 'reading variant' token: same hue family, adjusted lightness to hit 7:1. Brand color stays for logos and large accents; reading variant goes on text. See Color Blind Friendly Palettes for hue-safe construction.
• ▸
  The EAA 5% revenue penalty is calculated per product, not per company. A company with three non-compliant digital products faces three separate fine calculations. Audit each product separately.
• ▸
  Prepare for WCAG 3.0 now: use APCA Lc 75+ for body text, Lc 60+ for large headings, Lc 45+ for non-text elements. These targets are stricter than WCAG 2 AA but will save emergency rework when the standard finalizes. See WCAG Contrast Ratio for Text for the full APCA font-weight budget.
• ▸

  Framework-specific safe defaults that pass WCAG AA without thinking:

  UI Role	Tailwind class	CSS custom property	Measured on #FFFFFF
  Body text	text-gray-800 (#1f2937)	--text-primary: #1f2937	14.7:1
  Muted text	text-gray-600 (#4b5563)	--text-muted: #4b5563	7.6:1
  Placeholder	placeholder:text-gray-500 (#6b7280)	--text-placeholder: #6b7280	4.8:1
  Input border	border-gray-500 (#6b7280)	--border-input: #6b7280	4.8:1
  Focus ring	ring-2 ring-blue-600 ring-offset-2	outline: 3px solid #2563eb	5.2:1
  Error text	text-red-700 (#b91c1c)	--text-error: #b91c1c	6.5:1
  Link text	text-blue-700 (#1d4ed8)	--text-link: #1d4ed8	6.7:1

  Every row clears AA on white, but only body text, muted text, and error text clear it with room to spare. Placeholder and input border sit at 4.8:1 — they pass on white and fail on any tinted input surface, so do not reuse them on gray-50 or a colored form background. Note that error text at 6.5:1 is AA, not AAA; the commonly repeated claim that red-700 is a 7:1 token is wrong by 0.5 points. Verify your actual surface with the Contrast Checker. For dark mode equivalents, see WCAG Contrast Checker for Dark Mode. For the full token system approach, see Accessible Color Token System.