diff --git a/apps/website/src/pages/docs/accessibility.mdx b/apps/website/src/pages/docs/accessibility.mdx new file mode 100644 index 00000000000..3cdf7ab367b --- /dev/null +++ b/apps/website/src/pages/docs/accessibility.mdx @@ -0,0 +1,62 @@ +--- +title: Accessibility +layout: ./_layout.astro +--- + +## Metadata + +Applications should set the [`lang` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang) on the `` element. This can be done from the application entrypoint (whether that's a plain HTML file or a JSX root layout). + +```html + +``` + +Every page must have a unique `` 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". + +```html +<title>{pageName} — {applicationName} +``` + +### 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`](https://github.com/nfl/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](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) to emulate the same functionality. Some frameworks come with a [built-in route announcer](https://nextjs.org/docs/architecture/accessibility#route-announcements), while others might require implementing this manually. + +## Landmarks + +[Landmarks](https://www.w3.org/WAI/ARIA/apg/patterns/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 `
` element. This works well when combined with iTwinUI's [`
`](/docs/header), [``](/docs/sidenavigation), and [`