Overview

As part of the CI, we have added a test-contrast script that automates accessibility contrast checks for the Kendo UI components with the default-ocean-blue-a11y swatch. The script launches a local HTTP server, navigates through the test HTML pages, and analyzes them for color contrast issues according to WCAG guidelines.

Key Features

Contrast analysis

The contrast tests are performed using the AXE-Core tool, which checks for both WCAG 2.1 Level A and AA requirements, along with the stricter WCAG 2.1 Level AAA ones:

const axe = new AxeBuilder(browser.driver);
axe.withRules([ 'color-contrast' ]);
const output = await axe.analyze();
axe.withRules([ 'color-contrast-enhanced' ]);
const enhanced = await axe.analyze();

Focus Report

The script also uses custom logic for checking focus indicator contrast, which AXE-Core does not cover. It does so by:

• Iterates over all focused elements on a page by targeting elements with the .k-focus class
• Gets the focused indicator colors of each focused element- this may include the boxShadow, outlineColor, backgroundColor, or even computed styles of pseudo-elements (like :after), depending on the component type.
• Calculates the element background color and the parent background color, considering transparency, borders, and box-shadows
  • If the parent background is fully transparent, get the background of its parent element
  • If the parent background is semi-transparent, blend it with its parent background to get the actual solid background color
  • If the element background is semi-transparent, blend it with the parent background to get the actual solid element background color
  • If the element background is fully transparent, use the background color of the parent element instead
  • If the element has a border that is not transparent, use it for contrast calculation
  • If the element has an inset box-shadow, use the background color of the element for contrast calculation
  • If the outline offset is 0 and the box-shadow is inset, use the background color of the parent for contrast calculation
• Calculates contrast by computing the contrast ratio between the focus indicator color and both the element's background and its own color, using the same color math as for text contrast
• Threshold- checks that the contrast ratio is at least 3:1, as recommended for visible focus indicators
• Reports- any element failing this check is reported in the output under "Focus contrast WCAG violations"

Output

• Prints a summary of violations and focus contrast issues to the console
• Exits with code 1 if any violations are found

Important Notes

• Disabled elements are not required to meet focus contrast requirements
• Some elements and pages are excluded due to known issues or limitations in axe-core or the components themselves

Exclusions

To exclude an element or a whole HTML page from the contrast test, add it to the respective array:

• If an element has a failing focus indicator contrast ratio requirement and this is intended, add the element selector to EXCLUDED_ELEMENTS_FOCUS
• If a test page has a failing text contrast ratio requirement and this is intended, add the HTML page to EXCLUDED_PAGES_TEXT