Skip to content

Commit

Permalink
docs: add initial accessibility guide intro (#360)
Browse files Browse the repository at this point in the history
* docs: add initial accessibility guide section

* docs: add initial outline of a11y guides

* docs: make a11y guide outline show up on builds

* docs: add accessible content copy

* docs: revised accessible content guide

* chore: use the same heading as the principle

* chore: expand on internals vs. externals for clarity

* chore: final intro edits

* chore: defer a11y guides for later

* chore: get the stream direction right

* chore: add notice about future guides
  • Loading branch information
sh0ji authored Dec 13, 2024
1 parent 17fd382 commit e154c41
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 0 deletions.
78 changes: 78 additions & 0 deletions website/docs/guides/accessibility/00-index.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
title: Introduction
slug: /guides/accessibility
---

Accessibility—the practice of ensuring that products and environments work for people with disabilities—was one of the original reasons we created a design system and is still central to our design and development process.

But simply **using the Norton Design System will not guarantee that an application or its content will be accessible**.
In fact, a significant portion of an accessible user experience depends on factors that the Norton Design System either cannot or should not control.
In general, these include how the application composes design system foundations and components together, and the accessibility of the content itself.

These guides will help fill in some of those gaps, guiding us to build more accessible applications and content.

:::caution More to come
We're planning to add additional standalone topic-based guides soon so watch here for updates!
:::

## Guiding principles

The Norton Design System team follows a few simple principles to help guide our accessibility practices.

1. Build for accessibility first
1. Provide guarantees about our internals
1. Make the right thing the easy thing

### Build for accessibility first

Everything that the Norton Design System ships uses accessibility not only to define requirements, but to guide our designs and implementations.
To do this, we start with the most familiar, vetted standards for UI like operating system patterns, [the HTML specification](https://html.spec.whatwg.org/), and the [ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/) ([we have even contributed this](https://www.w3.org/WAI/ARIA/apg/about/acknowledgements/#participantsactiveintheariaauthoringpracticestaskforce)!).
These standards form the foundations of accessible UI, so we use their guidance, semantics, and models wherever possible to best ensure a familiar experience.

And of course, we measure our success against the latest version of the [Web Content Accessibility Guidelines](https://www.w3.org/WAI/standards-guidelines/) (WCAG).

### Provide guarantees about our internals

While the Norton Design System only plays one part in creating an accessible user experience of Norton products, the part we play has an enormous downstream impact.
A small mistake in a design system component could result in serious problems for users in Norton products.
For this reason, we guarantee that we will prioritize accessibility across the internals of our components and foundations, and will fix issues found inside the design system.

:::note Internal vs. External
We often refer to design system "internals" as opposed to things that are "external" to the design system.
This is a way of delineating boundaries between the design system and the applications that use the design system, helping us to understand where responsibility lies.

For instance, the semantics of our [Button](/docs/components/button)—its HTML markup—are _internal_ to the design system because we define it.
For example, our default `<Button>` will always render as a `<button type="button">`.
We allow the `type` to be overridden since we consider that logic that belongs to the application, but the HTML element cannot be since we consider it to belong to the design system.
This means it would be impossible to use our `<Button>` and get a `<div role="button" tabindex="0">`, for instance.

But we can't guarantee how our button is used since that is inherently _external_ to the design system.
For instance, there is nothing stopping a design system user from using our button to navigate between pages.
We advise against this since using a [Link](/docs/components/link) is the best way to make navigation accessible, but we can't and won't prevent it.
:::

Of course, a significant portion of an accessible user experience happens _external_ to the design system's components and foundations, where we cannot provide guarantees.
For those, we do our best to provide guardrails, guidelines, and help our users safely break the rules.

### Make the right thing the easy thing

We believe that application and content authors know best how their application should behave and how their content should be composed.
This includes behavior for people using assistive technology like screen readers or voice control software.

But accessibility can be hard and it's easy to make mistakes or oversights, so to address this tension, we provide guardrails and reasonable defaults to help **make the right thing the easy thing**.

This also means that application and content authors can use the design system in ways that aren't accessible, either accidentally or due to a misunderstanding about accessible design and development.
Since we know that our application and content authors want to make accessible products, we've created these accessibility guides to help cover the areas of accessibility that our components, foundations, and patterns don't or can't cover.

:::note Enforced accessibility vs. Reasonable defaults
Whenever possible, the Norton Design System will enforce accessibility requirements within its React implementation, but these instances are surprisingly rare.
Most often, we provide what is often called "reasonable defaults": default values that can be changed if necessary, but will work for most cases out of the box.

Here are a couple real examples of this contrasting approach.

- **Enforced**: when a [modal dialog](https://wwnorton.github.io/design-system/docs/components/modal) is opened, focus moves into it and stays within it until it is closed.
There is no way to customize this with the design system because it is a fundamental requirement of modal dialogs.
- **Reasonable default**: [tooltips](https://wwnorton.github.io/design-system/docs/components/tooltip) have a `trigger` prop that controls when the tooltip is opened and defaults to `focus pointerenter`.
This causes the tooltip to appear when users focus the tooltipped element (either with a mouse or a keyboard), or when they hover over it with [all pointers](https://developer.mozilla.org/en-US/docs/Web/API/PointerEvent/pointerType) (mouse, stylus, finger)&mdash;a reasonable assumption for the default behavior.
But if an application author wants to explicitly require another action to open the tooltip such as on click, they can customize this.
:::
3 changes: 3 additions & 0 deletions website/docs/guides/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,9 @@ import { Features, FeatureCard, } from '@website/components';
Guides are a focused and directed way to help you get the most out of the Norton Design System.

<Features basePath="/docs/guides/" columns={2}>
<FeatureCard title='Accessibility' icon={{ d: 'M20.5 6c-2.61.7-5.67 1-8.5 1s-5.89-.3-8.5-1L3 8c1.86.5 4 .83 6 1v13h2v-6h2v6h2V9c2-.17 4.14-.5 6-1l-.5-2zM12 6c1.1 0 2-.9 2-2s-.9-2-2-2-2 .9-2 2 .9 2 2 2z' }} slug='accessibility'>
How to build accessible experiences with the Norton Design System.
</FeatureCard>
<FeatureCard title='Development' icon={{ d: 'M9.4 16.6L4.8 12l4.6-4.6L8 6l-6 6 6 6 1.4-1.4zm5.2 0l4.6-4.6-4.6-4.6L16 6l6 6-6 6-1.4-1.4z' }} slug='dev'>
How to write code with the Norton Design System.
</FeatureCard>
Expand Down
11 changes: 11 additions & 0 deletions website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,17 @@ const sidebars = {
// 'migration',
],
},
{
type: "category",
label: "Accessibility",
collapsed: true,
items: [
{
type: "autogenerated",
dirName: "guides/accessibility",
},
],
},
"guides/usable-writing-guidelines",
],
foundations: [
Expand Down

0 comments on commit e154c41

Please sign in to comment.