Skip to main content

Accessibility Testing

WCAG 2.1 AA compliance testing dashboard with color contrast validation for light and dark modes

Tags:
accessibilitywcagcontrasttesting
Last updated: 2025-10-24T00:00:00.000Z

Accessibility Testing

Our design system is built with accessibility as a core principle, ensuring WCAG 2.1 AA compliance across all components and color combinations in both light and dark modes.

Color Contrast Testing

Test any color combination against WCAG 2.1 guidelines to ensure proper contrast ratios for text and UI elements.

Testing pure neutral gray combinations for WCAG 2.1 AA compliance. All text should maintain a contrast ratio of at least 4.5:1 (AA) or 7:1 (AAA).

Compliance Summary

Overview of our design system's accessibility compliance across all color pairs and modes.

✓
WCAG 2.1 AA Compliant
Visual hierarchy meets contrast requirements
✓
Grayscale First Design
Works without any color dependency
✓
Keyboard Accessible
All components keyboard navigable
✓
Screen Reader Ready
Proper ARIA attributes implemented
✓
Focus Management
Clear focus indicators throughout
✓
3-Tier Hierarchy
Primary, Secondary, Tertiary distinction

WCAG Compliance Testing

Comprehensive breakdown of all color combinations and their WCAG compliance status. Toggle your site theme to see compliance update for light and dark modes.

19 of 34 pairs compliant · 13 AAA · 6 AA

background/headingH1 15.75:1
AAA
background/headingH2 15.74:1
AAA
background/headingH3 15.74:1
AAA
background/headingH4 15.72:1
AAA
background/textBody 9.61:1
AAA
background/textSecondary 6.67:1
AA
background/textTertiary 4.17:1
fail
background/textDisabled 2.47:1
fail
background/foreground 15.75:1
AAA
background/foregroundSecondary 9.61:1
AAA
background/foregroundTertiary 6.67:1
AA
background/foregroundDisabled 2.47:1
fail
background/primary 3.00:1
fail
background/primaryHover 2.99:1
fail
background/primaryMuted 2.99:1
fail
background/secondary 2.74:1
fail
background/secondaryHover 2.38:1
fail
background/secondaryMuted 2.07:1
fail
background/error 2.99:1
fail
background/warning 3.60:1
fail
background/success 10.71:1
AAA
background/info 1.80:1
fail
surface/foreground 14.36:1
AAA
surface/foregroundSecondary 8.76:1
AAA
surface/foregroundTertiary 6.08:1
AA
surface/foregroundDisabled 2.25:1
fail
surface/primary 2.73:1
fail
surface/secondary 2.50:1
fail
surfaceSecondary/foreground 12.56:1
AAA
surfaceSecondary/foregroundSecondary 7.66:1
AAA
surfaceSecondary/foregroundTertiary 5.32:1
AA
surfaceTertiary/foreground 10.97:1
AAA
surfaceTertiary/foregroundSecondary 6.69:1
AA
surfaceTertiary/foregroundTertiary 4.65:1
AA

Semantic HTML Examples

Proper semantic HTML is crucial for accessibility. Our components use appropriate ARIA labels and roles.

Destructive Action (Ghost)

Used in lists and non-critical contexts

btn-ghost-destructive

Success Action (Confirm)

Only when this is the primary action

btn-ghost-success-confirm

Warning Action (Ghost)

Used in lists and non-critical contexts

btn-ghost-warning

WCAG 2.1 Standards

Level AA Requirements & Design Decisions

Our design system prioritizes readability and aesthetic balance over strict WCAG compliance, with the following considerations:

What Passes WCAG AA

Light Mode:

  • ✅ Text Secondary and above - All pass AA (4.5:1+)
  • ✅ Headings (h1-h4) - Pure extremes provide AAA contrast
  • ✅ Interactive elements - Buttons, active navigation use heading-level contrast
  • ✅ Accent colors - Most semantic colors pass on background

Dark Mode:

  • ✅ Headings (h1-h4) - Pure extremes provide AAA contrast
  • ✅ Interactive elements - Buttons, active navigation use heading-level contrast
  • ✅ Most accent colors - Better contrast on dark backgrounds than light mode

Intentional Aesthetic Choices

Dark Mode Body Text (Fails WCAG AA):

  • Body text: 3.73:1 (needs 4.5:1) - Prioritizes subtle, comfortable reading aesthetic
  • Secondary text: 2.34:1 - Supporting information, readable but de-emphasized
  • Tertiary text: 1.62:1 - Metadata, captions
  • Disabled text: 1.16:1 - Intentionally low contrast for inactive states

Why this works for us:

  • This is a personal design system for a single developer’s projects, not critical public infrastructure
  • Headings and interactive elements always pass AAA for clear hierarchy and navigation
  • Body text remains comfortably readable on modern high-resolution displays
  • Dark mode aesthetic prioritizes reduced eye strain over maximum contrast
  • Light mode provides higher contrast for users who prefer it

Trade-offs acknowledged:

  • Different color systems and themes have different strengths - light mode passes text contrast, dark mode passes more accent colors
  • No single theme satisfies all WCAG requirements across all token combinations
  • For critical documentation or public-facing applications, stricter compliance would be necessary

Core Accessibility Commitments

  • Use of Color: Information is not conveyed by color alone
  • Focus Visible: Keyboard focus indicators are clearly visible
  • Keyboard Navigation: All interactive elements are keyboard accessible
  • Semantic HTML: Proper heading hierarchy and ARIA labels throughout

Testing Methodology

  1. Automated Testing: Color contrast ratios are calculated using WCAG formulas
  2. Manual Testing: Keyboard navigation and screen reader compatibility
  3. Real-World Usage: Testing with actual assistive technologies
  4. Continuous Monitoring: Automated checks in our build process

Accessibility Guidelines

For Designers

  1. Use Semantic Colors: Stick to our design system tokens that ensure proper contrast
  2. Test Color Combinations: Use the Color Contrast Tester above
  3. Provide Alt Text: All images must have descriptive alternative text
  4. Design for Keyboard: Ensure all interactions work without a mouse

For Developers

  1. Use Semantic HTML: Proper heading hierarchy, landmarks, and form labels
  2. ARIA When Needed: Add ARIA labels only when semantic HTML isn’t sufficient
  3. Keyboard Support: All interactive elements must support Tab, Enter, and Escape
  4. Focus Management: Visible focus indicators and logical focus order

Tools & Resources

Testing Tools

External Resources