--- title: "Accessibility" slug: ovhcloud-design-system-build-accessibility category: generic type: overview version: 20.0.0 tokens: 4541 source: https://ovh.github.io/design-system/v20.0.0/llms/ovhcloud-design-system-build-accessibility.txt --- # Accessibility ## Introduction This guide focuses on accessibility best practices specifically for developers integrating the **OVHcloud Design System**. While our components are built with accessibility in mind, using semantic HTML elements and including the necessary ARIA attributes by default. Nevertheless, ensuring full accessibility in your specific use case might require you to implement additional ARIA attributes, roles, and behaviors at the integration level. However, depending on the context, you might need to enhance a component's accessibility. This guide will help you understand: * When and how to use ARIA properly * Common mistakes and best practices * How screen readers interpret different ARIA attributes For broader accessibility information beyond the **OVHcloud Design System**, consult our [Accessibility Statement](https://www.ovhcloud.com/fr/accessibility/) available on our official website. ### Before using ARIA #### Consult the Accessibility section for each component Each component in **OVHcloud Design System** comes with a dedicated **"Accessibility"** section that provides best practices and usage guidance. #### Be careful when adding extra ARIA attributes as ODS components may already handle it To be as close as possible to the accessible experiences provided by modern browsers, **OVHcloud Design System** aims to rely on semantic and native HTML elements whenever they are inherently well-suited for screen reader experiences. In addition to the predefined accessibility features of our components, you can find more guidance regarding accessible integration in the **"Accessibility"** section. ## Essential ARIA attributes ### aria-label: Providing an accessible name Use [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) when an element needs a descriptive name but has no visible text. ```tsx ``` Screen readers will announce a button. ```tsx ``` Screen readers will announce a button and the aria-label. #### Related Sources * [MDN Documentation - aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) * [RGAA - 6.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#6.1) * [RGAA - 7.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.2) * [RGAA - 11.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.1) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) * [RGAA - 11.9](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.9) ### aria-labelledby: Referencing another element as a label Use [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) to associate an element with an existing label (instead of duplicating text). ```tsx <> Filter your search results ``` Screen readers will announce a button. ```tsx <> Filter your search results ``` When the **Button** is focused, the screen reader should announce the linked label. > Use [aria-label](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-label) when there is no visible label, and [aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) when there is one. #### Related Sources * [MDN Documentation - aria-labelledby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-labelledby) * [RGAA - 6.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#6.1) * [RGAA - 7.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.2) * [RGAA - 11.1](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.1) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) * [RGAA - 11.9](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.9) ### aria-describedby: Providing additional context [aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) associates an interactive element with extra information, ensuring screen reader users receive helpful guidance without disrupting the UI. #### Difference between aria-labelledby and aria-describedby Attribute Purpose When to use it? Reading order aria-labelledby Defines the main context of the element When an element has no visible text or needs an external label Read first by the screen reader aria-describedby Provides additional description When secondary information is needed to clarify context Read after the main label #### When to use aria-labelledby vs aria-describedby? Use case aria-labelledby aria-describedby Use an external / hidden label Add complementary information Associate multiple elements to form a label (field group) Provide contextual help / information (e.g., input rules, field error) ```tsx Delete item ``` Screen readers won't announce the **Modal** content. ```tsx Delete item ``` Screen readers will announce the **Modal** content. #### Related Sources * [MDN Documentation - aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) * [RGAA - 11.10](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.10) ### aria-hidden: Hiding elements from screen readers Use [aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) set to `"true"` on elements that are purely decorative and should not be announced by screen readers. ```tsx ``` Some screen readers will announce the icon and detect the presence of the image. > Depending on the screen reader, some additional information might be read aloud, which is confusing and unhelpful. ```tsx ``` Screen readers will announce nothing, the icon is ignored. #### Related Sources * [MDN Documentation - aria-hidden](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-hidden) * [RGAA - 11.2](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.2) ### aria-busy: Indicating loading state When a section of the UI is loading, users should be informed that the content is not yet ready. [aria-busy](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) set to `"true"` signals that an element is currently in a loading state. Once loading is complete, `aria-busy` should be set to `"false"`. ```tsx
``` Screen readers will give no indication that the content is loading. The screen reader may start reading the page without knowing that this section is waiting to be updated. ```tsx
``` Screen readers understand that the content is not yet ready, so they delay announcing or interacting with it. #### Related Sources * [MDN Documentation - aria-busy](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-busy) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### status role: Announcing dynamic status changes Use [status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) to ensure that important updates are announced by screen readers without disrupting focus. ```tsx { const [message, setMessage] = useState(''); const handleClick = () => { setMessage('Copied to clipboard.'); }; return ( <> { message } ); } ``` Screen readers will announce the button and its label. ```tsx { const [message, setMessage] = useState(''); const handleClick = () => { setMessage('Copied to clipboard.'); }; return ( <> { message } ); } ``` Screen readers will announce the button and its label, and the message on click or press. > It also matters since it keeps focus on the button, avoiding disruption for keyboard users. #### Related Sources * [MDN Documentation - status role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/status_role) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### alert role: Announcing important messages Use [alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) for critical, time-sensitive messages that require immediate attention. Unlike `status role`, `alert role` is announced by screen readers, even if the user is focused elsewhere. ```tsx { const [error, setError] = useState(''); const handleClick = () => { setError('A critical error occurred while saving.'); }; return ( <> { error } ); } ``` Screen readers won’t immediately announce the error message when it appears, unless the user manually navigates to it. ```tsx { const [error, setError] = useState(''); const handleClick = () => { setError('A critical error occurred while saving!'); }; return ( <> { error } ); } ``` Screen readers will announce the error message, even when the user is focused elsewhere. #### Related Sources * [MDN Documentation - alert role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alert_role) * [RGAA - 7.4](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#7.4) ### radiogroup and radio roles: Making custom radio controls accessible [radiogroup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radiogroup_role) and [radio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/radio_role) roles ensure that screen readers correctly interpret and announce the selection. ```tsx <>
``` Screen readers will read each star individually with no context of selection group. ```tsx <>
``` Screen readers will announce a radio button, its label and aria-label, which item is focused on out of the total amount of items and that it is a radio group. > Please note that you should navigate within a radio group using `Arrow` keys. In the example above, `tabindex="-1"` is applied to all elements except the currently selected one. This is because only one item in a radio group should be focusable at a time. Users can navigate between options using the `Arrow` keys, rather than the `Tab` key, which moves focus to the next interactive element outside the group. For more details, see [Managing focus within components using a roving tabindex](https://www.w3.org/WAI/ARIA/apg/patterns/radio/examples/radio/) #### Sources * [MDN Documentation - radiogroup](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radiogroup_role) * [MDN Documentation - radio](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radio_role) * [RGAA - 11.5](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests/#11.5) ## Final Accessibility check for ARIA roles ### Validate the screen reader behavior Test with a screen reader to ensure that your changes are communicated correctly. Ensure that actions such as button clicks, form submissions, and changes in state are clearly communicated to the user. ### Testing Environment For consistent testing across different platforms and screen readers, here is the testing setup used by **OVHcloud Design System**, based on the recommendations from RGAA (France): Assistive Technology Browser NVDA Firefox JAWS Firefox or Internet Explorer Safari VoiceOver ## Resources to help you test accessibility * [Accessibility France Guidelines (FR)](https://accessibilite.numerique.gouv.fr): The French government's official accessibility resource for best practices and testing criteria * [Web Content Accessibility Guidelines (WCAG) 2.1](https://www.w3.org/TR/WCAG21): The internationally recognized standards for web accessibility, providing guidelines for creating more accessible web content * [WebAIM: Introduction to Web Accessibility](https://webaim.org/intro): A guide to the principles of web accessibility from WebAIM * [WebAIM: Semantic Structure](https://webaim.org/techniques/semanticstructure): Learn about the importance of semantic HTML and how it impacts accessibility * [WebAIM: Contrast Checker](https://webaim.org/resources/contrastchecker): Tool to ensure sufficient color contrast between text and background for readability * [French Accessibility Testing Methodology (FR)](https://accessibilite.numerique.gouv.fr/methode/criteres-et-tests): An in-depth guide to testing web accessibility in France * [French Testing Environment (FR)](https://accessibilite.numerique.gouv.fr/methode/environnement-de-test): Official guidelines on the tools and technologies to use when testing accessibility on desktop computers * [W3C Tutorial on Alternative Text for Images](https://www.w3.org/WAI/tutorials/images/decision-tree): A decision tree for writing appropriate alternative text for images