BrianAA

alexisbarnes

artmsilva

atomictangerine

chrisalcantara

christian-wp

clairehhelms

crombach

ebgranger

freedmand

hs4man21

klimenkoff9

mjperales

unconstruct

walliby

wp-aberg


<BR />{" "}

## What we learned

Hey there! We just had our design workshop number 2 and it was great joy to share with you all of the new things we have been working on. Here is what you missed:

- Answering some frequently asked questions since we released.
- Learning about our new component api.
- Deep diving on our button component
- Our new css framework
- Slots (new figma pattern for components)

<BR />

---

## The workshop video

<YoutubeEmbed videoid="e_jzDfTdjow" />


Continuing our deep dive in our new design system.

To the right of the image, a woman sits at a desk looking down at her computer. Around her head are bubbles depicting a quote, a video, a website, and a message. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 2 - WPDS for Designers'. 'WP Design System' appears on the lower left.

WPDS v1 - Design Workshop 2


<BR />
Watch Brian Alfaro lead a design workshop for our v1 rollout of the new WPDS. (Recorded
March 16th, 2022).
<BR />

<YoutubeEmbed videoid="cODayPp8b_U" />
<BR />

**Chapters:**

<BR />

[**0:00**](https://www.youtube.com/watch?v=cODayPp8b_U&t=0s) - Agenda & intro

<BR />

[**3:16**](https://www.youtube.com/watch?v=cODayPp8b_U&t=196s) - Our new tokens

<BR />

[**5:49**](https://www.youtube.com/watch?v=cODayPp8b_U&t=349s) - Color tokens

<BR />

[**7:26**](https://www.youtube.com/watch?v=cODayPp8b_U&t=446s) - Numeric tokens

<BR />

[**12:47**](https://www.youtube.com/watch?v=cODayPp8b_U&t=767s) - Context (light and dark)

<BR />

[**17:24**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1044s) - Color intention (theming)

<BR />

[**21:26**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1286s) - Figma plugin (Token
tools)

<BR />

[**25:09**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1509s) - Component API

<BR />

[**27:47**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1667s) - Zeplin code/style guide

<BR />

[**30:30**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1830s) - Zeplin extension

<BR />

[**31:59**](https://www.youtube.com/watch?v=cODayPp8b_U&t=1919s) - Navigation our doc site


Watch Brian Alfaro lead a design workshop for our rollout of the new WPDS.

To the right of the image, a woman sits at a desk looking down at her computer. Around her head are bubbles depicting a quote, a video, a website, and a message. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 1 - WPDS for Designers'. 'WP Design System' appears on the lower left.

WPDS v1 - Design Workshop


## What's happening

Watch Arturo Silva lead our second developer workshop for our v1 rollout of the new
WPDS. Same topics as the first one, but with a different approach. (Recorded April
7th, 2022).

<br />

## Topics discussed

- Box component
- Theme package's OOTB Stitches functions
  - `css`
  - `styled`
  - `theme`
  - `utils`
- The differences between SASS/SCSS and CSS-in-JS
- How to use the `css` function in Svelte, Vue.js, and more
- and much more!

<br />

<YoutubeEmbed videoid="pDQK-UJ2LJQ" />


Watch Arturo Silva lead our second developer workshop for our v1 rollout of the new WPDS. Same topisc as the first one, but with a different approach.

To the right of the image, a man stands holding a text box with both hands. In front of him a large website floats in front of him. He appears to be inserting the text box into the upper left of the website. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 2 - WPDS for Developers'. 'WP Design System' appears on the lower left.

WPDS v1 - Developer Workshop 2


<BR />
Watch Arturo Silva lead a developer workshop for our v1 rollout of the new WPDS.
(Recorded March 17th, 2022).
<BR />

<YoutubeEmbed videoid="CN-vbXz0asI" />


Watch Arturo Silva lead a developer workshop for our v1 rollout of the new WPDS.

To the right of the image, a man stands holding a text box with both hands. In front of him a large website floats in front of him. He appears to be inserting the text box into the upper left of the website. On the upper left of the image, the word 'WORKSHOP' appears in large bold letters. The words below this say 'Session 1 - WPDS for Developers'. 'WP Design System' appears on the lower left.

WPDS v1 - Developer Workshop


---

## Getting started

### Requesting access

If you are a Washington Post employee, please submit a SAR to gain access to your
Figma Product & Design workspace. If you are not a post employee and are
looking to use WPDS Ui Kit, please reference these Figma files.
[WPDS Ui Kit & WPDS Asset Manager](https://www.figma.com/@WPDS).

#### Prerequisite

Before jumping into Figma and using our design system, you must first understand the concepts around our system. The Figma library is built and designed to parallel what is happening in the code.
Please read over the following before proceeding with this guide.

1. [Color](/foundations/color)
2. Tokens - `color`, `radius`, `shadow`, `size`, `typoggraphy`, `z-index`
3. [Asset](/foundations/wam)

---

## Using components

### Enabling our Figma libraries

When using our Figma library, it is essential not to detach as this will
give you the optimal experience when handing off designs to a developer.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Our_Figma_Library__hutMYjdCRe-Anb5ckKUvpw"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Component variants

All of our components match the coded API (properties of the variants)
as close as possible.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Component_Api__rc7AiXYQTX2fe4lMLEOnHg"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

#### Slots

Some of our components use a concept called slots. Slots are for you to
replace with your component or nest another component. To replace,
select the slot in the layer and replace it with the desired component.
You can build out a design that does not need to be detached by replacing slots.

<Container caption="This example shows available slots to replace with other local or design system components">
  <InlineImage
    width={252}
    height={285}
    maxWidth="100%"
    src="/img/guides/figma/slots.png"
  />
</Container>

#### Icons

If an icon layer of a component is locked, this indicates that you should not change the icon. Otherwise, you may modify the icon glyph using any icon available in our Asset Manager.

#### Use Figma variant controls

Only use the Figma variant controls when modifying the Figma component to apply the desired variant. These controls closely match
to the coded component and inform the developer on what property value to assign.
Avoid manually overriding the properties by selecting the layers.

<Container>
  <InlineImage
    width={318}
    height={156}
    maxWidth="100%"
    src="/img/guides/figma/component_properties.gif"
  />
</Container>

---

## Using our tokens

### Applying tokens

In Figma, we have two tokens managed by the native Figma UI.
The shadow and color tokens can be accessed by
selecting the style icon. All other tokens are handled either through our token
tools or manually.

#### Applying color

Select the style icon and apply the fill or stroke color to apply a color token in Figma.
When selecting a color style, all tokens are displayed; a helpful way
of picking the right colors is to use our [theme](/foundations/color#Themes) alias to assign color with intention.

<Container>
  <InlineImage
    width={239}
    height={322}
    maxWidth="100%"
    src="/img/guides/figma/using_theme.gif"
  />
</Container>

#### Applying shadows

To apply shadows to an element, select the effects in the design panel and apply one of the shadow tokens.

<Container>
  <InlineImage
    width={228}
    height={322}
    maxWidth="100%"
    src="/img/guides/figma/applying_shadows.gif"
  />
</Container>

### Applying other tokens

We developed a plugin to manage and assign tokens in Figma that are currently
not supported or flexible enough to be used in design without detaching the style.
Our plugin resolves this by connecting our tokens while still being flexible in Figma.

#### Installing Token Tools

To install the plugin, visit the [plugin landing page](https://www.figma.com/community/plugin/1044987008646864166/Token-Tool)
and install. You will now have access to the plugin in your Figma file. If you do not see the plugin, please reload the file.

#### Token tools

Token Tools is a plugin that we will iterate and expand on as our needs grow with the system.
The interface design mimics Figma UI to avoid learning new interaction patterns.

<Container>
  <InlineSVG
    width={300}
    height={600}
    path="/img/guides/figma/plugin.svg"
    description="TESTING"
  />
</Container>

#### Theme

The theme tool in token tools applies the matching color for that theme switching it from its
current context to the following context.

<Container>
  <InlineImage
    width={1148}
    height={406}
    maxWidth="100%"
    src="/img/guides/figma/plugin_theme.gif"
  />
</Container>

#### Border radius

Using the border radius tool will apply the border radius token to any frame or shape that
has a uniform border radius.

<Container>
  <InlineImage
    width={1158}
    height={540}
    maxWidth="100%"
    src="/img/guides/figma/border_radius.gif"
  />
</Container>

#### Font size & Line height

The font size and line height tool will apply the token to the selected text element.

<Container>
  <InlineImage
    width={1158}
    height={540}
    maxWidth="100%"
    src="/img/guides/figma/font_size_line_height.gif"
  />
</Container>

#### Font weight & Font Family

Currently, token tools do not manage font family or font weight. However, in the WPDS Zeplin extension, the extension will note the tokens. For more information, please refer to our tokens documentation to apply the correct value in
Figma.

<BR size="xl" />

#### [Read next our Zeplin guide >](/resources/guides/zeplin-guide)

<BR size="xl" />


Figma is our tool of choice when designing and using our design system. Other design software is currently not supported, but maybe in the future.

Figma Guide


---

## Getting started

### Requesting access

If you are a Washington Post employee, please submit a SAR to access our Zeplin Product & Design workspace. If you are not a post-employee and want to use Zeplin in your suite, please reference our Figma file to upload and create your style guide.

### Creating a Zeplin project

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Creating_a_Zeplin_project__3QIHj0krQKKwmVOizwQ50Q"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Connecting WPDS Styleguide

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", maxWidth: "100%", padding: "$100 $100" }}
    src="https://scribehow.com/embed/Zeplin_Workflow__Sl-5tsJ3R26TMT8HyT_4QQ"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

### Connected Components

By linking the style guide you unlock our connected compoents. Selecting a component connected to code in Zeplin will reveal a code snippet and the props chosen for the component variant. This happens when you use our Figma Ui Kit components!

<Container caption="In this example the properties reveal taht 32 was selected for the prop `size`">
  <InlineImage
    src="/img/guides/zeplin/connected.png"
    width={520}
    height={671}
    maxWidth="100%"
  />
</Container>

#### Properties

We do our best to ensure that our Figma API that translates to Zeplin properties matches as close to 1:1 of the actual coded component. However, you might find some properties like states that are not in the coded component; this is due to the nature of Figma. In those instances, you can ignore it unless otherwise documented.

---

## Extension

### Getting WPDS Extension

Zeplin supports a good amount of tokens; there are some limitations in how some tokens are managed or not managed at all. Right not the current tokens managed by Zeplin is only color. We chose not to manage typestyles; instead, we highlight individual tokens font size, font, line height using our extension. We also manage tokens like border radius and shadows using our extension.

#### Installing the extension

Select the project in Zeplin you would like to add the extension to and then select extension > explore extensions > add WPDS Tokens.

<Container>
  <Box
    as="iframe"
    css={{ minHeight: "640px", padding: "$100 $100" }}
    src="https://scribehow.com/embed/WPDS_Zeplin_Extension__5t1hkwhtTzWyXS749Yk-2g"
    width="100%"
    height="640"
    allowfullscreen
    frameborder="0"
  ></Box>
</Container>

#### Typography tokens

To reveal the typography tokens, select a text layer to have the extension show the properties of that text.

<Container>
  <InlineImage
    alt="Animated image of showing how to add the WPDS extension"
    width={323}
    height={195}
    maxWidth="100%"
    src="/img/guides/zeplin/text_tokens.png"
  />
</Container>

#### Border radius and shadows

To reveal the border radius or shadow, select a layer with a border radius or shadow, and the extension will show the corresponding tokens.

<Container>
  <InlineImage
    alt="Animated image of showing how to add the WPDS extension"
    width={318}
    height={156}
    maxWidth="100%"
    src="/img/guides/zeplin/shadow_border.png"
  />
</Container>

#### Token syntax

Note that all tokens will display in stitches token string format by adding a $. Stitches is our default styling framework for our system, but if you need to refer to the token, drop the $.

<BR size="xl" />


Zeplin is our tool of choice when it comes to hand-off. It offers a layer of connection to code and design not yet realized by other tools.

Zeplin Guide


## 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

Text size, fonts and zoom settings


---

## 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 (i.e. "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 “ar” for Arabic or “es” for Spanish. There’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">
  نجم هذا القرار عن دعوى قضائية في محكمة جزئية فدرالية في واشنطن ضد ابن سلمان
  وحوالي 20 متهمًا آخر رفعتها خطيبة جمال خاشقجي، كاتب الأعمدة المساهم في صحيفة
  البوست الذي قُتِل على يد عملاء سعوديين في إسطنبول يوم 2 أكتوبر/تشرين الأول
  2018. وتزعم الدعوى أنّ ولي العهد والمتهمين الآخرين مسؤولون عن جريمة القتل تلك.
</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:
“Arabic character X, Arabic Character Y,” 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


---

## 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 — after it is selected — 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 — starting at the bottom — 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 — while maintaining pressure on the screen — 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/) — a paid-only screen reader for Windows and MacOS — 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


---

## 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

Resources

Release Notes

Welcome

What's new

Getting started

Foundations

Components

Resources

Dive Deeper

WPDS v1 - Design Workshop 2

WPDS v1 - Design Workshop

WPDS v1 - Developer Workshop 2

WPDS v1 - Developer Workshop

Figma Guide

Zeplin Guide

See all resources

Engineering Contributors

BrianAA

alexisbarnes

artmsilva

atomictangerine

chrisalcantara

christian-wp

clairehhelms

crombach

ebgranger

freedmand

hs4man21

klimenkoff9

mjperales

unconstruct

walliby

wp-aberg

FoundationsChevron Icon

ComponentsChevron Icon

ResourcesChevron Icon

Resources

Release Notes

Welcome

What's new

Getting started

Foundations

Components

Resources

Dive Deeper

WPDS v1 - Design Workshop 2

WPDS v1 - Design Workshop

WPDS v1 - Developer Workshop 2

WPDS v1 - Developer Workshop

Figma Guide

Zeplin Guide

See all resources

Engineering Contributors

BrianAA

alexisbarnes

artmsilva

atomictangerine

chrisalcantara

christian-wp

clairehhelms

crombach

ebgranger

freedmand

hs4man21

klimenkoff9

mjperales

unconstruct

walliby

wp-aberg