Accessibility
iTwinUI is built and tested to be inclusive and usable with assistive technologies. iTwinUI aims to be accessible by default where possible. However, iTwinUI also lacks the necessary context to handle everything out-of-the-box in every case. For example:
- iTwinUI’s color palette is carefully chosen to satisfy WCAG color contrast requirements. This assumption requires that the right color pairings are used depending on the scenario.
- iTwinUI components have accessibility features baked in, adhering to established WAI-ARIA patterns where applicable. This requires applications to pass the recommended props (e.g. labels) and not combine components in an incompatible manner.
There are some additional accessibility considerations for applications, described below. In all cases, the final user experience should be tested to ensure that it is actually accessible. We recommend running automated tests on every screen (using a tool like Lighthouse), and supplementing those automated tests with a manual audit to find issues that are difficult to detect automatically.
Metadata
Applications should set the lang attribute on the <html> element. This can be done from the application entrypoint (whether that’s a plain HTML file or a JSX root layout). The value of the lang attribute should coincide with the current language of the interface.
<html lang="en"> …</html>Every page must have a unique <title> that identifies the page. For example, the application’s home page might have the title “Home — Acme Application”, and a projects page might have the title “Projects — Acme Application”.
<title>{pageName} — {applicationName}</title>Single-page applications
When working with single-page applications, setting the title might require using your framework’s built-in metadata API, or a third-party library like react-helmet.
When navigating between pages on a regular website, screen-readers will automatically announce the page title. Within a single-page application, you might need to use a live region to emulate the same functionality. Some frameworks come with a built-in route announcer, while others might require implementing this manually.
In some cases, it may be necessary to programmatically move focus after a client-side navigation occurs. This helps ensure that the new content can be easily reached by keyboard users.
Landmarks
Landmarks are a set of eight roles that identify the major sections of a page. Landmarks allow assistive technology users to quickly browse and skip to relevant content.
The main content of the page must be wrapped in a <main> element. This works well when combined with iTwinUI’s <Header>, <SideNavigation>, and <Footer> components.
<Header>…</Header><SideNavigation>…</SideNavigation><main>…</main><Footer />Depending on the complexity of the content, you may need to set up additional landmarks for a better user experience. Also, consider using a <SkipToContentLink> to allow keyboard users to easily find the main landmark.
Headings
Headings communicate the organization of the page content. Assistive technology users rely on headings, in addition to landmarks, to navigate and understand the page.
- Every page must have one
<h1>element that identifies the page.- This heading often coincides with the page title.
- Every major section of the page might contain an
<h2>element. - Sub-sections of the major sections might be identified with
<h3>.
It is important to not skip heading levels (e.g. going from <h2> to <h4>). iTwinUI’s <Text> component decouples the heading’s visual presentation from its semantics, which helps ensure that a proper heading structure can be utilized regardless of the desired visuals.
In some designs, the page might not have an obvious candidate to be used as the <h1>. Since every page is required to have an <h1>, this heading can be rendered as <VisuallyHidden> to maintain a sensible heading structure without impacting visuals.
<VisuallyHidden as='h1'>Projects</VisuallyHidden>