Add accessibility documentation #5856
Conversation
|
|
|
||
| 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 |
There was a problem hiding this comment.
It might also be good to show how to dynamically update the lang attribute for multi-lang sites - see #3091 (comment)
There was a problem hiding this comment.
NB: the example in #3091 (comment) refers to transformPage() but this was replaced with transformPageChunk() in #5657.
There was a problem hiding this comment.
@geoffrich This is really useful information. It identifies what's available, what users need to do themselves, and reliable links for additional info. 👍
| }); | ||
| ``` | ||
|
|
||
| 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. |
There was a problem hiding this comment.
[question, suggestion] Is there a fallback if the element no longer exists? Might be useful to let devs know what the outcome would be, either way. 👍
There was a problem hiding this comment.
There's no fallback element -- when keepfocus is set, SvelteKit won't call focus at all. So if the element is removed, focus will be lost just as if you removed the currently focused element in vanilla JS. I can try to clarify this part a bit. Maybe add something like:
If the element no longer exists, the user's focus will be lost.
|
@geoffrich this is a great start, and the snippets you have included are really helpful. My only caution is that getting a11y right requires a lot more thought, and I wonder if this needs to be more explicit in the documentation? i.e., whilst Svelte/SvelteKit provides some really good helpers, on their own they don't make an a11y app. You're already thinking about this with the proposed 'Guides' section on learn.svelte.dev, but helping people be aware of the built-in capabilities as well as understand that these alone don't make an accessible app would be a really open approach to building a better AX. |
| 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). | ||
|
|
There was a problem hiding this comment.
I'm not really sure we need this sentence. It could apply to any section as we want people to open issues about issues they encounter anywhere.
| 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). |
There was a problem hiding this comment.
[comment] I thought this bit was thoughtful; it's signaling to the accessibility community that their feedback is welcome, which is a welcome exception in tech (by large, over the last 30 years). The sentence may not be a technical necessity but it might be a community necessity. Just a perspective to consider. 👍
There was a problem hiding this comment.
I can go either way on this, but Melanie captures why I included it in the first place. It emphasizes that we want to be receptive to a11y suggestions and improve as needed.
@accuser would something to this effect in the intro be what you're looking for? "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" section of this guide for additional resources." I had something similar to that in one of my drafts, but it got lost along the way. |
geoffrich
force-pushed
the
grich/a11y-docs
branch
from
644bfba
to
d1c21bb
Compare
|
The big |
Co-authored-by: Rich Harris <[email protected]>
Add docs around SvelteKit's accessibility features and what developers need to do to play nicely with them.
I focused these docs on SvelteKit-specific concerns (route announcements, focus management) instead of general a11y practices (e.g. skip link, button vs link, etc). In the future, a "Guides" section on learn.svelte.dev may be a good place to go deeper into general a11y best practices, or integrated into the official SvelteKit tutorial.
I'm looking for feedback on prose, accuracy of information, and thoughts on anything else we want to include (or exclude).
Leaving in draft for now until the dust settles on the big routing changes.
Prior art:
Context around route announcement/focus management: #307
Please don't delete this checklist! Before submitting the PR, please make sure you do the following:
Tests
pnpm testand lint the project withpnpm lintandpnpm checkChangesets
pnpm changesetand following the prompts. All changesets should bepatchuntil SvelteKit 1.0