Skip to main content

Validate Palette Contrast

The Validate Palette Contrast ability checks colour pairs in your design palette for WCAG (Web Content Accessibility Guidelines) compliance before applying them to your theme.

Overview​

This ability ensures your site's color scheme meets accessibility standards by validating contrast ratios between text and background colors. It helps prevent color combinations that could be difficult for users with visual impairments to read.

Input Format​

The ability accepts a color palette as input:

{
  "colors": [
    {
      "name": "primary",
      "hex": "#678233"
    },
    {
      "name": "text",
      "hex": "#ffffff"
    },
    {
      "name": "background",
      "hex": "#f5f5f5"
    }
  ],
  "wcag_level": "AA"
}

Parameters​

ParameterTypeRequiredDescription
colorsarrayYesArray of color objects with name and hex properties
wcag_levelstringNoWCAG compliance level: "A", "AA" (default), or "AAA"
pairs_to_checkarrayNoSpecific color pairs to validate (e.g., ["primary-text", "background-text"])

WCAG Levels Checked​

The ability validates contrast ratios according to WCAG standards:

LevelNormal TextLarge TextMinimum Ratio
A3:13:13:1
AA4.5:13:14.5:1
AAA7:14.5:17:1
  • Normal Text — text smaller than 18pt (or 14pt bold)
  • Large Text — text 18pt or larger (or 14pt bold or larger)

Output Schema​

The ability returns a detailed validation report:

{
  "compliant": true,
  "wcag_level": "AA",
  "pairs": [
    {
      "pair": "primary-text",
      "color1": "#678233",
      "color2": "#ffffff",
      "contrast_ratio": 5.2,
      "wcag_a": true,
      "wcag_aa": true,
      "wcag_aaa": false,
      "status": "pass"
    },
    {
      "pair": "background-text",
      "color1": "#f5f5f5",
      "color2": "#333333",
      "contrast_ratio": 12.1,
      "wcag_a": true,
      "wcag_aa": true,
      "wcag_aaa": true,
      "status": "pass"
    }
  ],
  "summary": {
    "total_pairs": 2,
    "passing": 2,
    "failing": 0,
    "recommendations": []
  }
}

Output Fields​

FieldTypeDescription
compliantbooleanWhether the entire palette meets the specified WCAG level
wcag_levelstringThe WCAG level that was checked
pairsarrayDetailed results for each color pair
contrast_rationumberThe calculated contrast ratio (1:1 to 21:1)
statusstring"pass" or "fail" for each pair
recommendationsarraySuggestions for improving failing pairs

Usage Example​

Prompt:

Check if my color palette meets WCAG AA standards. I have primary color #678233, text color #ffffff, and background #f5f5f5.

Result: The ability validates all color combinations and returns:

  • ✅ Primary + Text: 5.2:1 ratio (passes WCAG AA)
  • ✅ Background + Text: 12.1:1 ratio (passes WCAG AAA)
  • Overall: Compliant with WCAG AA

Integration with Theme Builder​

When using Theme Builder's design-direction selection, the Validate Palette Contrast ability:

  1. Analyzes your selected color palette
  2. Checks all text-background combinations
  3. Validates against your chosen WCAG level
  4. Provides recommendations for non-compliant pairs
  5. Prevents applying inaccessible color schemes

Best Practices​

  • Start with AA level — WCAG AA is the standard for most websites
  • Test before applying — validate your palette before committing to a design
  • Check all combinations — ensure text, links, and UI elements all meet standards
  • Consider user preferences — some users may have additional color sensitivity
  • Use contrast checkers — combine this ability with browser tools for verification

Failing Pairs and Recommendations​

If a color pair fails validation, the ability provides recommendations:

{
  "pair": "primary-text",
  "status": "fail",
  "contrast_ratio": 2.8,
  "wcag_aa": false,
  "recommendations": [
    "Lighten the text color to #ffffff (ratio would be 5.2:1)",
    "Darken the background color to #556b2f (ratio would be 4.8:1)",
    "Use a different primary color like #4a6b1f (ratio would be 6.1:1)"
  ]
}