Writing Accessibility Docs for Your Components
Accessibility docs are the user manual for your component's a11y features. They guide consumers on correct usage, like required ARIA attributes or keyboard behavior.
Why it exists
Code alone can't guarantee an accessible user experience. A component might be built with perfect ARIA attributes and keyboard logic, but if the developer using it doesn't provide the right props, like an accessible name for a button, it's still inaccessible. Accessibility documentation bridges this gap between the component author and the component consumer.
The mental model
Think of accessibility documentation as the API documentation for assistive technology users. Your standard props documentation describes the component's API for developers. Your accessibility documentation describes the component's 'API' for screen readers and keyboard-only users, and what the consuming developer must do to preserve it. It defines the contract: 'If you provide these things (e.g., a label), the component guarantees this experience (e.g., a screen reader will announce it correctly).'
How it works
Effective accessibility documentation for a component typically includes several key pieces of information. First, it specifies the keyboard interaction model, detailing every key and what it does (e.g., 'Arrow keys navigate options, Enter selects, Escape closes'). Second, it lists the necessary ARIA roles, states, and properties the component manages, like role="dialog", aria-modal="true", or aria-expanded. Finally, and most importantly, it clarifies the consumer's responsibility, explicitly stating which props are required to provide an accessible name or context, such as needing to pass an aria-label to an icon-only button.
When to use it
This practice is essential whenever you create a component that will be used by other developers, which is the core premise of a design system or shared component library. It's also vital during handoffs between design, engineering, and QA to create a shared understanding of the expected accessible behavior. Documenting a11y up front prevents bugs and ensures consistency.
When not to use it
You would not create this level of documentation for a one-off component used in a single, isolated place with no intention of reuse. In that context, the accessibility requirements are localized to that specific implementation. The formal documentation is for reusable, system-level components.
One canonical example
The W3C's ARIA Authoring Practices Guide (APG) is the gold standard. For its 'Dialog (Modal)' pattern, it doesn't just show code. It explicitly documents keyboard interactions (Tab/Shift+Tab are trapped inside, Escape closes it), required ARIA roles (dialog), and properties (aria-labelledby, aria-modal). This tells any developer building or using a modal exactly what is required to meet user expectations for accessibility.
Interview question
According to the card, what is the primary role of accessibility documentation for a reusable UI component?
- a.To detail the component's internal ARIA structure, allowing developers to customize it.
- b.To guarantee the component is fully accessible out-of-the-box, reducing developer effort.
- c.To guide component consumers on how to provide necessary context and props to preserve accessibility.Correct
- d.To enable assistive technologies to directly interpret the component's intended behavior without relying on the DOM.
Why? this is the answer
The card emphasizes that accessibility documentation bridges the gap between component authors and consumers by clarifying the consumer's responsibility to provide necessary props and context. Option A describes a secondary benefit, but not the primary role of ensuring correct usage by consumers.
Just read this? Test yourself on what you have been reading.
Read the original → w3.org
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Open roles that interview on accessibility — each one lists the topics its interview covers.
See open roles