UI Libraries do not make your application accessible

Published: August 31, 2026. Updated September 4, 2026. 7 minute read

Web UI libraries are extremely helpful when built right. They can consolidate many decisions, support teams of any size, ensure consistency, and account for accessible interactions. Although, adoption alone does not guarantee a site or application will become fully accessible or usable.

Note, I may use the terms ‘accessibility’ and ‘usability’ interchangeably, but they have important distinctions: in order for a task to be achievable with a wide variety of user agents and human abilities, then it must be made accessible; and in order for a workflow to be highly efficient and with minimal motor or cognitive strain, then it must be made usable. It’s sometimes trickier to make a digital experience usable after it has been made accessible, but with “inclusive design” we can make an experience usable first in order to make it accessible more easily.

With that in mind, here are a few examples of usability flaws in a UI library that may carry into an application:

• A styled UI library provides a theme that is either only high contrast, or only low contrast.
• Some provided interactive elements do not present focus rings.
• A button group of 2 modes presents the ‘active’ toggle as an inverted colour, making it unclear which button is active and which is inactive.
• An accordion with its ‘expanded’ indicator is too far away from the start position of its container, making it practically invisible to a user with a screen magnifier.
• Top-level navigation links that use colour alone to represent the ‘current’ page.

A keen observer or experienced practitioner may avoid the above flaws in their own projects, but they may still carry over depending on who is making the adoption decision evaluated against their own abilities; at which point it may be too late to undo the decision, or it may be a challenge to report the issue and have it prioritized by the library maintainer either due to competing priorities or education gaps in acknowledging the priority.

Though even in the best circumstances, such as when a thoughtfully designed and thoroughly tested library becomes adopted, there is still the possibility of components being composed without proper care by the adopter. Some examples are:

• An accessible combobox is presented for the user to select options for a form submission, but selecting an item navigates to another page entirely, and without prior notice.
• A group of three accessible accordions is used to contain three complex applications that present nested interactions and heavy payloads.
• A link provides distinct styles and an appropriate aria-current value, but goes unused within a top-level navigation landmark.

Some of these micro interactions are complex, for sure; but proper guidelines must be put forth to increase the chances of having the adopter make the right decisions. Not all adopters can be trained, or be afforded enough time; although the UI library cannot bear all responsibility at the same time.

Accessibility claims

Plenty of paid and free UI libraries exist, and some of them claim some level of accessibility. From my observations, they provide claims that span a few levels of confidence:

1. No mention of accessibility.
2. A one-liner mentioning their components are accessible, but nothing more.
3. A document dedicated to accessibility, and a short list of considerations made.
4. A comprehensive overview of accessibility features accounted for, maybe some documented tests, guidelines on every component page, and potentially a disclaimer of not being fully accessible.

There’s also the paradox of believing “headless” UI libraries “solve the accessible parts”. By definition, a headless UI library only provides utility logic so that consumers may compose their own set of components. To review, there are 4 principles from the Web Contents Accessibility Guidelines (WCAG), listed here for convenience:

• Perceivable
• Operable
• Understandable
• Robust

Some headless libraries that claim any amount of accessibility do so from the basis of following patterns from the ARIA Authoring Practices Guide (APG), a guide that provides a set of disclaimers in its APG Introduction. Their introduction includes some important points, such as:

While the APG includes a library of patterns and functional examples, [its] objectives do not include providing a comprehensive design system or production-ready code. Not only would developing a production-ready design system be beyond the capacity of the Authoring Practices Task Force, developing examples that satisfy requirements of a unified design system would inhibit its primary aim of building broad understanding of relevant practices.

For educational purposes, it’s a useful resource. As a development resource, it is not, nor does it claim to be, a quality checklist for components. It cannot be relied upon as an up-to-date, fully tested, and comprehensive set of guidelines to building some components for a UI library. APG can be considered as one of several quality checks, but it should not be the only reference.

Let’s try applying headless UI libraries to the 4 WCAG principles:

• Perceivable; unaccounted for. Consumers provide styles, ensure proper colour contrast, focus styles, interactive affordances, labels, and more.
• Operable; at worst, unaccounted for. At best, accounts for keyboard and assistive technology users specifically when it comes to interactive components; which may or may not have documented tests or a wide coverage of tests.
• Understandable; at worst, unaccounted for. At best, provide customizations for multi-lingual copy where applicable wherever single-language copy is provided. Either way, the consumer must provide content and test surrounding workflows.
• Robust; at worst, unaccounted for. At best, provide appropriate attributes for name, role, value that can be represented under a variety of conditions. Either way, the consumer must apply these attributes to applicable elements and test to ensure all states reflect across a variety of user agents.

Given the amount of leftover responsibility for the library adopter, it’s clear that a UI library, accessible or not, cannot make the adopter’s application accessible purely from adoption. Especially when adopting a headless library, where all the perceivable and understandable parts are not provided, the adopting application does not have accessibility handled by the library alone.

Does that mean it’s not worth trying to build or adopt a UI library? Of course not, and I say this as someone who had built a few design systems. Being able to provide components to team members that you can confidently say had put in all reasonable efforts to provide accessible interactions within the constraints of their boundaries is always worth it; because adoption of such patterns can scale up nicely. As well, when accessibility flaws are identified and triaged as priority-zero bugs to be patched and shipped, all consumers and end users can receive those improvements swiftly and at scale.

The right approach for UI libraries

Always start with a disclaimer. If I could be a bit meta, I disclaim my words in this blog post as a comprehensive guide to building accessible UI libraries. With similar intent, I believe it’s important for UI libraries to disclaim that adopting their components will make any consuming web service suddenly become accessible; there is so much for the library consumer to consider, and it should be made frequently clear to the consumer what to account for.

With that said, here’s a brief checklist of considerations I believe every UI library should include:

1. Documentation front pages include a passage or link to a document that provides an accessibility pledge. This pledge disclaims any level of adoption of the UI library would lead to an accessible application. It references WCAG, and any relevant accessibility legislature the UI library is intended to serve and/or comply with. View Developing an Accessibility Statement by the Web Accessibility Initiative for more guidance.
2. It’s possible for relevant users to easily submit feedback or issues; and if such issues relate to accessibility, then they are treated as critical bugs. Ideally, similar priority can be made for usability.
3. Individual component documentation includes: eligibility criteria, when to use it, when not to use it, what to use instead in some common situations; comprehensive tests for assistive technologies across multiple systems; and convenient links or summaries of known issues.

One good example I found is the U.S. Web Design System Combo box component documentation, which tidily includes screen reader tests that reference their respective WCAG Success Criterion.

Build to serve

Be cautious when adopting UI libraries. There may be cases where necessary attributes may be missing, contrast is insufficient, or there’s too much travel between context and its first meaningful interaction. Some components may need to be vendored or forked, but it’s nice to put in the time to constructively open tickets to report any gaps and see how they may be addressed; because the fix will compound its effects across all adopters.

When building UI libraries, especially for business outcomes or in service to unknown users, accessibility must be a pillar of focus. When choosing to adopt a UI library, headless or otherwise, it’s imperative to evaluate each individual component you intend to use and test them. Adoption of a UI library, no matter their accessibility claims, does not guarantee the adopting application will become accessible.

If a UI library does not properly test their components, or they make incomplete claims about accessibility, then they are distributing barriers at scale.