From 93161c04653d57a747fab8cf7619dfd042a701ea Mon Sep 17 00:00:00 2001 From: madalynrose Date: Wed, 29 Jan 2020 15:42:21 -0500 Subject: [PATCH 01/11] WIP draft --- .../index.md | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md new file mode 100644 index 0000000000000..b9f92db24c064 --- /dev/null +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -0,0 +1,59 @@ +--- +title: "Accessibility Improvements to Client Side Routing - Available in 2.19.8" +date: 2020-02-05 +author: "Madalyn Parker" +excerpt: "We recently released accessibility improvements to client side routing, enabling screen reader users to successfully navigate sites built with Gatsby." +tags: ["accessibility, client-side-routing, diversity-and-inclusion"] +--- + +We recently released accessibility improvements to client side routing, building on previous focus management [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) improvements released in 2019. These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at this [issue](https://github.com/gatsbyjs/gatsby/issues/5581) opened way back in May 2018. + +In July of 2019 Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to ultimately determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](https://www.gatsbyjs.org/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: + +> - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. +> +> - Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. + +### Some Background + +Our first step to addressing focus management (the first recommendation, above) was [switching](https://www.gatsbyjs.org/blog/2018-09-27-reach-router/) to [@reach/router](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of @reach/router isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by @reach/router. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping div. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of @reach/router’s strengths. + +Gatsby's .org site takes advantage of @reach/router’s [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to implement this on your site to ensure you're also following the recommendations from our research. + +### New Improvements + +The changes that were just shipped address the second recommendation above, adding a live region that announces route changes. Using @reach-router alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything on client-side route changes. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of technologies used. +Our solution appends a `RouteAnnouncer` component as a sibling of our main focus wrapper. + +```jsx + + {this.props.children} //gatsby-focus-wrapper + + +``` + +The RouteAnnouncer is a component that renders an ARIA live region. This region has `aria-live` set to `assertive` because we want route changes to always interrupt whatever the screen reader is currently doing. We’ve also set `aria-atomic` to true because we want every change to the content of this div to be announced. Our live region has inline styles to position it off of the page, as recommended by [WebAIM](https://webaim.org/techniques/css/invisiblecontent/#offscreen). + +`````jsx +
+
```` + +### What’s Next +Localization +Configuration/announcement component/ref +````` From 733b0bb3341a69014e093c1be0e0a241479eae76 Mon Sep 17 00:00:00 2001 From: madalynrose Date: Wed, 29 Jan 2020 16:50:04 -0500 Subject: [PATCH 02/11] rough draft --- .../index.md | 57 ++++++++++--------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index b9f92db24c064..344a384017b04 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -6,9 +6,9 @@ excerpt: "We recently released accessibility improvements to client side routing tags: ["accessibility, client-side-routing, diversity-and-inclusion"] --- -We recently released accessibility improvements to client side routing, building on previous focus management [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) improvements released in 2019. These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at this [issue](https://github.com/gatsbyjs/gatsby/issues/5581) opened way back in May 2018. +We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at this [issue](https://github.com/gatsbyjs/gatsby/issues/5581) opened way back in May 2018. -In July of 2019 Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to ultimately determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](https://www.gatsbyjs.org/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: +In July of 2019 Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](https://www.gatsbyjs.org/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: > - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. > @@ -18,11 +18,12 @@ In July of 2019 Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeit Our first step to addressing focus management (the first recommendation, above) was [switching](https://www.gatsbyjs.org/blog/2018-09-27-reach-router/) to [@reach/router](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of @reach/router isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by @reach/router. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping div. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of @reach/router’s strengths. -Gatsby's .org site takes advantage of @reach/router’s [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to implement this on your site to ensure you're also following the recommendations from our research. +Gatsby's .org site uses @reach/router’s [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to take advantage of this on your site to ensure you're also following the recommendations from our research. ### New Improvements -The changes that were just shipped address the second recommendation above, adding a live region that announces route changes. Using @reach-router alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything on client-side route changes. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of technologies used. +The changes that were just shipped address the second recommendation above, adding an ARIA live region that announces route changes. Using @reach-router alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of technologies used. + Our solution appends a `RouteAnnouncer` component as a sibling of our main focus wrapper. ```jsx @@ -32,28 +33,30 @@ Our solution appends a `RouteAnnouncer` component as a sibling of our main focus ``` -The RouteAnnouncer is a component that renders an ARIA live region. This region has `aria-live` set to `assertive` because we want route changes to always interrupt whatever the screen reader is currently doing. We’ve also set `aria-atomic` to true because we want every change to the content of this div to be announced. Our live region has inline styles to position it off of the page, as recommended by [WebAIM](https://webaim.org/techniques/css/invisiblecontent/#offscreen). - -`````jsx -
-
```` +The RouteAnnouncer is a component that renders an ARIA live region. This region has `aria-live` set to `assertive` because we want route changes to always interrupt whatever the screen reader is currently doing. We’ve also set `aria-atomic` to true because we want every change to the content of this div to be announced. Our ARIA live region has inline styles to hide it visually, as recommended by [WebAIM](https://webaim.org/techniques/css/invisiblecontent/#offscreen). + +```jsx +
+``` + +This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared with sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. ### What’s Next -Localization -Configuration/announcement component/ref -````` + +Now that this large improvement has been shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in. Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page. As always, we're open to suggestions from the community. From 7e5bc3797a79294ffc02cf1ad7aa43c7bdb6dfbb Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Thu, 30 Jan 2020 14:19:28 -0500 Subject: [PATCH 03/11] Apply stylistic suggestions from code review Co-Authored-By: LB --- .../index.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index 344a384017b04..a6a022c9f2b36 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -8,21 +8,20 @@ tags: ["accessibility, client-side-routing, diversity-and-inclusion"] We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at this [issue](https://github.com/gatsbyjs/gatsby/issues/5581) opened way back in May 2018. -In July of 2019 Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](https://www.gatsbyjs.org/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: +In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: -> - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. -> -> - Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. +- Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. +- Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. ### Some Background -Our first step to addressing focus management (the first recommendation, above) was [switching](https://www.gatsbyjs.org/blog/2018-09-27-reach-router/) to [@reach/router](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of @reach/router isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by @reach/router. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping div. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of @reach/router’s strengths. +Our first step to addressing focus management (the first recommendation, above) was [switching](/blog/2018-09-27-reach-router/) to [`@reach/router`](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of `@reach/router` isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by `@reach/router`. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping `div`. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of `@reach/router’s` strengths. -Gatsby's .org site uses @reach/router’s [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to take advantage of this on your site to ensure you're also following the recommendations from our research. +Gatsby's .org site uses `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to take advantage of this on your site to ensure you're also following the recommendations from our research. ### New Improvements -The changes that were just shipped address the second recommendation above, adding an ARIA live region that announces route changes. Using @reach-router alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of technologies used. +The changes that were just shipped address the second recommendation above, adding an ARIA live region that announces route changes. Using `@reach-router` alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of the technologies used. Our solution appends a `RouteAnnouncer` component as a sibling of our main focus wrapper. @@ -33,7 +32,7 @@ Our solution appends a `RouteAnnouncer` component as a sibling of our main focus ``` -The RouteAnnouncer is a component that renders an ARIA live region. This region has `aria-live` set to `assertive` because we want route changes to always interrupt whatever the screen reader is currently doing. We’ve also set `aria-atomic` to true because we want every change to the content of this div to be announced. Our ARIA live region has inline styles to hide it visually, as recommended by [WebAIM](https://webaim.org/techniques/css/invisiblecontent/#offscreen). +The `RouteAnnouncer` is a component that renders an ARIA live region. This region has `aria-live` set to `assertive` because we want route changes to always interrupt whatever the screen reader is currently doing. We’ve also set `aria-atomic` to true because we want every change to the content of this `div` to be announced. Our ARIA live region has inline styles to hide it visually, as recommended by [WebAIM](https://webaim.org/techniques/css/invisiblecontent/#offscreen). ```jsx
``` -This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared with sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. +This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared to sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. ### What’s Next -Now that this large improvement has been shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in. Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page. As always, we're open to suggestions from the community. +Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in. Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page. As always, we're open to suggestions from the community. From c86e9abd538752d0b235131fa1ac6d49e54d55d4 Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Thu, 30 Jan 2020 14:58:04 -0500 Subject: [PATCH 04/11] add links to issues for upcoming features also add descriptive text for issue #5581 --- .../index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index a6a022c9f2b36..95fa4a7f0dbaf 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -6,7 +6,7 @@ excerpt: "We recently released accessibility improvements to client side routing tags: ["accessibility, client-side-routing, diversity-and-inclusion"] --- -We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at this [issue](https://github.com/gatsbyjs/gatsby/issues/5581) opened way back in May 2018. +We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in the ["a11y issues: page nav doesn't trigger assistive tech" issue](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: @@ -58,4 +58,6 @@ This component sets the content to be announced (e.g. "Navigated to Gatsby Blog" ### What’s Next -Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in. Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page. As always, we're open to suggestions from the community. +Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in (see [issue 20801](https://github.com/gatsbyjs/gatsby/issues/20801)). Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page (see [issue 21059](https://github.com/gatsbyjs/gatsby/issues/21059)). + +As always, we'd love to hear ideas and suggestions from the community. From b5bd8704515fb18a1cdc88e54c4bd32c8e323f6c Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Thu, 30 Jan 2020 16:51:12 -0500 Subject: [PATCH 05/11] update verbiage for a11y nav issue link --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index 95fa4a7f0dbaf..d1affefcb3142 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -6,7 +6,7 @@ excerpt: "We recently released accessibility improvements to client side routing tags: ["accessibility, client-side-routing, diversity-and-inclusion"] --- -We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in the ["a11y issues: page nav doesn't trigger assistive tech" issue](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. +We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: From 7987e5403fcccc1d3d8a34d63058891ff3a49086 Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Thu, 30 Jan 2020 17:17:17 -0500 Subject: [PATCH 06/11] remove unnecessary "/" --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index d1affefcb3142..7b7163e83c7bc 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -8,7 +8,7 @@ tags: ["accessibility, client-side-routing, diversity-and-inclusion"] We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. -In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to \ determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: +In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. - Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. From 9d5d589695745fd5265d8876b596986e47e95b1b Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Fri, 31 Jan 2020 14:03:43 -0500 Subject: [PATCH 07/11] Apply stylistic suggestions from code review Co-Authored-By: Marcy Sutton --- .../index.md | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index 7b7163e83c7bc..b89b12ffaa6ca 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -1,27 +1,27 @@ --- -title: "Accessibility Improvements to Client Side Routing - Available in 2.19.8" +title: "Accessibility Improvements to Client Side Routing in Gatsby - Available in 2.19.8" date: 2020-02-05 author: "Madalyn Parker" excerpt: "We recently released accessibility improvements to client side routing, enabling screen reader users to successfully navigate sites built with Gatsby." tags: ["accessibility, client-side-routing, diversity-and-inclusion"] --- -We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. +We recently released accessibility improvements to client side routing in Gatsby core, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. -In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: +In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine the best user experience for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. - Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. -### Some Background +## Some Background Our first step to addressing focus management (the first recommendation, above) was [switching](/blog/2018-09-27-reach-router/) to [`@reach/router`](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of `@reach/router` isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by `@reach/router`. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping `div`. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of `@reach/router’s` strengths. Gatsby's .org site uses `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to take advantage of this on your site to ensure you're also following the recommendations from our research. -### New Improvements +## New Improvements -The changes that were just shipped address the second recommendation above, adding an ARIA live region that announces route changes. Using `@reach-router` alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of the technologies used. +The functionality that just shipped addresses the recommendation to add an ARIA live region that announces route changes. Using `@reach-router` alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of the technologies used. Our solution appends a `RouteAnnouncer` component as a sibling of our main focus wrapper. @@ -54,10 +54,12 @@ The `RouteAnnouncer` is a component that renders an ARIA live region. This regio > ``` -This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared to sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. +This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a React `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. -### What’s Next +One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared to sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. -Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in (see [issue 20801](https://github.com/gatsbyjs/gatsby/issues/20801)). Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page (see [issue 21059](https://github.com/gatsbyjs/gatsby/issues/21059)). +## What’s Next -As always, we'd love to hear ideas and suggestions from the community. +Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language in which a user is navigating the web (see [issue 20801](https://github.com/gatsbyjs/gatsby/issues/20801)). Additionally, we would like to offer additional customization for developers, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page (see [issue 21059](https://github.com/gatsbyjs/gatsby/issues/21059)). + +As always, we'd love to hear ideas and suggestions from the community on existing and/or new issues in the Gatsby GitHub repo. From fef7aaa7d7b895fb1b81f15f72589e12d87ea0dc Mon Sep 17 00:00:00 2001 From: madalynrose Date: Fri, 31 Jan 2020 17:01:36 -0500 Subject: [PATCH 08/11] add skip nav examples --- .../index.md | 67 +++++++++++++++---- 1 file changed, 55 insertions(+), 12 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index 7b7163e83c7bc..e7ada408ddfee 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -1,27 +1,68 @@ --- -title: "Accessibility Improvements to Client Side Routing - Available in 2.19.8" +title: "Accessibility Improvements to Client Side Routing in Gatsby - Available in 2.19.8" date: 2020-02-05 author: "Madalyn Parker" excerpt: "We recently released accessibility improvements to client side routing, enabling screen reader users to successfully navigate sites built with Gatsby." tags: ["accessibility, client-side-routing, diversity-and-inclusion"] --- -We recently released accessibility improvements to client side routing, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. +We recently released accessibility improvements to client side routing in Gatsby core, building on previous focus management improvements [released in version 2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197). These improvements enable people relying on screen readers to successfully navigate sites built with Gatsby. If you'd like an in-depth look at how we made incremental changes to get to this release, have a look at the conversation in this [issue about assistive technology and navigation](https://github.com/gatsbyjs/gatsby/issues/5581). It was opened way back in May 2018. -In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine what the best user experience is for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: +In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine the best user experience for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. - Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. -### Some Background +## Some Background + +Our first step to addressing focus management (the first recommendation, above) was [switching](/blog/2018-09-27-reach-router/) to [`@reach/router`](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of `@reach/router` isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by `@reach/router`. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping `div`. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of `@reach/router’s` strengths. Both of these changes were a major improvement for most users, but because some assistive technologies (NVDA and VoiceOver in particular) were still not working, we kept [issue 5581](https://github.com/gatsbyjs/gatsby/issues/5581) open and continued to make incremental changes over time. + +While this work prioritizes screen reader users, we are still far from the most accessible solution for other disabilities. For example, users who rely on magnification, voice navigation users, and users relying on switches (devices that replace the need to use a keyboard or a mouse) have a hard time orienting themselves on a new page if focus is set on too large of an element or an inoperable element (like our wrapper `div`). Sending focus directly to a smaller, interactive control like a skip link is ideal. Unfortunately, we're limited with what we can programmatically achieve at the framework level (we have no way of knowing if a skip link exists on site pages from our `Router`). + +For this reason, we encourage developers to take control of focus themselves. We encourage you to take advantage of `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) (or implement a skip link yourself) on your site. + +```javascript:title=layout.js +import { SkipNavLink, SkipNavContent } from "@reach/skip-nav" +import "@reach/skip-nav/styles.css" //this will auto show and hide the link on focus + +const Layout = ({ children }) => { + return ( + <> + +
+

Welcome to my site

+
+ +
{children}
+
+ © {new Date().getFullYear()}, Built with + {` `} + Gatsby +
+ + + ) +} +``` -Our first step to addressing focus management (the first recommendation, above) was [switching](/blog/2018-09-27-reach-router/) to [`@reach/router`](https://reach.tech/router). This got us part of the way there out-of-the-box. However, Gatsby’s implementation of `@reach/router` isn’t idiomatic in that Gatsby puts everything on a single, catch-all route. This means that every page is technically on the same route and route changes weren’t getting picked up by `@reach/router`. Our improvements in [2.13.2](https://github.com/gatsbyjs/gatsby/pull/13197) made sure that every time a route changed, we reset focus on a wrapping `div`. These changes also ensure that our single, catch-all route is dynamic so we can register changes and take advantage of `@reach/router’s` strengths. +Then you can make sure focus is directed there in your `gatsby-browser.js` file: + +```javascript:title=gatsby-browser.js +exports.onRouteUpdate = ({ location, prevLocation }) => { + if (prevLocation !== null) { + const skipLink = document.querySelector("#reach-skip-nav") + if (skipLink) { + skipLink.focus() + } + } +} +``` -Gatsby's .org site uses `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) in its [Layout Component](https://github.com/gatsbyjs/gatsby/blob/master/www/src/components/layout/layout-with-heading.js#L36), making that link the next element a user lands on when they navigate to a new page. We encourage you to take advantage of this on your site to ensure you're also following the recommendations from our research. +**Note:** After noticing that Gatsby's .org site was missing this, I whipped up a [Pull Request](). Incremental improvements are so important! -### New Improvements +## New Improvements -The changes that were just shipped address the second recommendation above, adding an ARIA live region that announces route changes. Using `@reach-router` alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of the technologies used. +The changes that were shipped in [PR #19290](https://github.com/gatsbyjs/gatsby/pull/19290) address the recommendation to add an ARIA live region that announces route changes. Using `@reach-router` alone got us most of the way there depending on which browser and screen reader combination someone is using; for most combinations, page content would be communicated when changing routes. However, we found that two of the [most popular](https://webaim.org/projects/screenreadersurvey8/#browsercombos) combinations (NVDA with FireFox and VoiceOver with Safari) weren’t announcing anything at all on client-side route changes. This leads to a confusing experience where users are unsure which page they are on and unsure if links are working. Implementing our ARIA live region ensures that there is consistent and reliable behavior regardless of the technologies used. Our solution appends a `RouteAnnouncer` component as a sibling of our main focus wrapper. @@ -54,10 +95,12 @@ The `RouteAnnouncer` is a component that renders an ARIA live region. This regio > ``` -This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared to sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. +This component sets the content to be announced (e.g. "Navigated to Gatsby Blog") by targeting the `innerText` on the `gatsby-announcer` div, selected by `ref`. Using a React `ref` and only updating the announcement text if it is different from the current announcement text prevents screen readers from repeating announcements if the page renders multiple times. + +One limitation of implementing this at the framework level is that we don't have access to what ultimately ends up on the pages, as they can be sourced from anywhere. For this reason, the announcement will always start with "Navigated to", followed by either the content of the first `h1` on the page, the `title` of the page, or `location.path` depending on what is present. Additionally, the differences between framework level and "userland" changes were evident when testing behavior compared to sites implementing similar changes themselves (e.g. Marcy Sutton's [example solution](https://github.com/marcysutton/gatsby-a11y-workshop/blob/master/examples/client-side-routing/gatsby-browser.js) as part of her [gatsby-a11y-workshop](https://github.com/marcysutton/gatsby-a11y-workshop)) and finding that the framework-level implementation had less consistent behavior and bugs with repetition. -### What’s Next +## What’s Next -Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language a user is navigating the web in (see [issue 20801](https://github.com/gatsbyjs/gatsby/issues/20801)). Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page (see [issue 21059](https://github.com/gatsbyjs/gatsby/issues/21059)). +Now that this large improvement is shipped, we'll continue building on our progress. Right now the English words "Navigated to" appear in every announcement. Because accessible solutions are meant to be [understandable](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Understandable), we aim to localize this string based on the language in which a user is navigating the web in (see [issue 20801](https://github.com/gatsbyjs/gatsby/issues/20801)). Additionally, we would like to offer additional customization for users, offering the option to specify an element to grab announcement text from instead of the `h1` or `title` on the page (see [issue 21059](https://github.com/gatsbyjs/gatsby/issues/21059)). -As always, we'd love to hear ideas and suggestions from the community. +As always, we'd love to hear ideas and suggestions from the community on existing and/or new issues in the [Gatsby GitHub repo](https://github.com/gatsbyjs/gatsby). From 82110a46a8789bc2e51c56ba11fb0e32c8caae68 Mon Sep 17 00:00:00 2001 From: madalynrose Date: Fri, 31 Jan 2020 17:26:28 -0500 Subject: [PATCH 09/11] add PR link --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index e7ada408ddfee..f505bc97c8125 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -58,7 +58,7 @@ exports.onRouteUpdate = ({ location, prevLocation }) => { } ``` -**Note:** After noticing that Gatsby's .org site was missing this, I whipped up a [Pull Request](). Incremental improvements are so important! +**Note:** After noticing that Gatsby's .org site was missing this, I whipped up a [Pull Request](https://github.com/gatsbyjs/gatsby/pull/21108). Incremental improvements are so important! ## New Improvements From 448fa9cbc2b64ef9d7aa07bd98c86d6370ea84c0 Mon Sep 17 00:00:00 2001 From: Madalyn <3230904+madalynrose@users.noreply.github.com> Date: Fri, 31 Jan 2020 21:52:54 -0500 Subject: [PATCH 10/11] Apply suggestions from code review Co-Authored-By: Marcy Sutton --- .../index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md index f505bc97c8125..5ed33ea97745f 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md @@ -11,7 +11,7 @@ We recently released accessibility improvements to client side routing in Gatsby In July of 2019, Marcy Sutton teamed up with [Fable Tech Labs](https://www.makeitfable.com/) to conduct user testing to determine the best user experience for navigating JavaScript applications. Marcy wrote a thorough [blog post](/blog/2019-07-11-user-testing-accessible-client-routing/) about that research. This left us with some concrete recommendations to execute on: - Provide a skip link that takes focus on a route change within the site, with a label that indicates what the link will do when activated: e.g. “skip to main navigation”. -- Include an ARIA Live Region on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. +- Include an [ARIA Live Region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) on page load. On a route change, append text to it indicating the current page, e.g. “Portfolio page”. ## Some Background @@ -19,7 +19,7 @@ Our first step to addressing focus management (the first recommendation, above) While this work prioritizes screen reader users, we are still far from the most accessible solution for other disabilities. For example, users who rely on magnification, voice navigation users, and users relying on switches (devices that replace the need to use a keyboard or a mouse) have a hard time orienting themselves on a new page if focus is set on too large of an element or an inoperable element (like our wrapper `div`). Sending focus directly to a smaller, interactive control like a skip link is ideal. Unfortunately, we're limited with what we can programmatically achieve at the framework level (we have no way of knowing if a skip link exists on site pages from our `Router`). -For this reason, we encourage developers to take control of focus themselves. We encourage you to take advantage of `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) (or implement a skip link yourself) on your site. +For this reason, we recommend that developers take control of focus themselves and assert the functionality in [automated tests](/docs/end-to-end-testing/#writing-tests). We encourage you to take advantage of `@reach/router’s` [skip nav functionality](https://reacttraining.com/reach-ui/skip-nav/) (or implement a skip link yourself) on your site. ```javascript:title=layout.js import { SkipNavLink, SkipNavContent } from "@reach/skip-nav" @@ -58,7 +58,7 @@ exports.onRouteUpdate = ({ location, prevLocation }) => { } ``` -**Note:** After noticing that Gatsby's .org site was missing this, I whipped up a [Pull Request](https://github.com/gatsbyjs/gatsby/pull/21108). Incremental improvements are so important! +**Note:** After noticing that Gatsby's .org site was missing this, I whipped up a [Pull Request](https://github.com/gatsbyjs/gatsby/pull/21108) to facilitate a design discussion and work through real-world feedback. Incremental improvements are so important! ## New Improvements From 16b5a761c341242d116bbecd088e1cbf553eca73 Mon Sep 17 00:00:00 2001 From: Sidhartha Chatterjee Date: Mon, 10 Feb 2020 03:08:43 +0530 Subject: [PATCH 11/11] Fix date --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename docs/blog/{2020-02-05-accessible-client-side-routing-improvements => 2020-02-10-accessible-client-side-routing-improvements}/index.md (99%) diff --git a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md b/docs/blog/2020-02-10-accessible-client-side-routing-improvements/index.md similarity index 99% rename from docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md rename to docs/blog/2020-02-10-accessible-client-side-routing-improvements/index.md index 5ed33ea97745f..517f5fea5807c 100644 --- a/docs/blog/2020-02-05-accessible-client-side-routing-improvements/index.md +++ b/docs/blog/2020-02-10-accessible-client-side-routing-improvements/index.md @@ -1,6 +1,6 @@ --- title: "Accessibility Improvements to Client Side Routing in Gatsby - Available in 2.19.8" -date: 2020-02-05 +date: 2020-02-10 author: "Madalyn Parker" excerpt: "We recently released accessibility improvements to client side routing, enabling screen reader users to successfully navigate sites built with Gatsby." tags: ["accessibility, client-side-routing, diversity-and-inclusion"]