Accessibility in your project

Every release publishes accessibility.notes and accessibility.knownLimitations. A component cannot make your page accessible on its own, though. Once you place it, several things depend on how you use it.

What components document #

• Notes describe how the component is meant to be used accessibly, for example which prop provides an accessible name or which heading level it renders.
• Known limitations state problems that have not been solved yet. Read them before adopting a component.

Check the component in your page #

Content #

• Provide meaningful alternative text for informative images, and empty alternative text for decorative ones.
• Write link and button text that makes sense out of context. Avoid several links that all say "Learn more".
• Keep the heading order of the page logical. Check the level a component renders against the headings around it.
• Replace preview fixture content. Placeholder text is not written for your users.

Colour and appearance #

• Re-check text and control contrast after changing palette tokens or variants, in every appearance mode you enable.
• Do not rely on colour alone to convey meaning that you add.

Behaviour #

• Connect forms to real handlers and show real validation and error messages. A form without a working submission path is a barrier, not just a bug.
• Check that the component works with a keyboard in your layout, including with your header, dialogs and skip links.
• Respect reduced-motion preferences if you add animation.
• If a component requires client-side JavaScript, check what happens before it loads and when it fails.

Testing #

Test the assembled page, not only the component: keyboard navigation, zoom to 200%, a narrow viewport and at least one screen reader. Automated checkers find some issues but not all of them.

If you find an accessibility problem in a component itself, please report it with the component id, version and variant.