From 64bca2e7428c1e96d0da1c6591d6bc814a83f261 Mon Sep 17 00:00:00 2001 From: Geoff Rich <4992896+geoffrich@users.noreply.github.com> Date: Mon, 8 Aug 2022 16:45:47 -0700 Subject: [PATCH 1/5] docs: add a11y docs --- documentation/docs/19-accessibility.md | 63 ++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 documentation/docs/19-accessibility.md diff --git a/documentation/docs/19-accessibility.md b/documentation/docs/19-accessibility.md new file mode 100644 index 000000000000..349a0c6adc71 --- /dev/null +++ b/documentation/docs/19-accessibility.md @@ -0,0 +1,63 @@ +--- +title: Accessibility +--- + +SvelteKit strives to provide an accessible platform for your app by default. Svelte's [compile-time accessibility checks](https://svelte.dev/docs#accessibility-warnings) will also apply to any SvelteKit application you build. + +Here's how SvelteKit's built-in accessibility features work and what you need to do to help these features to work as well as possible. + +We recognize that accessibility can be hard to get right. If you want to suggest improvements to how SvelteKit handles accessibility, please [open a GitHub issue](https://github.com/sveltejs/kit/issues). + +### Route announcements + +In traditional server-rendered applications, every navigation (e.g. clicking on an `` tag) triggers a full page reload. When this happens, screen readers and other assistive technology will read out the new page's title so that users understand that the page has changed. + +Since navigation between pages in SvelteKit happens without reloading the page (known as [client-side routing](/docs/appendix#routing)), SvelteKit injects a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) onto the page that will read out the new page name after each navigation. This determines the page name to announce by inspecting the `` element. + +Because of this behavior, every page in your app should have a unique, descriptive title. In SvelteKit, you can do this by placing a `<svelte:head>` element on each page: + +```svelte +/// file: src/routes/index.svelte +<svelte:head> + <title>Todo List + +``` + +This will allow screen readers and other assistive technology to identify the new page after a navigation occurs. Providing a descriptive title is also important for [SEO](/docs/seo#manual-setup-title-and-meta). + +### Focus management + +In traditional server-rendered applications, every navigation will reset focus to the top of the page. This ensures that people browsing the web with a keyboard or screen reader will start interacting with the page from the beginning. + +To simulate this behavior during client-side routing, SvelteKit focuses the `` element after each navigation. If you want to customize this behavior, you can implement custom focus management logic using the `afterNavigate` hook: + +```js +/// +// ---cut--- +import { afterNavigate } from '$app/navigation'; + +afterNavigate(() => { + /** @type {HTMLElement | null} */ + const to_focus = document.querySelector('.focus-me'); + to_focus?.focus(); +}); +``` + +You can also programmatically navigate to a different page using the [`goto`](/docs/modules#$app-navigation-goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepfocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. + +### Lang attribute + +By default, SvelteKit's page template sets the default language of the document to English. If your content is not in English, you should update the `` element in `src/app.html` to have the correct [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#accessibility) attribute. This will ensure that any assistive technology reading the document uses the correct pronunciation. For example, if your content is in German, you should update `app.html` to the following: + +```html +/// file: src/app.html + +``` + +### Further reading + +For the most part, building an accessible SvelteKit app is the same as building an accessible web app. You should be able to apply information from the following general accessibility resources to any web experience you build: + +- [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility) +- [The A11y Project](https://www.a11yproject.com/) +- [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/) \ No newline at end of file From 3d788cdf9dd59e5eca8cdc5248d5ddcbf6fd761e Mon Sep 17 00:00:00 2001 From: Geoff Rich <4992896+geoffrich@users.noreply.github.com> Date: Sat, 13 Aug 2022 20:32:32 -0700 Subject: [PATCH 2/5] Respond to PR feedback --- documentation/docs/19-accessibility.md | 29 ++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/documentation/docs/19-accessibility.md b/documentation/docs/19-accessibility.md index 349a0c6adc71..d5d7798f344d 100644 --- a/documentation/docs/19-accessibility.md +++ b/documentation/docs/19-accessibility.md @@ -4,7 +4,7 @@ title: Accessibility SvelteKit strives to provide an accessible platform for your app by default. Svelte's [compile-time accessibility checks](https://svelte.dev/docs#accessibility-warnings) will also apply to any SvelteKit application you build. -Here's how SvelteKit's built-in accessibility features work and what you need to do to help these features to work as well as possible. +Here's how SvelteKit's built-in accessibility features work and what you need to do to help these features to work as well as possible. Keep in mind that while SvelteKit aims to provide an accessible foundation, you are still responsible for making sure your application code is accessible. If you're new to accessibility, see the ["further reading"](/docs/accessibility#further-reading) section of this guide for additional resources. We recognize that accessibility can be hard to get right. If you want to suggest improvements to how SvelteKit handles accessibility, please [open a GitHub issue](https://github.com/sveltejs/kit/issues). @@ -43,7 +43,7 @@ afterNavigate(() => { }); ``` -You can also programmatically navigate to a different page using the [`goto`](/docs/modules#$app-navigation-goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepfocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. +You can also programmatically navigate to a different page using the [`goto`](/docs/modules#$app-navigation-goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepfocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. If the element no longer exists, the user's focus will be lost, making for a confusing experience for assistive technology users. ### Lang attribute @@ -54,6 +54,31 @@ By default, SvelteKit's page template sets the default language of the document ``` +If your content is available in multiple languages, you should set the `lang` attribute based on the language of the current page. You can do this with SvelteKit's [handle hook](/docs/hooks#handle): + +```html +/// file: src/app.html + +``` + +```js +/// file: src/hooks.js +/** + * @param {import('@sveltejs/kit').RequestEvent} event + * @returns {string} + */ +function get_lang(event) { + return 'en'; +} +// ---cut--- +/** @type {import('@sveltejs/kit').Handle} */ +export function handle({ event, resolve }) { + return resolve(event, { + transformPageChunk: ({ html }) => html.replace("%lang", get_lang(event)) + }); +} +``` + ### Further reading For the most part, building an accessible SvelteKit app is the same as building an accessible web app. You should be able to apply information from the following general accessibility resources to any web experience you build: From d1c21bb58b35f0a8030bb25deb3177b1f2a62149 Mon Sep 17 00:00:00 2001 From: Geoff Rich <4992896+geoffrich@users.noreply.github.com> Date: Tue, 16 Aug 2022 07:45:29 -0700 Subject: [PATCH 3/5] Use +page --- documentation/docs/19-accessibility.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/documentation/docs/19-accessibility.md b/documentation/docs/19-accessibility.md index d5d7798f344d..5efdaa764518 100644 --- a/documentation/docs/19-accessibility.md +++ b/documentation/docs/19-accessibility.md @@ -2,9 +2,9 @@ title: Accessibility --- -SvelteKit strives to provide an accessible platform for your app by default. Svelte's [compile-time accessibility checks](https://svelte.dev/docs#accessibility-warnings) will also apply to any SvelteKit application you build. +SvelteKit strives to provide an accessible platform for your app by default. Svelte's [compile-time accessibility checks](https://svelte.dev/docs#accessibility-warnings) will also apply to any SvelteKit application you build. -Here's how SvelteKit's built-in accessibility features work and what you need to do to help these features to work as well as possible. Keep in mind that while SvelteKit aims to provide an accessible foundation, you are still responsible for making sure your application code is accessible. If you're new to accessibility, see the ["further reading"](/docs/accessibility#further-reading) section of this guide for additional resources. +Here's how SvelteKit's built-in accessibility features work and what you need to do to help these features to work as well as possible. Keep in mind that while SvelteKit provides an accessible foundation, you are still responsible for making sure your application code is accessible. If you're new to accessibility, see the ["further reading"](/docs/accessibility#further-reading) section of this guide for additional resources. We recognize that accessibility can be hard to get right. If you want to suggest improvements to how SvelteKit handles accessibility, please [open a GitHub issue](https://github.com/sveltejs/kit/issues). @@ -17,7 +17,7 @@ Since navigation between pages in SvelteKit happens without reloading the page ( Because of this behavior, every page in your app should have a unique, descriptive title. In SvelteKit, you can do this by placing a `` element on each page: ```svelte -/// file: src/routes/index.svelte +/// file: src/routes/+page.svelte Todo List @@ -74,7 +74,7 @@ function get_lang(event) { /** @type {import('@sveltejs/kit').Handle} */ export function handle({ event, resolve }) { return resolve(event, { - transformPageChunk: ({ html }) => html.replace("%lang", get_lang(event)) + transformPageChunk: ({ html }) => html.replace('%lang', get_lang(event)) }); } ``` @@ -85,4 +85,4 @@ For the most part, building an accessible SvelteKit app is the same as building - [MDN Web Docs: Accessibility](https://developer.mozilla.org/en-US/docs/Learn/Accessibility) - [The A11y Project](https://www.a11yproject.com/) -- [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/) \ No newline at end of file +- [How to Meet WCAG (Quick Reference)](https://www.w3.org/WAI/WCAG21/quickref/) From 364557ffb57c30cdeb2e12a9f95a6d2ed71e10f0 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Tue, 16 Aug 2022 12:54:37 -0400 Subject: [PATCH 4/5] Update documentation/docs/19-accessibility.md --- documentation/docs/19-accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/19-accessibility.md b/documentation/docs/19-accessibility.md index 5efdaa764518..4de8653f90a1 100644 --- a/documentation/docs/19-accessibility.md +++ b/documentation/docs/19-accessibility.md @@ -74,7 +74,7 @@ function get_lang(event) { /** @type {import('@sveltejs/kit').Handle} */ export function handle({ event, resolve }) { return resolve(event, { - transformPageChunk: ({ html }) => html.replace('%lang', get_lang(event)) + transformPageChunk: ({ html }) => html.replace('%lang%', get_lang(event)) }); } ``` From 44d70f1e0fc9fd9fe14398f1778c159847ed3086 Mon Sep 17 00:00:00 2001 From: Geoff Rich <4992896+geoffrich@users.noreply.github.com> Date: Tue, 16 Aug 2022 10:06:14 -0700 Subject: [PATCH 5/5] Update documentation/docs/19-accessibility.md Co-authored-by: Rich Harris --- documentation/docs/19-accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/19-accessibility.md b/documentation/docs/19-accessibility.md index 4de8653f90a1..b2ca4c9aa789 100644 --- a/documentation/docs/19-accessibility.md +++ b/documentation/docs/19-accessibility.md @@ -45,7 +45,7 @@ afterNavigate(() => { You can also programmatically navigate to a different page using the [`goto`](/docs/modules#$app-navigation-goto) function. By default, this will have the same client-side routing behavior as clicking on a link. However, `goto` also accepts a `keepfocus` option that will preserve the currently-focused element instead of resetting focus. If you enable this option, make sure the currently-focused element still exists on the page after navigation. If the element no longer exists, the user's focus will be lost, making for a confusing experience for assistive technology users. -### Lang attribute +### The "lang" attribute By default, SvelteKit's page template sets the default language of the document to English. If your content is not in English, you should update the `` element in `src/app.html` to have the correct [`lang`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/lang#accessibility) attribute. This will ensure that any assistive technology reading the document uses the correct pronunciation. For example, if your content is in German, you should update `app.html` to the following: