From 5a6444f2d83059d002b0f4eba304b3d86ed36d6c Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 11 Jul 2022 11:13:05 -0500 Subject: [PATCH 1/2] Add documentation on accessibility. --- docs/accessibility.md | 46 +++++++++++++++++++++++++++++++++++++++++++ docs/manifest.json | 4 ++++ docs/upgrading.md | 4 ++++ 3 files changed, 54 insertions(+) create mode 100644 docs/accessibility.md diff --git a/docs/accessibility.md b/docs/accessibility.md new file mode 100644 index 0000000000000..583431be34bbb --- /dev/null +++ b/docs/accessibility.md @@ -0,0 +1,46 @@ +--- +description: Learn about the built-in accessibility features of Next.js. +--- + +# Accessibility + +The Next.js team is committed to making Next.js accessible to all developers (and their end-users). By adding accessibility features to Next.js by default, we aim to make the Web more inclusive for everyone. + +## Route Announcements + +When using screen readers or other assistive technology, routes are announced when navigating between pages. This works by default when transitioning between pages on the server (e.g. using the `` tag). + +Next.js also supports client-side transitions for improved performance (using `next/link`). To ensure that client-side transitions are also announced to assistive technology, Next.js includes a route announcer by default. + +The Next.js route announcer looks for the page name to announce by first inspecting `document.title`, then the `

` element, and finally the URL pathname. + +## Linting + +Next.js provides an [integrated ESLint experience](/docs/basic-features/eslint.md) out of the box, including custom rules for Next.js. By default, Next.js includes `eslint-plugin-jsx-a11y` to help catch accessibility issues early, including warning on: + +- [aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) +- [aria-proptypes](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-proptypes.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) +- [aria-unsupported-elements](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/aria-unsupported-elements.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) +- [role-has-required-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-has-required-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) +- [role-supports-aria-props](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/role-supports-aria-props.md?rgh-link-date=2021-06-04T02%3A10%3A36Z) + +For example, this plugin helps ensure you add alt text to `img` tags, use correct `aria-*` attributes, use correct `role` attributes, and more. + +## Disabling JavaScript + +By default, Next.js prerenders pages to static HTML files. This means that JavaScript is not required to view the HTML markup from the server and is instead used to add interactivity on the client side. + +If your application requires JavaScript to be disabled, and only HTML to be used, you can remove all JavaScript from your application using an experimental flag: + +```js +// next.config.js +export const config = { + unstable_runtimeJS: false, +} +``` + +## Accessibility Resources + +- Check [color contrast ratios](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) between foreground and background elements +- Use [`prefers-reduced-motion`](https://web.dev/prefers-reduced-motion/) when working with animations +- TODO add more pls diff --git a/docs/manifest.json b/docs/manifest.json index 84bdbdfb6335e..a4a5955c1d145 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -172,6 +172,10 @@ "title": "Testing", "path": "/docs/testing.md" }, + { + "title": "Accessibility", + "path": "/docs/accessibility.md" + }, { "title": "Guides", "routes": [ diff --git a/docs/upgrading.md b/docs/upgrading.md index 9f42281afaed1..855a4370e6043 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -4,6 +4,10 @@ description: Learn how to upgrade Next.js. # Upgrade Guide +## Upgrading to 12.2 + +If you were using Middleware prior to `12.2`, please see the [upgrade guide](https://nextjs.org/docs/messages/middleware-upgrade-guide) for more information. + ## Upgrading from 11 to 12 ### Minimum Node.js version From efd6d2e945246e47f7e882b15f1504c780b0d5e4 Mon Sep 17 00:00:00 2001 From: Lee Robinson Date: Mon, 11 Jul 2022 14:45:40 -0500 Subject: [PATCH 2/2] Address code review comments --- docs/accessibility.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/accessibility.md b/docs/accessibility.md index 583431be34bbb..dc4b4a40ab751 100644 --- a/docs/accessibility.md +++ b/docs/accessibility.md @@ -8,11 +8,11 @@ The Next.js team is committed to making Next.js accessible to all developers (an ## Route Announcements -When using screen readers or other assistive technology, routes are announced when navigating between pages. This works by default when transitioning between pages on the server (e.g. using the `` tag). +When transitioning between pages rendered on the server (e.g. using the `` tag) screen readers and other assistive technology announce the page title when the page loads so that users understand that the page has changed. -Next.js also supports client-side transitions for improved performance (using `next/link`). To ensure that client-side transitions are also announced to assistive technology, Next.js includes a route announcer by default. +In addition to traditional page navigations, Next.js also supports client-side transitions for improved performance (using `next/link`). To ensure that client-side transitions are also announced to assistive technology, Next.js includes a route announcer by default. -The Next.js route announcer looks for the page name to announce by first inspecting `document.title`, then the `

` element, and finally the URL pathname. +The Next.js route announcer looks for the page name to announce by first inspecting `document.title`, then the `

` element, and finally the URL pathname. For the most accessible user experience, ensure that each page in your application has a unique and descriptive title. ## Linting @@ -41,6 +41,8 @@ export const config = { ## Accessibility Resources +- [WebAIM WCAG checklist](https://webaim.org/standards/wcag/checklist) +- [WCAG 2.1 Guidelines](https://www.w3.org/TR/WCAG21/) +- [The A11y Project](https://www.a11yproject.com/) - Check [color contrast ratios](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast) between foreground and background elements - Use [`prefers-reduced-motion`](https://web.dev/prefers-reduced-motion/) when working with animations -- TODO add more pls