I am currently regretting the posts I didn't make. Yes, as someone who bangs on and on about posting things on your blog first and then elsewhere, I too fail many times. And, it's been like that when it comes to Jessie.

Since we adopted Jessie in 2017, I've been celebrating her adoption aniversary on social media instead of this blog. And it bit me in the arse. I used to have a lovely thread going on for years on Twitter but, of course, I haven't touched that hell space in a very long time. I was lazy and now I am paying the price. For this year's anniversary I still posted on BlueSky and Mastodon but, I want to make sure that memory is captured here too.

Sweet Jessie has been with us for eight years now and, fun fact, she is about to turn 14! She was five years old when we adopted her. It's been a priviledge that the majority of her life has now been with us.

Since living with us she has:

• lived in three different homes;
• brought a mouse in only once (and it was a baby so it doesn't count);
• went missing once (the worst);
• has had dentist appointments and teeth removed;
• became a big sister to an human;

I really hope I have many more years of posts to make. 💗

We can build UI components with accessibility in mind. We can also document accessibility specifics alongside them, or review them for obvious barriers during development. All helpful and recommended. What about claiming conformance? In this post, I'll talk about how WCAG technically doesn't allow for that, and why I believe WCAG is right.

This post is partially based on a series of talks I've been doing called “Built-in accessibility: blessing or curse?”, that also goes into “accessible web platform features” and authoring tools. A video from JS Heroes 2025 on YouTube is available .

As usual, opinions are my own, they do not represent those of my employer or Working Groups I am in.

Why components can't conform

In WCAG 2, components (like the React/Angular/vanilla/HTML components in your design system) cannot formally conform to WCAG, because one of WCAG's conformance requirements says:

conformance is for full web page(s) only, and cannot be achieved if part of a web page is excluded.

Of course, you could put an isolated component on an HTML page, or in some kind of Codepen or Storybook situation, but I don't think that makes a difference (even if you now technically created a ‘full web page’). We want to know if people can access a thing, and people (end users) access end products, specifically full pages and processes (eg they want to buy a thing, or submit a review).

The requirement was written before 2008, the year WCAG 2.0 was published. At that time front-end components weren't a thing, not as installable packages, but also not really as copy-pasteable snippets (it seems Natalie Downe pioneered this as a practice at Clearleft in 2009).

The requirement could be reconsidered. Design systems have matured a lot in the last decade. Multi-brand, multi-framework and automatically tested components are the norm now. Maybe I'm biased as an accessibility specialist, but I've seen a lot of teams name accessibility as a or the major driver to develop their design systems. And I've seen many be super effective in creating more accessible end products, because of how they're able to get best practices in the hands of many and their role in centralising useful documentation.

We should definitely test how accessible components are and document what they can and can't contribute to a website's accessibility. And WCAG requirements can help with this. However, I think claiming WCAG conformance about pages or sets of pages, as we do today, approaches it at the right level. I don't think we should want to claim conformity of components by themselves (we can of course review them, optimise them, document them, have accessibility specialists evaluate them). We shouldn't want to claim conformance specifically, because of two risks: overpromise and not capturing actual accessibility.

Risk of overpromise

Allowing for conformance claims on components makes it too easy for “component sales people” to make promises that they can't keep.

I don't mean “component sales people” derogatorily. I used to be one, mind. By this word, I mean specifically people involved in:

• promoting the design system with people who can use the components in their product (or buy them commercially)
• promoting the design system and its merits with decision makers and budget holders

The concept of a component that is WCAG-conformant sounds really good, I think. As a developer, I would npm install it straight away. As a budget holder, I would allocate vast sums of money towards it. Even as an accessibility person, I would like for it to exist, but I'm pretty convinced… there's no “it”. It isn't something that's actually feasible or meaningful (see below).

There's a real risk in overpromising the value of a component if we say it is accessible or conforms to some accessible standard. It could make people believe that they no longer need to worry about accessibility once they use or buy the component. That creates the wrong expectations: accessibility is a continuous process. Like we want to always iterate on user experience, we want to always iterate on accessibility.

Risk of not capturing actual accessibility

Claiming a component is conformant would not be as meaningful as it may seem. It would likely fail to capture actual accessibility of users, for many reasons. Below, I'll go into three: customisability, combinability and context.

Customisability

Most modern components have options, tools like Storybook exist for web developers to list, demo and test component options.

Many such options can easily have an impact on WCAG conformance at the point of usage, meaning we can only establish whether the usage meets WCAG in the final product. Conformance can't be decided in the “demo” component.

For example:

• if we can change colours in a component, we need to know what the colours are to decide if the end product meets WCAG (1.4.3, 1.4.11)
• if we can change buttton text in a component, we need to know what the text is in the end product to decide if the end product is accessible (eg no to “click here”, yes to descriptive text) or meets WCAG (eg 2.5.3)
• if we can pass alternative text to an image component, we need to know if the passed in text describes whatever the image is… we'd need to look at both the image and the text, to decide if the end product meets WCAG (1.1.1)
• if spacing is customisable, we need to know what the number is in the end product to decide whether it meets WCAG (2.5.8)

Combinability

Sometimes, we need to combine components in the right way in order to create something that is accessible or meets WCAG.

For instance, many design systems have separate label components and input components. To create an input situation that meets WCAG (1.3.1, 4.1.2), the person creating the end products may have to combine two components. And at that point, the “conformance” wouldn't really be in that one component, it would be in the effective combination of multiple (Many systems offer helpers or use one component to make this easier, but that's not my point).

Context

Lastly, context matters too. In the isolation of a test suite, there is only so much we can see. Looking at accessibility in lab conditions is undeniably useful, but for actual accessibility, we need at context: what people would actually be using.

My skip link component isn't meaningfully accessible if it is used in a page that doesn't contain the ID that it is set up to skip to. Or if there are no blocks of content that are repeated. Surely, it could contribute to meeting 2.4.1 Bypass Blocks , but only in the context of a page where it lets a user actually bypass actual blocks.

The focus indicator on my calendar component isn't meaningfully accessible if the picker sits inside a element that cuts it off halfway. It can contribute to meeting 2.4.7 Focus Visible, but only in the context of a page that doesn't then break it.

Accessibility that can be built in

There are some aspects of accessibility that mostly “survive” customisability, combinability and context.

This is what you should definitely try to build into your components, where possible:

• keyboard accessibility, eg how to move between dates in a datepicker, or how to select an option from a list, or what is the order of elements.
  Note: this can still be broken by page level keyboard interjections (like any use of positive tabindex, or via script).
• semantics (specifically roles) that don't depend, eg a button component that uses the button element.
  Note: a lot of semantics do depend, eg for popovers there are many suitable roles.
• states and relationships, eg the aria-expanded state in something that can expand.
• sensible reading order.
• zoom and reflow support.
  Note: this can still break with content and context.
• user preference support, eg dark/forced color mode, text spacing.
• support for accessibility features, eg caption and audio description support in a video player component.

There are many other ways to make components robust. I definitely see a lot of value in doing that. Over the last few years I've seen a number of examples where serious investement in accessibility at the design system level yields fewer and less severe issues in end products.

Another major benefit of working with components in a design system: there is a lot of opportunity to show the way. Document how to use the component well, what was tested, what needs to be tested in the end product, et cetera. Help well-meaning developers get it right (we can do a different post on what to do with ill-meaning developers).

Specs that components can meet

Added 13 August, based on Peter's thoughtful comment

While I say components can't meet the WCAG specification, they can absolutely meet other specifications. I don't think it makes sense to claim a button meets WCAG, but it does make sense to me to say a button meets a button-specific spec.

For any component you could make a list of things of requirements to make that component accessible (or good). A component could meet all of those requirements. This is not a fantasy.

The NL Design System project (disclaimer: I used to work there) incubates components from a community of government design system makers. As part of the incubation process, they makes lists of requirements for each component, see for instance their list of requirements for Skip Link (Dutch, should work with a translate service of your choice).

The US Web Design System has checklists too, like their Button checklist. They explain what things were tested when the component was made, and what you should be test for each component upon implementation.

Wrapping up

Officially, we can't claim accessibiliity conformance on components. But I'd also argue about wanting to make such claims, as we risk overpromising. Yet, there is lots of value in optimising components. There's lots of value in attempting to build in what can reasonably be built in. And to provide documentations that explains how you've gone about building and testing. As long as we never forget who interacts with what (and how). The goal should be that people can use the end product.

---

Originally posted as Can components conform to WCAG? on Hidde's blog.

Reply via email

Highlights

• I find that not every reader who purchases early access to my book wants to give me feedback about rough drafts.
• I figure out where all my time is going and think of ways to minimize time drains.
• I spend 10 hours reimplementing a web app from scratch that originally took me 300 hours to build.
• I continue to learn functional programming with Gleam, but I might be cheating.

Goal grades

At the start of each month, I declare what I’d like to accomplish. Here’s how I did against those goals:

Anyone who has worked closely with me, or followed on social media [, ], will have seen a post or comment to the effect of:

Names and dates on docs. Every time. Don't forget.

This is most often tacked onto design documents lacking inline attribution, and is phrased provocatively to make it sticky.

Why do I care enough about this to be prescriptive — bordering on pushy — when colleagues accuse me of being Socratic to a fault about everything else? Because not only is unattributed writing a reliable time-waster, the careers of authors hang in the balance.

Having to work to find the best person to discuss a topic with is annoying, but in large organisations, the probability of authors having work appropriated without credit goes up when they fail to claim ownership of their writing. It should go without saying that this is toxic, and that functional engineering cultures look harshly on it. But to ward off bad behaviour, it helps to model what's healthy.

The best reminder to cite work is for authors to name themselves. Doing this increases their stature, unsubtly encourages others to link and cite, and leaves a trail of evidence for authors to reference when building a case for promotion.

The importance of evidence to support claims of design work in technical fields cannot be overstated. Having served on hiring and promotion committees for many years, I can unequivocally say that this collateral is often pivotal. The difference between "[x] promote" and "[x] do not promote" often comes down to the names on documents. Reviewers will pay attention to both the authors list and the propensity of design doc authors to cite others.¹

Weighing Up Inline Attribution

In response to unsubtle nudges, several recurring arguments are offered against explicit authorship notices.

"These blocks detract from readability."

This is fair, but does not outweigh the needs of future readers who may be working to trace a chain of events or ideas. Nor does it outweigh the needs of authors for credit regarding their work at a future date.

"There's already an edit log."

This crutch fails in any number of ways:

• PDFs and printed copies do not include authorship data that is not in body text.
• Some systems (e.g. Google Docs) do not make the history available to non-editors.
• Documents may be copied or re-published in ways that disconnect the content from the original revision tracking system; e.g., in a systems transition as part of an acquisition.

Moreover, design is a complex and collaborative process. Ideas and concepts captured in documents are not always the contribution of the person writing down the conclusions of a whiteboarding session. A clear, consistent way to give credit helps everyone feel included and encourages future collaboration.

"Our team is small.

This is usually offered as a claim of superfluousness. If everyone knows everything and everyone working in a system, why does attribution matter?

Perhaps a team is small now, but will it always be? I am not in a position to tell, and my interlocutors also lack crystal balls. Given the downside risks, attribution is a pittance of an insurance premium.

"Specifying an author elides the contributions of collaborators."

This is easily countered with invitations in comments and drafts for contributors to add themselves to the authorship section. Generous and collaborative folks — the sorts of people we want to promote — reliably add their collaborators to documents proactively and set the expectation that others will do the same. Over time, practice becomes habit, which crystallises into culture.

Minimum Viable Attribution

A final concern I hear is that these blocks require a great deal of upkeep. Long-form revision logs might be onerous, but the minimum viable attribution style only needs three elements: names, emails, and dates. These should be provided on the very first page, ideally just below the title.

The primary date always refers first drafting, even if that is before publication. If deemed necessary, authors can optionally add a "Last Updated" field below the primary date, but this is optional. Documents authored in a single sitting by a lone author should avoid extra visual noise.

Revision logs are generally unnecessary, and my personal view is that they distract from content; if they're a requirement (e.g., in a heavily regulated industry), record them in an Appendix, but do not remove minimum viable attributions.

Here's a screenshot of an explainer I helped draft many years ago showing the basic form²:

If a document is still an early draft, it can be helpful to put some indication in the title — I use a prefix like "[ Draft ] ..." — and invite collaborators to add themselves to the authors list by including an entry there of the form "Your Name <your_email@example.com>". Once a document is circulated widely, remove these inline markers.

FOOTNOTES

1. If you write technical design docs, it is always a good sign if you cite prior work and parallel efforts, including competing designs. Omitting those references is something that both technical and promotion reviewers are alert to and are primed to think poorly of. No design is entirely new, and it is a sign of maturity to give others their due. ⇐

2. Don't worry, all of these email addresses are now inactive.

   On the question of emails and spam in authoring public documents, views are split. I favour always using them, but understand if authors prefer other sorts of contact information; e.g., their personal website. Best not to be too fussy about this sort of thing, except to ensure that internal documents always contain email addresses. ⇐

Eric wrote about his newsletter subscriptions, and asked some friends to do the same. Here’s my entry.