Explore our accessibility checklist, testing strategies and considerations. Contact accessibility@washpost.com with any questions, ideas or feedback.


---

The following checklist is derived from the much more detailed [WCAG guidelines](https://www.w3.org/WAI/WCAG21/quickref/). This does not cover every possible accessibility issue but aims to cover the most prominent varieties. It&rsquo;s meant to be an entry-level guide. For help with any part of the guide, or to request an addition to any of our docs, contact accessibility@washpost.com. We can also share copies of this checklist as .md files upon request.

**Important: Repeat all steps below on all screen sizes (mobile, tablet, desktop) to better evaluate accessibility across devices.**

**Many of the checklist items link out to more detailed instructions from [our accessibility docs](/resources/accessibility/) on how to test.**

We provide a [5-minute video tutorial](/resources/tutorials/five-minute-accessibility-audit) going through a portion of the checklist.

Thanks for incorporating accessibility considerations into your work!

<br />
## 1. Screen reader & keyboard controls

It might seem complicated, but this testing often takes only a minute or two! Use the links below and reach out with any questions.

- **Navigate content with keyboard only**<br />
  Press the `tab` key ([setup needed if using Firefox and Safari](/resources/accessibility/keyboard-accessibility#Setup)) and `shift` + `tab` to cycle forward and backward through
  the buttons, links, hoverable elements and any others the user should
  be able to interact with, ensuring (a) they each receive [appropriate focus
  styles](/resources/accessibility/keyboard-accessibility#Focus%20rings) and (b) they are clickable with the enter key (links and buttons)
  and/or space key (buttons). Each time you press `tab`, you should see
  something change on the page. If not, there is a missing focus style or tab
  index issue. See the [full list of keyboard controls](/resources/accessibility/keyboard-accessibility#How%20to%20navigate%20with%20a%20keyboard%20only) for details on other behavior, like what arrow keys and escape should do.

- **Test with screen reader linearly**<br />
  Using a screen reader ([guidance on using screen readers](/resources/accessibility/screen-readers)), navigate the
  page from top to bottom. You can click with your mouse to position the screen reader, which is helpful for testing specific parts of a page. Ensure all visible text is read aloud with correct pronunciation and in a sensible
  order.

- **Test with screen reader rotor**<br />
  Open [the screen reader rotor](/resources/accessibility/screen-readers#Using%20the%20VoiceOver%20rotor) (`caps lock` + `U` with VoiceOver)
  and ensure all links, buttons and other elements have appropriate names. Interactive
  elements [should not have generic names like "click here."](/resources/accessibility/semantic-html#Hyperlink%20text%20guidelines) You should be able
  to understand what each link or button does from the rotor menu without other
  context from the page.

- **Confirm heading order is correct**<br />
  Check the page headers using a screen reader. Does the heading order make
  sense? There should be only one `h1`, the page title. From there, headings
  should be [ordered strictly by page hierarchy](/resources/accessibility/semantic-html#Heading%20order%20and%20page%20landmarks)
  (don't jump from `h2` to `h4`, don't use `h2` as a subhead of an `h3`, etc.).

- **Confirm page landmarks are present and have correct content**<br />
  Are the [base page landmarks](/resources/accessibility/semantic-html#Page%20landmarks) (`main`, `nav`, `header`, `footer`) present? If there is complementary page content like a sidebar or right rail, is it in an `aside` tag? Are the landmarks accessible with a screen reader? They should contain the right content to help screen readers scan the page quickly.

---

## 2. Multimedia

- **Ensure all images have alt text**<br />
  Follow the [guidance for writing alt text](/resources/accessibility/alt-text).
  If an image is purely decorative, make sure it still has `alt` or `alt=""`
  present in the HTML. Similarly, videos and gifs should have text descriptions
  for screen reader users.

- **Test with reduced motion settings turned on**<br />
  Turn on [reduced motion](/resources/accessibility/audio-and-video#Animations%20and%20reduced%20motion), and ensure all non-essential animation and other moving content is eliminated upon page refresh. If not, then you should use [the prefers-reduced-motion media query](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) to modify behavior accordingly.

- **Hide useless content from screen readers**<br />
  Just as you would put alt="" for purely decorative images to hide them from
  screen readers, you should add [aria-hidden="true"](/resources/accessibility/semantic-html#Hiding%20content%20from%20screen%20readers)
  for content on the page that is not screen reader friendly. An example might be an election map full of svgs and labels, etc. You can include
  [a table version](/resources/accessibility/semantic-html#Tables) of the data or some
  other alternative for accessibility, and then hide the map with aria-hidden.

- **Avoid auto-playing audio and video**<br />
  Never auto-play audio. Auto-playing video, animations and other graphics (including gifs) are strongly discouraged. Ensure all
  audio and video instances have an accessible [pause, stop or hide button](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html).

- **Eliminate rapidly flashing content**<br />
  Videos, gifs and animations must not include any instances of flashing or blinking
  more than 3 times within any one second, as this is a seizure risk.

- **Provide captions and transcripts**<br />
  Anywhere there is audio, there should be a [transcript](/resources/accessibility/audio-and-video#Transcripts%20guidance) provided. Videos with audio should include [captions](/resources/accessibility/audio-and-video#Captions) in addition to transcripts.
  Both should include words spoken AND any other meaningful sounds from the
  audio (such as a sigh or laugh in conversation, or the chopping of a knife
  in cooking) as well.

---

## 3. Text, labels & zoom settings

- **Ensure text is readable and in plain language**<br />
  Text should be [no smaller than 12px](/resources/accessibility/text-size-and-zoom#Text%20size) and written in [plain language](/resources/accessibility/plain-language-and-labeling)
  wherever possible. Is there any jargon or use of idioms? These should be avoided.

- **Ensure text decoration is not needed to understand meaning**<br />
  Do you use underlined text (<u>example</u>) or struck-through text (~~example~~)? Text decorations like these are often not recognized by screen readers and are often confusing to other users, too, so they are generally not recommended. If you do use text decoration to convey meaning, then you must also provide [other ways for users to understand the meaning of decorated text](/resources/accessibility/plain-language-and-labeling#Text%20decoration).

- **Ensure non-English content is labeled as such**<br />
  Content in non-English languages, such as Arabic or Spanish, must have the
  lang="CODE" attribute set, where CODE is the language code e.g. &ldquo;ar&rdquo; for Arabic
  or &ldquo;es&rdquo; for Spanish. There&rsquo;s a [list of language codes](https://www.w3schools.com/tags/ref_language_codes.asp).
  This is essential [for non-English text to be read correctly by screen readers](/resources/accessibility/semantic-html#Non-English%20language%20support).
  Additionally, Arabic and some other languages are read right-to-left. In those cases, we need to set an additional attribute in the HTML, `dir="rtl`.

- **Clearly label interactive content**<br />
  Meaning of icons, buttons and other elements should be [explicitly conveyed
  via text](/resources/accessibility/plain-language-and-labeling#Icons,%20emojis%20and%20ASCII%20art) whenever possible. In all cases, interactive elements should have
  appropriate [aria-labels](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label). See our [guidance on labeling for screen reader users](/resources/accessibility/semantic-html#Labeling%20interactive%20elements). Avoid user prompts or notices that disappear automatically. If the content
  includes a form, make sure that clear prompts and error messages are provided. See our
  [guidance on forms](/resources/accessibility/plain-language-and-labeling#Forms%20and%20user%20input).

- **Change page zoom level and browser zoom settings**<br />
  Set [page zoom](/resources/accessibility/text-size-and-zoom#Page%20zoom) to 200% (on a Mac, press `command +` to zoom in). Does text scale
  correctly? Is it still readable (no overflow, overlap, etc.)? Then, Restore the page zoom to 100% and [increase the font size in your browser settings](/resources/accessibility/text-size-and-zoom#Scaling)
  to 200%. Does text scale correctly? Is it still readable?

---

## 4. Color

- **Confirm white text is never on a pure black background**<br />
  White text on a pure black background causes a [fuzziness known as halation](https://medium.com/@h_locke/why-dark-mode-causes-more-accessibility-issues-than-it-solves-d2f8359bb46a)
  for many users with astigmatism. See [our guidance for avoiding halation](/resources/accessibility/color#Avoid%20white%20text%20on%20black%20backgrounds).

- **Confirm black text is never on a pure white background**<br />
  Black text on a pure white background causes [eye strain among
  many users](https://uxmovement.com/content/why-you-should-never-use-pure-black-for-text-or-backgrounds/). See [our guidance for avoiding eye strain](/resources/accessibility/color#Avoid%20black%20text%20on%20white%20backgrounds).

- **Ensure color contrast meets the WCAG AA standard**<br />
  All color combinations, especially for text and interactive elements, must
  meet at least the AA (preferably AAA) [color contrast](/resources/accessibility/color)
  standard [using the WebAIM tool](https://webaim.org/resources/contrastchecker/).

- **Check contrast for common forms of colorblindness**<br />
  Ensure color combinations meet the AA color contrast standard for [colorblind
  users](/resources/accessibility/color#David%20Nichols'%20coloring%20for%20colorblindness%20tool) among at least the
  three most common forms of colorblindness.

- **View the page in dark and light mode**<br />
  [Dark mode and light mode](/resources/accessibility/color#Dark%20mode%20vs.%20light%20mode%20settings)
  should both be supported. Does the page change to light or dark mode automatically
  per browser settings? Does the page pass color contrast thresholds in both
  modes? And does everything change color correctly upon toggling to light or
  dark? Are all links, buttons, fonts, etc. on the page still visible?

---

## 5. Automated testing (will not catch most issues)

If you are a developer, read [our documentation on automated testing](/resources/accessibility/automated-testing) for info about adding automated checks to your code.

- **Run the WAVE tests**<br />
  Install the [WAVE Chrome extension](https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh?hl=en-US)
  and then use it on the page ([guide to using WAVE](</resources/accessibility/automated-testing#WAVE%20Evaluation%20Tool%20(Google%20Chrome%20extension)>)). The tool is great for beginners, as it allows you to learn about different types of issues by clicking interactive labels that appear on the page.
  Fix any issues that are flagged.

- **Run the axe DevTools tests**<br />
  Install the [axe DevTools Chrome Extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US) and then use it on the page ([guide to using axe DevTools](</resources/accessibility/automated-testing#axe%20DevTools%20(Google%20Chrome%20extension)>)). Fix any issues that are flagged.


Overview of considerations, not comprehensive

Accessibility Checklist

Describing images for blind and low-vision users

Alt text


---

## Audio

### Auto-play

Never auto-play audio.

### Pause, stop or hide button

All audio should have an accessible [pause, stop or hide button](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html) so that users can turn the audio off as needed.

### Transcripts

See [our transcripts section](#Transcripts%20guidance).

---

## Video (including gifs and animations)

### Avoid flashing content

Content that flashes can trigger seizures or other adverse effects for some users.

Nothing should flash on the screen more than 3 times within a single second. In general, flashing content should be avoided entirely.

### Avoid auto-play

Auto-playing video content in any situation is strongly discouraged.

### Pause, stop or hide button

All videos, gifs or animations should have an accessible [pause, stop or hide button](https://www.w3.org/WAI/WCAG21/Understanding/pause-stop-hide.html).

### Captions

Any time a video includes audio, there should also be captions provided. These should include words spoken AND any other meaningful sounds from the audio (such as a sigh or laugh in conversation, or the chopping of a knife in cooking) as well.

Closed captions are preferable so that users can turn them on or off per their preferences.

Ensure captions have appropriate color contrast with the video (rendering captions as white text on a dark gray background is common), and keep the captions in sentence case. Avoid kinetic captions, which are captions with "fun" effects like changing text size and location, which make them harder to read and thus less accessible.

Below is an example of how captions should look on a video.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/closed-captions-example.png"
      alt="Screenshot of a Washington Post video shows captions typed in white text on a dark gray background at the bottom center of the screen."
    />
  </Box>
</Container>
<br />

### Transcripts

See [our transcripts section](#Transcripts%20guidance).

### Video descriptions

Don't rely on video alone to convey important information. Video descriptions should be provided in text so that blind and low-vision users understand what the video shows.

---

## Transcripts guidance

Anytime there is audio or a video including audio, there should also be a transcript provided. These should include words spoken AND any other meaningful sounds from the audio (such as a sigh or laugh in conversation, or the chopping of a knife in cooking) as well.

Transcripts should be prominently placed near the audio or video they transcribe. Don't hide transcripts behind other menus.

Below is a good example of prominent transcript placement.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/transcript-placement-example.png"
      alt="Screenshot of a Washington Post podcast page shows 'See the transcript' button listed right below the audio player."
    />
  </Box>
</Container>
<br />

Timestamps are usually not necessary and can make transcripts unnecessarily cluttered.

Speaker names should be provided whenever there is more than one speaker in a video or audio. See the example below.

**Always confirm transcript accuracy manually when using automated transcribers.**

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/transcript-example.png"
      alt="Screenshot of a Washington Post podcast transcript shows the text from the podcast along with laebls of who is speaking and other context."
    />
  </Box>
</Container>
<br />

---

## Animations and reduced motion

Some users, including those with vestibular motion disorders, may have system settings to reduce motion in the web content.

For instance, on a Mac, there is a "Reduce motion" toggle in the System Settings under Accessibility/Display:

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={706}
      height={616}
      src="/images/reduce-motion-example.png"
      alt="Screenshot of Mac System Settings menu showing the reduce motion toggle is turned on."
    />
  </Box>
</Container>
<br />

We have to write code that recognizes these system settings in order to adjust motion accordingly.

To do this, we use the [prefers-reduced-motion CSS media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion), as documented by MDN.

Our [Tooltip component](/components/tooltip) uses `prefers-reduced-motion` to decide whether to include an animation when tooltip content is opened. If the user does not have reduced motion settings turned on, then the animation is used.

We built a shortcut media query `"@reducedMotion"` for use in our WPDS components. It does the same thing as `@media (prefers-reduced-motion)`.

Below is an example of how this looks in practice. The code is from our Carousel component. Note the animation is eliminated when the user prefers reduced motion:

```jsx
const Slider = styled("div", {
  display: "flex",
  transition: `transform 0.5s ${theme.transitions.inOut}`,
  "@reducedMotion": {
    transition: "none", // animation eliminated when user prefers reduced motion
  },
});
```


Captions, transcripts, controls, avoiding auto-play

Audio and Video


---

## Intro

Automated testing is generally believed to catch around 30-50 percent of accessibility issues on a page. They are a useful tool in achieving accessibility, but they are not sufficient for full testing. Below are some automated testing tools that we use at The Post.

---

## WAVE Evaluation Tool (Google Chrome extension)

WebAIM's [WAVE Evaluation Tool extension](https://chrome.google.com/webstore/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh?hl=en-US) provides an interactive testing suite that is a good starting point for automated accessibility testing. There is [a video guide to using WAVE](https://www.youtube.com/watch?v=ITUDiTgAZY0), but we'll go over the basics here as well.

After installing, select the puzzle piece icon in the top right of the Chrome browser and select the tool from the dropdown, as shown below.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/wave-step-one.png"
      alt="Screenshot shows The Washington Post homepage with the Chrome browser extensions menu open in the top right corner of the browser. The WAVE Evaluation Tool is highlighted in the menu as the user has it in focus."
    />
  </Box>
</Container>
<br />

Selecting the tool will open a menu if errors, alerts and other notices on the page. The interactive visual experience makes WAVE helpful for beginners.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/wave-step-two.png"
      alt="Screenshot shows The Washington Post homepage with the The WAVE Evaluation Tool menu open on the left side of the screen. The menu lists a summary of errors, alerts and other notices on the page, and the homepage itself has colorful icons sprinkled throughout it to show where the tool's audit flagged things that can be viewed in more detail."
    />
  </Box>
</Container>
<br />

Click on the icons that appear throughout the page to understand what each is signaling.

**WAVE should always be used alongside the axe DevTools described below. Don't rely on only one tool or the either. Use both.**

---

## axe DevTools (Google Chrome extension)

Install the [axe DevTools extension](https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US). There is [a video guide to using the axe DevTools](https://www.youtube.com/watch?v=iRGB40c_YJc&t=36s), but we'll go over the basics here as well.

To test a page with the axe DevTools, open the developer tools in Chrome and select axe DevTools in the console dropdown, as shown below.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/axe-dev-tools-step-one.png"
      alt="Screenshot shows the Chrome dev tools menu open to the right of The Washington Post homepage. In the Chrome dev tools' 'More tabs' dropdown menu, the axe DevTools extension is highlighted as the user has it in focus."
    />
  </Box>
</Container>
<br />

Once in the axe DevTools menu, you can select "scan ALL of my page."

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/axe-dev-tools-step-two.png"
      alt="Screenshot shows the axe DevTools menu open to the right of The Post's homepage. In the axe DevTools menu, 'Scan ALL of my page' is highlighted as the user has it in focus."
    />
  </Box>
</Container>
<br />

Finally, you will receive a list of errors on the page that you can expand to view. You can even see where in the page HTML the error occurs. This is very useful for catching and fixing issues.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/axe-dev-tools-step-three.png"
      alt="Screenshot shows the axe DevTools menu open to the right of The Post's homepage. In the axe DevTools menu, the results of full page scan are shown. A total of 45 issues were flagged, and the details of the first issue are expanded below the total."
    />
  </Box>
</Container>
<br />

---

## axe-core testing library

In addition to the Chrome extension, the axe testing suite is available in [a set of npm packages](https://github.com/dequelabs/axe-core-npm) so that you can configure the tests to run automatically.

Each package has more details in its README on how the package is used.

We also recommend [jext-axe](https://github.com/nickcolley/jest-axe) for unit testing, though it is not part of the axe-core library.

---

## Linting with jsx-a11y

Pair the axe-core npm packages with the [eslint-plugin-jsx-a11y npm package](https://www.npmjs.com/package/eslint-plugin-jsx-a11y) to improve your automated testing.

Per the package's developers: "This plugin does a static evaluation of the JSX to spot accessibility issues in React apps. Because it only catches errors in static code, use it in combination with [@axe-core/react](https://github.com/dequelabs/axe-core-npm/tree/develop/packages/react) to test the accessibility of the rendered DOM. Consider these tools just as one step of a larger a11y testing process and always test your apps with assistive technology."

The jsx-a11y developers provide [a list of everything covered by jsx-a11y's automated checks](https://www.npmjs.com/package/eslint-plugin-jsx-a11y#user-content-supported-rules).

---

## Storybook automated tests

Storybook is a valuable tool for viewing your components in isolation and conducting testing.

We recommend reading [the Storybook accessibility docs](https://storybook.js.org/docs/react/writing-tests/accessibility-testing) for more information.


Useful for catching some (but not all) issues

Automated testing tools


---

## Motivations

Low color contrast can make text and other page elements harder to see for everyone, especially users with disabilities and many older users. One common form of disability is colorblindness, but there are many forms of color blindness with different effects on perception of color.

When working with meaningful content such as text, visuals and user inputs, it is important to ensure users can easily distinguish between elements.

There are additional considerations we must make to avoid eye strain and a blurred effect known as halation for some users.

---

## Color contrast standards

The Post's [accessibility statement](https://www.washingtonpost.com/accessibility/) notes that we are guided by the [WCAG 2.1 Level AA standard](https://www.w3.org/WAI/WCAG21/quickref/?showtechniques=143). However, we strongly encourage meeting the [level AAA standard](https://www.w3.org/WAI/WCAG21/quickref/?showtechniques=143%2C146) whenever possible.

Since 2021, WPDS has provided [a library of grayscale and color tokens](/foundations/color) designed with adherence to WCAG's AA standard in mind. Within our token library, there is a theme token labeled `accessible`, which maps to hex value `#666666` in light mode and `#858585` in dark mode. The contrast ratio is 5.7 when the `accessible` color is used in light mode on a pure white (`#FFFFFF`) background and in dark mode on a pure black (`#000000`) background.

To ensure acceptable color contrast when using other color tokens, you will need to test manually.

---

## Testing color contrast, including for colorblind users

Use the below tools in conjunction with each other to ensure colors meet contrast standards for both colorblind and non-colorblind users. You should also use the tools to test your selected colors in both light mode and dark mode whenever both are offered.

### WebAIM Color Contrast Checker

The [WebAIM Color Contrast Checker](https://webaim.org/resources/contrastchecker/) evaluates colors for WCAG compliance. You enter the hex values for the foreground and background colors, and the site calculates the contrast ratio. It rates the colors with a &ldquo;Pass&rdquo; or &ldquo;Fail&rdquo; rating. You can use the slider under each color to lighten or darken it until a &ldquo;Pass&rdquo; rating is attained. The hex code will update accordingly.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/webaim-contrast-checker.png"
      alt="Screenshot of the WebAIM Color Contrast Checker shows #AE726A &mdash; a shade of brown &mdash; selected as the foreground color, and #FFFFFF &mdash; pure white &mdash; selected as the background color. The contrast ratio is listed below as 3.87:1. Below that, examples of the color combo are shown for normal text, large text and graphical objects and user interface components, along with notes on whether the selected color combo passes WCAG AA and/or AAA standards in each scenario."
    />
  </Box>
</Container>
<br />

### Adobe Color Contrast Checker

The [Adobe Color Contrast Checker](https://color.adobe.com/create/color-contrast-analyzer) has a different UI than the WebAIM tool, so try both to see which better fits your needs.

### David Nichols' coloring for colorblindness tool

The [coloring for colorblindness tool](https://davidmathlogic.com/colorblind/#%23D81B60-%231E88E5-%23FFC107-%23004D40) allows you to input a color palette and see how that palette appears to users with different forms of colorblindness.

You can inspect the resulting colors in your browser to collect their hex codes and independently [verify they have enough contrast with each other](#WebAIM%20Color%20Contrast%20Checker).

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/coloring-for-colorblindness.png"
      alt="Screenshot of the coloring for colorblindness tool shows a color palette of red, light blue, mustard yellow and dark green squares stacked. Three stacks of squares to the right of it show the colors' different appearances to people with three forms of colorblindness: protanopia, deuteranopia and tritanopia."
    />
  </Box>
</Container>
<br />

### Adobe Color Blind Safe tool

The [Adobe Color Blind Safe tool](https://color.adobe.com/create/color-accessibility) has a different UI than David Nichols' tool, so try both to see which better fits your needs.

One advantage of the Adobe tool is that it has a built-in warning when colors are deemed to conflict for at at least one form of color blindness. Learn more on [Adobe's webpage about its tools](https://helpx.adobe.com/creative-cloud/adobe-color-accessibility-tools.html).

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/adobe-color-blind-safe.png"
      alt="Screenshot of the Adobe Color Blind Safe tool shows that two of the colors the user selected are in conflict for the color blindness known as Protanopia. The Adobe tool looks similar to the WebAIM one, but the palette is oriented sideways, and the colorblindness versions are stacked below it. There is also a color wheel with markers on it for each color in the palette."
    />
  </Box>
</Container>
<br />

---

## Avoiding eye strain and halation

While you may be tempted to use black text on a white background&nbsp;&mdash; and vice versa &mdash; for maximum color contrast, these combinations raise other issues.

Within [our color tokens library](/foundations/color), there is a theme token labeled `accessible`, which maps to hex value `#666666` in light mode and `#858585` in dark mode. The contrast ratio is 5.7 when the `accessible` color is used in light mode on a pure white (`#FFFFFF`) background and in dark mode on a pure black (`#000000`) background.

### Avoid white text on black backgrounds

Never use white (`#FFFFFF`) text on a black (`#000000`) background (in any circumstance, but be especially weary of this in dark mode). This causes [a fuzziness effect known as halation](https://medium.com/@h_locke/why-dark-mode-causes-more-accessibility-issues-than-it-solves-d2f8359bb46a) for many readers with astigmatism, and it makes reading difficult.

You can use light gray text instead of white, and/or a dark gray background instead of black, to avoid this issue.

View [our color tokens library](/foundations/color) &mdash; including the `accessible` token mentioned above &mdash; for more info.

### Avoid black text on white backgrounds

Never use black (`#000000`) text on a white (`#FFFFFF`) background (in any circumstance, but be especially weary of this in light mode). Pure black text on a white background is [known to cause eye strain among many users](https://uxmovement.com/content/why-you-should-never-use-pure-black-for-text-or-backgrounds/).

You can use dark gray text instead of black, and/or a light gray background instead of white, to avoid this issue.

View [our color tokens library](/foundations/color) &mdash; including the `accessible` token mentioned above &mdash; for more info.

---

## Dark mode vs. light mode settings

### Light or dark, or both?

It is best practice to support both light and dark mode on all content. This includes conducting the contrast tests described above in both modes. All links, buttons, fonts, etc. on the page should be visible in both modes.

### Respecting browser settings

Many users will have dark mode configured in their browser and/or system settings. When possible, we should build responsively and default to light or dark mode based on user settings without them having to manually click a toggle on our page.

A good way to respond to user settings is [the prefers-color-scheme CSS media feature](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme), as documented by MDN.

---

## Avoiding color coding

Even if you have fully accounted for contrast, colorblindness and compatibility with various user settings like dark mode, you should never rely purely on color coding to convey information to users.

Screen reader users will always need text explanations of content. Others have their devices set to grayscale, so colors are mostly indistinguishable. Furthermore, colors may also have different cultural meanings across users, leading to confusion over the selection of colors and what it all means.

Save yourself and your users the trouble by using text to convey the meaning of anything that you're tempted to convey via color.


Contrast, colorblindness, light and dark mode standards

Color


---

## Setup

Some browsers require setup for keyboard navigation to work as expected.

- In Safari, the `tab` key does not exhibit the behavior described below by default. You can press `option` and `tab` at the same time instead, or go into your Safari preferences and turn on &ldquo;Press Tab to highlight each item on a webpage&rdquo; in the "Advanced" pane of the preferences menu.
- In Firefox for MacOS, you may need to toggle the following setting on before using keyboard navigation: Apple > System Settings > Keyboard > Keyboard navigation.

---

## Keyboard focus

Some people use the keyboard (or another controller mapped to keyboard keys) instead of a mouse in order to navigate page content.

For a user to know that they can "click" an element with their keyboard (including elements that would exhibit some behavior upon mouse hover), that element must be focusable.

To be focusable means the element can be selected individually via keyboard controls. Try opening one of our pages in Google Chrome, and repeatedly press the `tab` key on your keyboard. You will notice that certain elements (but not every element) become highlighted or get a ring around them as you keep pressing `tab`. The `tab` key is just one of many [keyboard controls](#How%20to%20navigate%20with%20a%20keyboard%20only) available to users.

---

## Focus rings

Keyboard users need a visual cue that a clickable or hover-able element (whether it is a button, div, link or something else entirely) is in focus as they navigate the page. This lets them know when they can click something and what it is, since they are not using a visible mouse.

The only elements that should be highlighted or have a ring around them during keyboard navigation are the ones that are interactive. All links and buttons should be focusable, but a paragraph of plaintext without any links in it should not be focusable.

We have a `className="focus-highlight"` [Site Components Tachyon](https://build.washingtonpost.com/tachyons/search) for adding the visual cue to focusable elements.

If the CSS or component logic specifies that something should happen when an element is hovered or clicked with the mouse, then that same functionality (or an accessible version) should be achievable via pressing one or more keys on the keyboard.

```jsx
<div
  role="button"
  onClick={someFunction} // allows user to achieve function by clicking div
  onKeyDown={someFunction} // allows user to achieve same function via keyboard key
  tabIndex={0} // makes the div keyboard focus-able (divs by default are not)
  className="focus-highlight" // applies highlight to div when it is focused
>
  Functional div
</div>
```

You may be in a hurry to implement some function on a div and only add the `onClick` event. This makes the element impossible to use with the keyboard. So don't forget `onKeyDown`. Note that `onKeyPress` is deprecated. There is a [blog post describing why onKeyDown is best](https://www.mutuallyhuman.com/blog/keydown-is-the-only-keyboard-event-we-need/).

If you are working with an element that is non-focusable by default (like a div), then you will need to make sure the element is focusable by adding two things:

(a) `tabIndex={0}` to make the element tab-focusable

(c) `role="button"` so that screen readers let users know that it can be clicked

Elements like links and buttons should be focusable by default, but make sure to always verify since people may accidentally disable this functionality without even knowing it.

---

## How to navigate with a keyboard only

Try out the following to get a better sense for how people navigate web content without a mouse. Make sure to follow [the setup instructions](#Setup) first if using Firefox or Safari. Note the different controls for different types of interactive elements. Buttons are clickable via either space or enter, whereas links are only clickable via enter.

- **Tab:** Next focusable element
- **Shift Tab:** Previous focusable element
- **Enter:** "Click" currently focused link or button
- **Space:** Scroll down the page or &mdash; if applicable &mdash; "click" currently focused button (includes toggling a checkbox or radio button)
- **Up/Down arrows:** Scroll up/down the page or &mdash; if applicable &mdash; move between radio buttons and, in some cases, menu links
- **Right/Left arrows:** Adjust sliders in audio and video players or, in some cases, move between menu links
- **Escape:** Close an element that has appeared dynamically, such as a popup menu or dialog. After the dynamic element closes, focus should return to where it was before the element was opened.

---

## Limiting keyboard events to specific keys

In almost all cases, you don't want just any key on the keyboard triggering the event you added via `onKeyDown`.

At The Post, we have gotten around this by using `onKeyDown` wrapper functions like the examples below:

```jsx
/**
 * Wraps specified function with button keyboard logic
 * i.e. only "Enter" or " " (the spacebar/space key)
 * keydowns will trigger the function
 *
 * @param {object} e The keyboard event
 * @param {function} fn The function to be wrapped
 * @returns {object} The wrapped function
 */
export function keyDownButtonWrapper(e, fn) {
  if (e.key === "Enter" || e.key === " ") {
    e.preventDefault(); // space scrolls page by default
    fn();
  }
}

/**
 * Wraps specified function with link keyboard logic
 * i.e. only "Enter" keydowns will trigger the function
 *
 * @param {object} e The keyboard event
 * @param {function} fn The function to be wrapped
 * @returns {object} The wrapped function
 */
export function keyDownLinkWrapper(e, fn) {
  if (e.key === "Enter") fn();
}
```

<br />
When incorporated into a div with an `onKeyDown` function, which was the first example
on this page, the resulting code looks like the following:

```jsx
<div
  role="button"
  onClick={someFunction}
  onKeyDown={(e) => keyDownButtonWrapper(e, () => someFunction())}
  tabIndex={0}
  className="focus-highlight"
>
  Functional div
</div>
```

<br />

---

## Skip to main content

It is The Post's practice to include a "skip to main content" link in the header nav of all pages on our website.

This is a widely used standard to help keyboard users more efficiently navigate page content. Who wants to have to tab through the same links over and over on each page of a website?

The skip link gets around this by jumping the user to the unique page content, which we mark with the dom id `main-content` in our code.

You have to start navigating the page with your keyboard to discover this link, which is hidden to sighted users when not in keyboard focus. Open washingtonpost.com and try hitting the `tab` key on your keyboard. You will get something like the following:

<Container caption='Example of what "skip to main content" link looks like on washingtonpost.com'>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={335}
      height={216}
      src="/images/skip-link.png"
      alt="Screenshot of the top left corner of The Washington Post website shows a white underlined hyperlink called 'Skip to main content.' The link has a blue ring around it as it is currently in keyboard focus."
    />
  </Box>
</Container>
<br />

When you click this link using enter on your keyboard, you should expect to be jumped to the first clickable element in the unique page content (excluding ads, nav menus and other boilerplate that is consistent across pages).

If nothing happens, it means your page does not have a dom element with the id `main-content`. This is a bug, so remember to always confirm that one and only one dom element in your code has `id="main-content"`.


Ensuring content is navigable without a mouse

Keyboard accessibility


---

## Plain language standards

Writing in plain language makes our content more accessible to a wide variety of people, including those with cognitive disabilities, lower reading literacy and less background knowledge of the topic or concept being covered. This also matters in the design of user interfaces.

The U.S. federal government has [detailed plain language guidelines](https://www.plainlanguage.gov/guidelines/) and [a checklist](https://www.plainlanguage.gov/resources/checklists/checklist/). These are based on the [Plain Writing Act of 2010](https://www.govinfo.gov/app/details/PLAW-111publ274).

While we are an independent media organization, a lot of the guidance is relevant to us.

<br />
**In particular, we strongly recommend the following:**

- be concise
- use short sentences and clear structure
- use familiar, commonly understood words
- define any uncommon words or concepts
- avoid jargon, idioms and metaphors
- avoid excessive words and punctuation
- use the simplest tense possible
- use lists and tables to simplify complex material

---

## Icons, emojis and ASCII art

### Icons

Meaning of icons, buttons and other elements [should be labeled with visible text](https://uxdesign.cc/label-your-icons-e2bd57366d37) whenever possible. In all cases, interactive elements should have appropriate [aria-labels](/resources/accessibility/semantic-html#Labeling%20interactive%20elements) for screen reader users.

### Emojis and other symbols

Avoid relying on emojis or symbols. Emojis and other symbols may have confusing or unintended meanings, especially across generations and cultures. They are also annoying for blind and low-vision screen reader users. They should be avoided unless they are central to the content.

If you need to use emojis, consult [Unicode's emoji list](https://unicode.org/emoji/charts-13.0/full-emoji-list.html) to ensure the emojis translate well and appear as you expect across different devices and systems. They should be visible with sufficient contrast in light and dark mode.

Make sure to include visible text descriptions alongside all emojis to clarify meaning.

### ASCII art

ASCII art typed directly into a page is not accessible to screen readers.

However, screenshots of ASCII art with appropriate [alt text](/resources/accessibility/alt-text) included are okay.

Create the ASCII art on your own device and take a screenshot of the art you produced. Then you can post the screenshot and include alt text describing the ASCII art for blind and low-vision users.

When a screenshot is not an option, you can provide a text alternative of the ASCII art before it and then [include an anchor link for users to skip past the ASCII art](https://www.w3.org/TR/WCAG20-TECHS/H86.html).

---

## Text decoration

Underlines (<u>example</u>), strikethroughs (~~example~~) and other text decorations are often not recognized by screen readers and can confuse other users, too, so they are not recommended.

If you must use text decoration to convey meaning, then you must also provide other ways for users to understand the meaning of the decorated text.

For example, when using a strikethrough to visually label something as "completed" or "done," you should also include a label next to the struck-through text that explicitly says "completed" or "done."

- ~~Buy ingredients~~ (completed)
- ~~Travel home~~ (completed)
- Cook dinner

<br />
You can follow a similar approach when using underlines and strikethroughs to denote
added and removed content in an updated version of a document, perhaps one being
shown to readers as part of a news article:

The <u>new content</u> (added) in the document can thus be differentiated from the ~~old content~~ (removed) more easily.

---

## Hashtags and CamelCase

CamelCase involves capitalizing the first letter of each word in a multiple-word hashtag. This allows screen readers to distinguish words in a hashtag and increases legibility for everyone.

**For example, use #TheWashingtonPost instead of #thewashingtonpost.**

Capitalize the letters in acronyms and initials as well.

**For example, use #WPMedia instead of #Wpmedia.**

---

## Forms and user input

Clear error messages should be provided so that users know when and how to correct their input.

Similarly, avoid user prompts or notices that disappear automatically, as this creates a frustrating user experience when the user cannot access something they need in time. Label all fields clearly, and don't rely on placeholder text that disappears when a user begins filling out the field.

Don't require users to drag things around to fill out a form or complete some other task. Remember that not everyone uses a computer mouse.

WebAIM provides [more guidance on accessible forms](https://webaim.org/techniques/forms/#:~:text=Accessible%20forms%20are%20easy%20to,must%20be%20intuitive%20and%20descriptive.).


Clear and inclusive writing, navigating special characters

Plain language, symbols and forms


---

## Intro

Some people who are blind or low-vision use assistive technology known as a screen reader to hear the content on a page read aloud to them. They use controls to move between elements on a page, and the associated text and/or function is read aloud.

This is one purpose of [alt text](/resources/accessibility/alt-text); it is read by a screen reader to describe an image for those who cannot see it clearly. Similarly, interactive elements should often be labeled in code using [aria-labels](/resources/accessibility/semantic-html#Labeling%20interactive%20elements).

It is important to navigate a page manually with a screen reader while testing for accessibility. There are a number of different screen readers with their own quirks. On desktop, we strive to test with both VoiceOver and NVDA. On mobile devices, we strive to test with both VoiceOver and Talkback.

---

## VoiceOver (MacOS and iOS)

VoiceOver is a screen reader built into Apple operating systems MacOS and iOS. There is no need to do an installation. You can turn VoiceOver on via `command` + `F5` on a Mac, or in your accessibility settings on iOS devices.

### MacOS

After turning on VoiceOver, click "Learn More" to explore the controls via the quick start guide.

Apple has [detailed documentation on how to use VoiceOver](https://support.apple.com/guide/voiceover/welcome/mac), but we have highlighted some basic commands below.

#### Basic MacOS controls

**Note:** The `VO` referenced from now on is the "VoiceOver Modifier" key(s) that allow you to run VoiceOver commands. By default, `VO` is triggered via your `caps lock` key or `control` + `option`, but you can open [the VoiceOver Utility](https://support.apple.com/guide/voiceover/use-voiceover-utility-vo28017/10/mac/13.0) (`VO` + `F8`) to change it.

- **command + F5:** Turn VoiceOver on/off
- **VO:** Pause or unpause VoiceOver while it is reading content aloud
- **VO + Right/Left arrows:** Navigate to next/previous page element
- **VO + shift + Up arrow:** Move out of a child element and into [the parent area/group](https://support.apple.com/guide/voiceover/interact-with-areas-and-groups-vo24851/mac), if applicable (for example, while reading this list I can press `VO` + `shift` + `Up arrow` to exit the list entirely and return to the parent `article`, instead of having to finish the list and other article content first)
- **VO + shift + Down arrow:** Move into a child element (for example, while reading a list element like this one I can press `VO` + `shift` + `Down arrow` to interact with the individual words and characters in the text one at a time)
- **VO + A:** Begin reading all remaining page content in order from the current position
- **VO + U:** Open [the VoiceOver rotor](#Using%20the%20VoiceOver%20rotor), covered in more detail below
- **Escape:** Close the rotor or another VoiceOver menu that has been opened

<br />
All [other keyboard controls](/resources/accessibility/keyboard-accessibility#How%20to%20navigate%20with%20a%20keyboard%20only)
also work while using VoiceOver.

Again, these are not all the available commands. This is a beginner's guide.

<br />
<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/voice-over.png"
      alt="Screenshot shows the VoiceOver popup that is displayed when someone enables VoiceOver on their Mac using the keyboard shortcut."
    />
  </Box>
</Container>
<br />

#### Debugging with VoiceOver on a Mac

Use the commands outlined above to navigate a page. Make sure all text on the page is readable in a sensible order and that images have alt text. Buttons and elements that are mouse-hoverable should be labeled with [aria-labels](/resources/accessibility/semantic-html#Labeling%20interactive%20elements), and you should hear those labels read by VoiceOver.

**As a sighted user, you may find it useful to click on the page with your mouse to position VoiceOver on an element.** You can then test normally from there. This is only advisable when debugging one specific part of a page. You will also see info about the currently selected element in a little box on your screen. This is the same text that is being read to a user, so make sure the text is appropriate. This goes for alt text, labels and anything else that VoiceOver can access on the page.

Make sure to also attempt navigating the entire page with VoiceOver from start to finish. You may run into keyboard accessibility issues that are also VoiceOver issues. For instance, does the page have a skip to main content link? Is every clickable element on the page also clickable with VoiceOver?

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/voice-over-example.png"
      alt="Screenshot shows VoiceOver in use on a Washington Post article. A hyperlink on the page has a blue ring around it as it is currently in focus, and a box in the bottom left corner of the screen shows the link text that VoiceOver is reading aloud to the user."
    />
  </Box>
</Container>
<br />

### iOS

After turning on VoiceOver in your [iOS device's accessibility settings](https://support.apple.com/guide/iphone/turn-on-and-practice-voiceover-iph3e2e415f/16.0/ios/16.0), your controls will immediately change. It takes practice to get used to the VoiceOver iOS controls, so don't worry if it is confusing at first.

**Note:** We recommend turning off your iPhone's auto-lock feature, if enabled, while testing with VoiceOver. If your phone locks while in VoiceOver mode, it will stay in VoiceOver mode, and you will need to use the VoiceOver controls to unlock your phone. You can use a slow swiping up motion to open the passcode field. Click a button to select it, and then double tap to press the button and enter the value. Repeat until you've entered your full passcode.

**There are two things you should practice repeatedly when getting started with VoiceOver on iOS:**

1. Tap on something once to select it, and then &mdash; after it is selected &mdash; double tap to use it. This is how you will open apps, click buttons and perform other interactions. Try this with the VoiceOver on/off toggle in your accessibility settings to get used to it.
2. To go to your device's home screen, slowly slide one finger up your phone screen &mdash; starting at the bottom &mdash; until you feel a vibration, and then immediately lift your finger off the screen.

<br />
Test these two controls together. Turn VoiceOver on, navigate to your home screen,
and then re-open the settings app. Navigate to the VoiceOver setting and turn VoiceOver
off. Repeat the process for more practice, and then proceed to learn additional controls
below.

#### Basic iOS controls

Refer to [Apple's documentation on iOS VoiceOver controls](https://support.apple.com/guide/iphone/learn-voiceover-gestures-iph3e2e2281/16.0/ios/16.0) for more details and additional controls.

- **Single tap on an element:** Select that element. VoiceOver will read it aloud, and it will remain selected.
- **Double tap:** Activate the selected element. Try this with the VoiceOver on/off toggle in your accessibility settings to get used to it.
- **Swipe up/down with two fingers:** Read all content on the current page from top to bottom
- **Swipe up with three fingers:** Scroll down the page
- **Swipe down with three fingers:** Scroll up the page
- **Swipe right/left:** Navigate to next/previous page element (just like you would do with arrow keys on MacOS)

<br />
Again, these are not all the available controls. This is a beginner's guide.{" "}

### Using the VoiceOver rotor

VoiceOver users do not have to listen to each element on the page from top to bottom. They can jump around to different links, headings and other page elements using something called the rotor.

#### On desktop

Open the rotor using `VO + U`. (As mentioned in [the MacOS controls section](#Basic%20MacOS%20controls) above, the default `VO` key is `caps lock` or `option` + `control`.)

You can use the left and right arrow keys to filter by different types of elements. Use the up and down arrows to select a specific element, and press enter to jump to it.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/voice-over-rotor.png"
      alt="Screenshot shows the VoiceOver rotor in use on a Washington Post article. The VoiceOver box in the center of the screen shows a list of links on the page."
    />
  </Box>
</Container>

<br />

#### On mobile

Open the rotor by holding two fingers on the screen and rotating them clockwise &mdash; while maintaining pressure on the screen &mdash; like you are using a screwdriver.

Maintain the motion described above until the desired setting is selected. At that point you can swipe up or down the screen to enable the setting.

Refer to [Apple's documentation on the iOS VoiceOver rotor](https://support.apple.com/guide/iphone/control-voiceover-using-the-rotor-iph3e2e3a6d/16.0/ios/16.0) for more details.

---

## NVDA (Windows)

VoiceOver is only available on Apple devices. Users on Windows have access to different screen readers, though. One of the most common (and free-to-use) screen readers is [NVDA](https://www.nvaccess.org/download/). The [NVDA code is open source](https://github.com/nvaccess/nvda/).

Testing with NVDA on a Mac is tricky. Deque University offers [guidance on possible configurations](https://dequeuniversity.com/mac/windows-screen-readers).

---

## Talkback (Android)

The [Talkback screen reader](https://developer.android.com/guide/topics/ui/accessibility/testing#talkback) is built into Android devices. Our mobile apps team develops an Android version of The Washington Post mobile app, and they help with Talkback testing.

---

## Other screen readers

There are other screen readers like [JAWS](https://www.freedomscientific.com/products/software/jaws/) &mdash; a paid-only screen reader for Windows and MacOS &mdash; and [Narrator](https://support.microsoft.com/en-us/windows/complete-guide-to-narrator-e4397a0d-ef4f-b386-d8ae-c172f109bdb1), a free screen reader that comes built-in with Windows.

Testing with these screen readers is encouraged, when possible, but we at The Post are focused on testing with VoiceOver, NVDA and Talkback.


How to use them and why you need to do so

Screen readers


---

## Heading order and page landmarks

### Heading order motivation

Someone who is using a screen reader may jump around the headings on a page to quickly scan content. Headings have a hierarchy: A page should have only one h1 corresponding to its title, and h2s are used for major subsections, h3s are for subsections of h2s and so on.

If headings are used our of order, such as an h2 being placed below an h3 despite the h2 content being a subsection of h3, then the user may be confused. Skipping heading levels entirely, such as going from an h2 to an h4, can also cause issues.

It may be tempting to use headings out of order based on their styles, but this should not be done. You can add a class to a heading to provide extra styles, or rework your heading styles entirely because they may not make sense in the first place if you are being tempted to use headings out of order.

### Heading order solution

There must be only one h1 on any given page, as this corresponds to the page title or headline.

After that, the heading level represents the "scope" of the subsection. For instance, if you are working with an election results page showing the results of Democratic and Republican primaries in the state of Missouri, it would make sense to have the title of an individual office seat (such as governor) be an h2, while the Democratic and Republican primaries for that seat are each headed with an h3.

```jsx withPreview
export default function Example() {
  return (
    <Box
      css={{
        width: "100%",
        gap: "$100",
      }}
    >
      <h1>2020 Missouri primaries (h1)</h1>

      <h2>Governor (h2)</h2>

      <h3>Democratic primary (h3)</h3>

      <h3>Republican primary (h3)</h3>

      <h2>Attorney General (h2)</h2>

      <h3>Democratic primary (h3)</h3>

      <h3>Republican primary (h3)</h3>
    </Box>
  );
}
```

### Page landmarks

Our Washington Post article pages contain landmarks that screen reader users can quickly access via the rotor to jump around a page and hear different types of content.

We use [the following landmarks as documented by W3C](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/HTML5.html): `main`, `nav`, `aside`, `header` and `footer`. We also use [the article landmark defined by MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/article) to denote self-contained content such as an article or user-submitted comment.

In addition to the above, we can use `form` and `section` tags to define other key regions on a page, but we need to include an `aria-labelledby`, `aria-label` or `title` attribute on these elements so screen readers know what they contain.

Similarly, if the same type of landmark is used on a page multiple times (for example, two `nav`s or two `aside`s), then we should add an `aria-label` to each duplicate landmark to differentiate them.

Inspect one of our articles with the Chrome developer tools to find the landmarks. You can also open a [screen reader rotor](/resources/accessibility/screen-readers#Using%20the%20VoiceOver%20rotor) to view a list of landmarks.

The example code below demonstrates one way we can arrange landmarks on article pages. There are other possible arrangements. **Your main focus in using the landmarks should be that they contain appropriate content.** Otherwise screen reader users may be confused.

```jsx
<nav>
   <p>Header navigation links, etc.</p>
</nav>
<main>
   <header>
      <p>Article headline</p>
   </header>
   <article>
      <p>Article content</p>
   </article>
</main>
<aside>
   <p>Right rail content</p>
</aside>
<footer>
   <p>Footer navigation links</p>
</footer>
```

---

## Labeling interactive elements

Our docs address the need for alt text when a reader cannot see an image.

The `aria-label` and `aria-labelledby` conventions are for interactive elements that are not images. See [the ARIA guide](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) for more context.

### aria-label

You might use aria-label on a clickable div on a page to clarify for the user its purpose:

```jsx
<div
  aria-label="Submit form" // text that will be read aloud by screen reader
  role="button" // also read by screen reader to say div behaves like a button
  onClick={someFunction} // allows user to achieve function by clicking div
  onKeyDown={someFunction} // allows user to achieve same function via keyboard
  tabIndex={0} // makes the div keyboard focus-able (divs by default are not)
  className="focus-highlight" // applies highlight to div when it is focused
/>
```

Notice that the `aria-label` attribute is passed a string value to be read by a screen reader.

<br />

An `aria-label` can also be useful when you want to have two versions of the same text shown. For instance, in many tables on our live elections results pages we include abbreviations of certain words, such as "Unc." for "Uncontested," "Pct." for "Percent," etc.

We can use `aria-label` to write text that is only seen by screen readers, while the standard component text remains seen by non-screen-reader users.

```jsx
// Full word read by screen reader, but abbreviation seen on the visible page
<span aria-label="Uncontested">Unc.</span>
```

### aria-labelledby

You might use `aria-labelledby` to clarify for a screen reader the connection between an input field and its purpose:

```jsx
// copied from https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-labelledby_attribute
<div id="myBillingId">Billing</div>

<div>
    <div id="myNameId">Name</div>
    <input type="text" aria-labelledby="myBillingId myNameId"/>
</div>
<div>
    <div id="myAddressId">Address</div>
    <input type="text" aria-labelledby="myBillingId myAddressId"/>
</div>
```

Note that the `aria-labelledby` is passed a string containing an element id or multiple ids separated by spaces. The text content of the elements with these ids is what will be read by the screen reader so that the user understands what each input field is for (in this case, "Billing Name" and "Billing Address").

There is also an `aria-describedby` property meant to connect elements with relevant (but not essential information). This is not used as commonly, and `aria-labelledby` should be used regardless of whether a value for `aria-describedby` is also present on a given element.

---

## Hyperlink text guidelines

It is important that hyperlink text is meaningful even out of context. This is because many screen reader users jump between links on a page without hearing the text surrounding each one. Read [our screen reader guide](/resources/accessibility/screen-readers) for more info.

There are some key things to watch for when writing link text:

- Avoid using the URL as the link text.
  - URLs are often read by screen readers in a disjointed manner, and they can also be confusing and less meaningful for sighted users.
- Keep link text concise, but don't sacrifice meaning. This speeds up the process of scanning links as a user, especially as a screen reader user.
  - For example, "Subscribe" is better than "Subscribe for more content from us in the future."
- Don't include words like "link" or "click here" in your link text.
  - This is redundant. Links should be evident in their styling and structure. If you feel the need to specify "click here," then your link probably isn't styled correctly for [keyboard accessibility](/resources/accessibility/keyboard-accessibility).
- Ensure each unique link has unique link text.
  - If multiple links have different text but the same value, then users may waste their time clicking them all. This is a frustrating user experience.
  - Similarly, if multiple links have the same text but go to different sites, then users may miss out because they assumed the links were the same.

---

## Hiding content from screen readers

There are often ads on our products. When third-party ads are used, we don't have full control over their accessibility. For screen reader users, inaccessible ads hinder page navigation.

Our practice is to apply `aria-hidden="true"` on our ad wrapper elements so that they are ignored by screen readers and thus do not clutter the page. The [guide to ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) has more context.

We use `aria-hidden="true"` on non-ad content **if and only if it is useless to screen readers** (it is purely decorative or it is innaccessible content that already has a screen reader accessible alternative elsewhere on the page).

---

## Content for screen readers only

### sr-only class

Try searching "sr-only" on [our Tachyons search page](https://build.washingtonpost.com/tachyons/search). You should find the following class:

```jsx
.sr-only {/* all screens */
  clip: rect(0,0,0,0);
  border: 0;
  height: 1px;
  margin: -1px;
  overflow: hidden;
  padding: 0;
  position: absolute;
  width: 1px;
}
```

This is a best practice for adding elements to a page that we want available only to screen reader users. For instance, we might have a table on a page and want a caption describing that table for screen readers without taking up space on the visible page layout.

You can add that caption to the table in the HTML and apply the sr-only class to ensure the text is available to screen readers but not visible.

A link with the `sr-only` class applied will stay hidden to sighted users at all times, evem when it receives keyboard focus. This can cause confusion when sighted users navigate a page with keyboard controls. <b>For this reason, `sr-only` is generally not appropriate when working with interactive elements like links, buttons, etc.</b> Use Visually Hidden (below) instead.

### Visually Hidden component

See [our Visually Hidden component docs](/components/visually-hidden) for more information. It functions similarly to `sr-only`, but they are not quite the same. For example, a Visually Hidden link will appear to sighted users when in focus. On the other hand, a link with the `sr-only` class applied will stay hidden to sighted users at all times. <b>For this reason, `sr-only` is generally not appropriate when working with interactive elements like links, buttons, etc.</b> Use Visually Hidden instead.

---

## Non-English language support

Content in non-English languages, such as Arabic or Spanish, must have the lang="CODE" attribute set, where CODE is the language code such as &ldquo;ar&rdquo; for Arabic or &ldquo;es&rdquo; for Spanish. There&rsquo;s a [list of language codes](https://www.w3schools.com/tags/ref_language_codes.asp).

Additionally, Arabic and some other languages are read right-to-left. This means we need to set an additional attribute in the HTML for Arabic text. Add dir="rtl to the DOM elements with lang="ar".

Below is an example of how this looks:

```jsx
<p dir="rtl" lang="ar">
  &#1606;&#1580;&#1605; &#1607;&#1584;&#1575; &#1575;&#1604;&#1602;&#1585;&#1575;&#1585; &#1593;&#1606; &#1583;&#1593;&#1608;&#1609; &#1602;&#1590;&#1575;&#1574;&#1610;&#1577; &#1601;&#1610; &#1605;&#1581;&#1603;&#1605;&#1577; &#1580;&#1586;&#1574;&#1610;&#1577; &#1601;&#1583;&#1585;&#1575;&#1604;&#1610;&#1577; &#1601;&#1610; &#1608;&#1575;&#1588;&#1606;&#1591;&#1606; &#1590;&#1583; &#1575;&#1576;&#1606; &#1587;&#1604;&#1605;&#1575;&#1606;
  &#1608;&#1581;&#1608;&#1575;&#1604;&#1610; 20 &#1605;&#1578;&#1607;&#1605;&#1611;&#1575; &#1570;&#1582;&#1585; &#1585;&#1601;&#1593;&#1578;&#1607;&#1575; &#1582;&#1591;&#1610;&#1576;&#1577; &#1580;&#1605;&#1575;&#1604; &#1582;&#1575;&#1588;&#1602;&#1580;&#1610;&#1548; &#1603;&#1575;&#1578;&#1576; &#1575;&#1604;&#1571;&#1593;&#1605;&#1583;&#1577; &#1575;&#1604;&#1605;&#1587;&#1575;&#1607;&#1605; &#1601;&#1610; &#1589;&#1581;&#1610;&#1601;&#1577;
  &#1575;&#1604;&#1576;&#1608;&#1587;&#1578; &#1575;&#1604;&#1584;&#1610; &#1602;&#1615;&#1578;&#1616;&#1604; &#1593;&#1604;&#1609; &#1610;&#1583; &#1593;&#1605;&#1604;&#1575;&#1569; &#1587;&#1593;&#1608;&#1583;&#1610;&#1610;&#1606; &#1601;&#1610; &#1573;&#1587;&#1591;&#1606;&#1576;&#1608;&#1604; &#1610;&#1608;&#1605; 2 &#1571;&#1603;&#1578;&#1608;&#1576;&#1585;/&#1578;&#1588;&#1585;&#1610;&#1606; &#1575;&#1604;&#1571;&#1608;&#1604;
  2018. &#1608;&#1578;&#1586;&#1593;&#1605; &#1575;&#1604;&#1583;&#1593;&#1608;&#1609; &#1571;&#1606;&#1617; &#1608;&#1604;&#1610; &#1575;&#1604;&#1593;&#1607;&#1583; &#1608;&#1575;&#1604;&#1605;&#1578;&#1607;&#1605;&#1610;&#1606; &#1575;&#1604;&#1570;&#1582;&#1585;&#1610;&#1606; &#1605;&#1587;&#1572;&#1608;&#1604;&#1608;&#1606; &#1593;&#1606; &#1580;&#1585;&#1610;&#1605;&#1577; &#1575;&#1604;&#1602;&#1578;&#1604; &#1578;&#1604;&#1603;.
</p>
```

<b>It is very important that this is done correctly.</b> A screen reader user may
not hear content in non-English languages correctly if it is not tagged correctly.
For example, if Arabic is not tagged correctly, then it is not read by the built-in
MacOS & iOS screen reader VoiceOver. Instead, each character is read individually:
&ldquo;Arabic character X, Arabic Character Y,&rdquo; etc. VoiceOver also includes different
voices that pronounce the words from different languages. If `lang` is not set on
non-English text, then VoiceOver will not use the correct voice.

---

## Tables

W3C provides [more guidance for making tables more accessible to screen readers](https://www.w3.org/WAI/tutorials/tables/).

### The caption tag

The `caption` tag is an important component of tables that is used by screen readers to provide an overview of a table when it is first reached. If we don't want the caption to be shown on the visible page (in some cases, we might), then we can hide it using [the sr-only className](#Content%20for%20screen%20readers%20only).

```jsx
<table>
   <caption className="sr-only">Total votes for Biden, Sanders and Warren in Super Tuesday states</caption>
   <thead>
   ...
```

### The thead tag

For a table with only column headers, the `thead` tag contains the headers for each column. Even though the tag is called `thead`, the header elements must still be `th` tags, not `td` tags, in order for the screen reader to read the contents of the table correctly.

This is because screen readers read the header of the column for every cell within that column as a reminder to the reader of what is being read aloud. For instance, if our table contains vote totals and we have:

```jsx
<thead>
    <tr>
        <td>State</td>
        <td>Votes for Biden</td>
        <td>Votes for Sanders</td>
        <td>Votes for Warren</td>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Alabama</td>
        <td>15,000</td>
        <td>7,000</td>
    <td>2,000</td>
    </tr>
    ... // table rows and data for a bunch of other states
    <tr>
        <td>Virginia</td>
        <td>13,000</td>
        <td>8,000</td>
    <td>3,000</td>
    </tr>
<tbody>
```

Then the screen reader will only read the headings once, at the top of the table, and the listener has to remember the order of (1) Biden, (2) Sanders and (3) Warren for the rest of their time reading the table, as they will only be read a bunch of state names and numbers sequentially.

On the contrary, if we have:

```jsx
<thead>
    <tr>
        <th>State</th>
        <th>Votes for Biden</th>
        <th>Votes for Sanders</th>
        <th>Votes for Warren</th>
    </tr>
</thead>
<tbody>
    <tr>
        <td>Alabama</td>
        <td>15,000</td>
        <td>7,000</td>
    <td>2,000</td>
    </tr>
    ... // table rows and data for a bunch of other states
    <tr>
        <td>Virginia</td>
        <td>13,000</td>
        <td>8,000</td>
    <td>3,000</td>
    </tr>
<tbody>
```

Then the screen reader user will hear "Votes for Warren - 3,000" when they get to the last cell in the table. This makes for a much more user-friendly experience, and this is why we should always make sure to use the `th` tag in our `thead` elements.

---

## Alerting screen readers of live updates

`aria-live` is an attribute used to notify people using screen readers of dynamic changes in the content of a live region of a page. See [the ARIA documentation on aria-live](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) for more details.

<br />

**While this attribute can serve a purpose in terms of accessibility, it should be used extremely cautiously.** For instance, a screen reader user may be bothered repeatedly if `aria-live` is applied for something like new comments on an article.

We almost always want to use `aria-live="polite"` when we do use `aria-live`. This makes it so that updates do not interrupt the screen reader user and instead waits til they idle.


Heading order, tables, labels and screen reader support

Semantic HTML and ARIA


## Text size

### Choosing font sizes

Do not use font sizes below 12px. Generally, body font sizes should be at least 14px or 16px.

Important text should be in larger fonts than supplementary text.

Our [WPDS Foundations font sizes](/foundations/typography#Font%20size) start at 12px.

### Scaling

Font size should scale automatically per the user's browser settings.

You can test this by accessing your browser settings and updating the font size, as shown below in Google Chrome. The process and options may vary between browsers and operating systems. Do your research for each situation you are testing.

Ensure after changing the font size that the fonts on your content scale automatically. We should meet our users where they are as much as possible, and that means responding to their settings.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/browser-font-size.png"
      alt="Screenshot shows The Washington Post homepage with 200% font size via Google Chrome browser settings."
    />
  </Box>
</Container>

---

## Page zoom

Content on our pages should remain readable when a user increases their font size or enlarges text using zoom. Many users also have zoom settings configured in their browser (e.g. zoom defaults to 150% on each new page the user opens).

**WCAG sets 200% as the minimum zoom level below which all content on a page should remain readable.**

Zoom in using `command +` (Mac) or `control +` (Windows). You should be able to see the current zoom level momentarily, as shown below.

You'll want to watch for issues like overlapping text, text spilling out of containers, etc. that hinder readability as zoom level increases.

To fix such issues, ensure you are building components that resize dynamically. The below screenshot is from our homepage. We can see that it resizes into a one-column format to accomodate the high zoom level of 200%.

<Container>
  <Box css={{ display: "flex", justifyContent: "center", margin: "auto" }}>
    <InlineImage
      width={836}
      height={448}
      src="/images/zoom-example.png"
      alt="Screenshot shows The Washington Post homepage at 200% page zoom."
    />
  </Box>
</Container>

---

## Font selection

Avoid using complicated fonts that present words in unfamiliar or elaborate ways, such as in cursive or cartoon-ish styling. These can be difficult to read. Additionally, writing in all caps or with irregular capitalization can make text harder to read, especially for screen reader users who may hear text read incorrectly do to irregular capitalization.

Our [WPDS Foundations fonts](/foundations/typography#Font) are good examples of legible fonts. When using a non-WPDS font, consider the above to ensure it is accessible to users.

There is not a consensus as to whether serif or san-serif fonts are more readable in general. We at The Post use both.


Choosing fonts and ensuring they are responsive