Finalsite + AudioEye: Fix a color contrast flag

Misty Flowers

April 28, 2026 22:43

A step-by-step walkthrough for editors, from finding the flagged element on your page to confirming the fix. Part of the AudioEye how-to series.

💡Quick answers

What does AudioEye mean when it flags a color contrast issue? Text, a button, icon, or form field does not have enough contrast against its background to meet WCAG 2.1 Level AA.
What contrast ratio do I need to pass? 4.5:1 for normal body text; 3:1 for large text (18pt or larger, or 14pt bold or larger); 3:1 for UI components like buttons, form borders, and focus outlines.
How do I find which element has the contrast problem? Open the flagged page and add /?oss=1 to the URL. The AudioEye Accessibility Page Scanner highlights the exact element and shows the current ratio.
How do I fix a color contrast issue in Finalsite? Check the current ratio in a contrast checker, pick a compliant color from your brand palette, and update the color in Composer or your site theme settings.
How do I confirm the fix worked? Reload with /?oss=1 to confirm the flag is gone on the live page. The AudioEye report runs on a rolling 7-day window, so it takes about a week to drop off the main report.

Why color contrast matters

Color contrast is one of the most common accessibility issues on websites, and one of the most invisible to the person who created the page. If you have typical vision and are working on a full-brightness monitor in a normal indoor room, text that passes or fails contrast can look more or less the same to you.

The people it affects include: readers with low vision, readers with color vision differences, anyone reading on a phone in direct sunlight, and older readers whose contrast sensitivity has decreased with age. For all of them, text with low contrast is the difference between "I can read this" and "I am giving up."

What AudioEye shows you

On your AudioEye report, color contrast issues show up with a message like "Element has insufficient color contrast." The report tells you the page URL and the element type, but not always exactly where on the page that element sits. That is what the on-page scanner is for.

Step 1: Find exactly where on the page the issue is

Open the page your AudioEye report flagged, then add /?oss=1 to the end of the URL (use &oss=1 if the URL already has other parameters). Press Enter and wait about a second; the AudioEye Accessibility Page Scanner panel appears on the page.

The scanner highlights the specific element with insufficient contrast and shows you:

The WCAG 2.1 success criterion involved (typically 1.4.3 Contrast Minimum or 1.4.11 Non-text Contrast)
The current contrast ratio
The foreground and background colors it detected
A plain-language description and help text

Pro tip

Scroll the page if the highlighted element is not visible in the scanner panel. The scanner covers the whole page, including elements below the fold.

Step 2: Confirm the current contrast ratio

The scanner's reported ratio is usually enough, but if you want to double-check, or if you want to experiment with alternate colors before you commit, paste the foreground and background hex codes into a contrast checker.

Recommended tools

WebAIM Contrast Checker: industry standard; also suggests compliant color adjustments via a lightness slider.
AudioEye Color Contrast Checker: enter two hex codes, get an instant WCAG AA/AAA pass or fail.
TPGi Colour Contrast Analyser: free desktop app with an eyedropper to sample colors directly from your screen, useful when you do not have a hex code.
Tanaguru Contrast-Finder: suggests the closest valid color to your original that will pass.

Note on third-party tools

While this is a curated list of industry-standard resources, Finalsite does not officially endorse these specific third-party tools. We recommend choosing the tool that best fits your workflow and consulting with your legal or compliance team to determine which they suggest for your organization's specific requirements.

Contrast targets to pass WCAG 2.1 Level AA

Normal body text: 4.5:1
Large text (18pt or larger, or 14pt bold or larger): 3:1
UI components (buttons, form borders, focus outlines, icons that convey meaning): 3:1

Non-text contrast: Buttons and form field borders

AudioEye surfaces two distinct types of contrast flags. The more common is text contrast (WCAG 1.4.3), which checks whether text is readable against its background. The second is non-text contrast (WCAG 1.4.11), which checks the visible boundaries of interactive UI components: buttons, form input fields, checkboxes, radio buttons, and focus indicators, measured against the colors immediately adjacent to them.

When AudioEye flags "Non-text contrast-ratio on visual boundaries is too low," the issue is the element's border or edge, not the text inside it. A form input field that blends into a white page background, a button whose border color is too close to the page color, or a checkbox that disappears against a light gray section all fail this check.

The required ratio is 3:1, the same as large text contrast, but measured between the element's boundary color and the immediately adjacent background color.

Where this usually shows up in Finalsite

The most common sources are form input fields in forms, buttons created in Content elements, and focus outlines. These are typically controlled through your site theme rather than individual Content elements. If you are not sure where your button or input border colors are set, email accessibility@finalsite.com with the page URL and the flagged element type. Theme-level color changes affect the whole site and should be coordinated.

The fix process is the same as for text contrast: use /?oss=1 to locate the flagged element, then check the contrast ratio between the element's border color and the adjacent background color. Adjust the border or background color until it meets 3:1, then update the value in your theme or element settings.

Step 3: Choose a compliant color

Open your selected contrast checker, drop in your current foreground and background colors, and nudge one of them until the ratio passes. A few practical tips:

Start by darkening the text or lightening the background, not both, so the change stays close to your brand.
If your brand palette includes a darker or lighter variant of the same hue, use that first.
Avoid fixing contrast by adding bold everywhere. Bolding changes the target from 4.5:1 to 3:1 only at 14pt and larger; it does not help at smaller sizes.
For icons and buttons, the 3:1 rule applies to the element's edges or meaningful shape, not just any text inside it.
If your brand palette does not include a compliant variant, it is worth a conversation with whoever owns your brand guide. Accessible contrast is a design constraint, not a styling preference.

Step 4: Apply the new color in Composer

Where you change the color depends on where the element lives:

Text inside a Content element: select the text, open the color picker in the Content toolbar, and apply the new hex code.
Buttons or call-to-action elements: edit the element's style settings. Most Finalsite button components expose color controls in your site's Style Guide.
Site-wide colors (headers, navigation, footer, default link color): these live in your site's theme and CSS. Changing them there updates every page at once. Before making any changes, review the Composer Themes overview. If you are not sure, email accessibility@finalsite.com before making site-wide changes.

Content element background colors

The background color of a standard Content element is controlled by your site's global theme and CSS. It cannot be changed within the element settings or the editing toolbar. If the contrast issue involves the background of a Content element rather than the text color, the fix requires a theme-level change. Email accessibility@finalsite.com with the page URL and a description of the element.

Composer built-in accessibility checker

The Accessibility Checker built into the Content element helps flag many contrast issues while you are editing, before you publish. It is a useful second set of eyes, though it does not replace a full review.

Step 5: Verify the fix

Publish your change.
Reload the page with /?oss=1 on the end of the URL.
Confirm the scanner no longer flags the element. If it does, double-check the hex codes in the scanner's detail panel; you may be styling a nested element (like a link inside a paragraph) that inherits a different background than you expected.

About the 7-day report window

The AudioEye report runs on a rolling 7-day window. The live page scan confirms your fix immediately; the main report takes about a week to update.

Want to see this in action?

If you are learning the workflow or training a teammate, it is useful to work through a real report first:

Live scanner practice: pick any page on an AudioEye-enabled site and append /?oss=1. You can step through the flagged elements and their contrast ratios in real time, without changing anything.
Finalsite's own AudioEye report: browse the contrast flags in a live dashboard to see how they appear.

Still stuck?

If the scanner shows a contrast issue you cannot trace to a specific element, or if the element seems to inherit colors from somewhere you cannot edit directly, email accessibility@finalsite.com. Send the page URL and a quick note on what you have tried, and we will help trace it.