Accessibility: Color contrast

[StijnMaenhautCZ]

We have been using Radix UI Theme with a lot of pleasure. Creating a web application goes fast and efficient. Thanks for all the hard work!

The introductory text of Radix UI Theme states:

An open source component library optimized for fast development, easy maintenance, and accessibility.

We are however facing color contrast issues with some theme colors, following the AA accessibility standard. For example if we take the teal color, we are facing quite a lot of issues (see screenshots below for specific examples). The color contrast issues are resolved with the highContrast option, but the main colors should be sufficient so we only use highContrast in exceptional cases.

To resolve these issues there are two possible outcomes, I think:

• The theme sub colors are adjusted to meet contrast requirements (or the components are using the right sub colors) — preferred solution
• The developer has the possibility to interchange the sub colors of a given component to meet contrast requirements

Tools

To define the contrast value, we used the following tools:

• Chrome Dev Tools (hover an element while inspecting)
• Colour Contrast Analyser (CCA)

Text contrast

See https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html

Alert dialog button

Badge

Button

Non text contrast

See https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html

Text field

The contrast between the background color (white) and border color (gray) is insufficient.

[vladmoroz]

Hey, your assessment is based on the WCAG 2.0 standard, which is outdated and doesn’t predict accurately how human vision perceives text. First of all, I'd recommend to check for yourself and consider if you find the text there hard to see.

Radix Colors were designed with a modern APCA color algorithm as the guardrails, which predicts the perception better and is going to be used for the upcoming WCAG 3.0 standard.

There's a wealth of info about how APCA works and the issues with the WCAG 2.0 contrast ratios. Teals and oranges are one of the most common areas where it's clear that WCAG 2.0 is off:

Please refer to the APCA repo for more info:

https://github.com/Myndex/SAPC-APCA https://github.com/Myndex/SAPC-APCA/discussions/categories/documentation

Plenty of articles out in the wild too.

Contrast info for each color is available on the Radix Colors homepage: https://www.radix-ui.com/colors

---

The contrast between the background color (white) and border color (gray) is insufficient.

I would recommend to use placeholders and other visual cues for the text inputs, as darker borders would be a visual compromise for most modern apps. See this in the document you linked:

This success criterion does not require that controls have a visual boundary indicating the hit area, but if the visual indicator of the control is the only way to identify the control, then that indicator must have sufficient contrast. If text (or an icon) within a button or placeholder text inside a text input is visible and there is no visual indication of the hit area then the Success Criterion is passed.

---

The developer has the possibility to interchange the sub colors of a given component to meet contrast requirements

If for some reason you still need to please the WCAG 2.0 ratios or simply have higher contrast requirements for your app, you could either use highContrast option on many components, use an accent which is not problematic with the way WCAG works (like indigo), or overwrite the CSS variables used for the color scales that power every component.

[StijnMaenhautCZ]

Thanks for the swift reply!

I understand that you're already working towards APCA and WCAG 3.0, however this is an upcoming standard of which it is unknown when it will be released:

The First Public Working Draft of WCAG 3.0 was published on 21 January 2021. The July 2023 draft has many changes that resulted from public feedback. We plan to publish updated drafts every 3-6 months. WCAG 3 is not expected to be a completed W3C standard for a few more years. — Source: W3

I disagree with the fact that WCAG 2 is outdated, as it is under active use due to legislation.

European norm 301549 states that, simply put, websites and mobile applications have to comply with WCAG 2.1 level A and AA. As we are a digital agency located in Belgium and working for a Belgian client, we need to abide by the WCAG 2.1 (or even 2.2) rules. APCA is indeed more human readable and a step forward in accessibility. As WCAG 3.0 is upcoming, it would be great if all exposed theme colors would be WCAG 2 and APCA compatible. This is a solid foundation to build the interface upon.

Using highContrast for most of the components is, in my belief, not the best way forward. It should be only used when the contrast of components should have an even higher contrast than the one set by design, to accommodate for users with visual disabilities.

Specifically concerning the border color of an input, you stated that it is sufficient to have a placeholder or another visual cue for text inputs. However, the WCAG 2.1 document concerning non text contrast states that:

See Active User Interface Component Examples

[vladmoroz]

The overlap between "modern, good-looking design" and "satisfies WCAG 2 contrast" is extremely narrow due to the inherent issues in the way contrast is calculated in WCAG 2.

If you need strict WCAG 2 contrast ratios conformance, Radix Themes is not going to work out of the box for you, and it's not going to be on the roadmap because it's mutually exclusive with the direction that can keep the project alive.

It's an OSS project where you can see the implementation, so feel free to modify the color scales to suit your needs if you are set on using Radix Themes.

---

European norm 301549 states that, simply put, websites and mobile applications have to comply with WCAG 2.1 level A and AA

EN 301 549 applies only to the websites and apps in the public sector. We care about the real accessibility rather than conformance to the standards in itself, and we don't position Radix Themes as a project for use in the public sector. If we did, this would have been a completely different project that would make no sense for building modern web apps, which is our primary goal.

---

Specifically concerning the border color of an input, you stated that it is sufficient to have a placeholder or another visual cue for text inputs. However, the WCAG 2.1 document concerning non text contrast states that:

I quoted the same link you are referencing. Again, that document states that the criterion is required when the border of the control is the only way to identify the control. I suggested to have an extra visual cue like a placeholder as lower contrast border inputs with placeholder text as it's more idiomatic nowadays and frankly more helpful for the user too, as placeholder provides a better affordance than even a high-contrast border.

[Veyfeyken]

EN 301 549 applies only to the websites and apps in the public sector.

From 2025, certain services (including online banking and e-commerce) have to comply to EN 301 549 (and thus WCAG) as a result of the European Accessibility Act. It's no longer a public-sector-only-story.

I suggested to have an extra visual cue like a placeholder as lower contrast border inputs with placeholder text as it's more idiomatic nowadays and frankly more helpful for the user too, as placeholder provides a better affordance than even a high-contrast border.

A placeholder is not a substitute for a label outside the element. It disappears on focus and is usually hard to read. It's discouraged from a usability and accessibility perspective.

• The problem with placeholders and what to do instead - Adam Silver
• Placeholders in Form Fields Are Harmful - Nielsen Norman Group
• A placeholder is not a label - HTML Hell

Should "Modern and good-looking" outweigh research-based user experience best practices?

[vladmoroz]

A placeholder is not a substitute for a label outside the element. It disappears on focus and is usually hard to read. It's discouraged from a usability and accessibility perspective.

Yes, I am aware of that, and of course the label should be used as well. Did I ever suggest placeholder would replace the label?

I feel like you are trying to read between the lines, ignoring my reasoning and the solutions I suggested.

[Veyfeyken]

I'm not ignoring your reasoning, just pointing out why I don't follow it. Best practice is to leave input's empty, therefore placeholders are not a good solution to the low contrast problem.

I feel like you're looking for excuses to justify low contrast text or UI components instead improving it. From what I gather Radix does a lot to make accessibility easier, big cheer for that. We just disagree on this I guess.

[vladmoroz]

The community is welcome to create an outline variant for inputs with darker borders, or distribute a different set of CSS color variables that would plug into Radix Themes, which we'd gladly feature on the Radix website.

I'd like to point out that the inputs used throughout the very Nielsen Norman Group site itself feature a border that is a couple steps lighter than in Radix Themes—and by the looks of it, it would be fair to assume that few things on that website weren't subjected to their own research practices.

Altogether I don't follow how something that in practice isn't a showstopper neither for the operating systems like macOS, nor for the likes of NNG, is scrutinised to this level in a free OSS project where you received multiple suggested workarounds almost right away.

As for "low contrast text" claim, I am not interested in discussing the conformance of the teal example to WCAG 2 contrast ratios, because it's a flawed algorithm that doesn't reflect how human vision perceives text at this hue, and we provide the options to use other colors and to even override the defaults.