Coding a page


<Alert dismissable={false} variant="information">
  <b>Note: </b>When contributing a component the process takes time, and a quick
  turnaround is in contrast to the amount of testing and approval that each
  component requires. WPDS components follow a strict contribution process to
  minimize breaking changes or bugs.
</Alert>

---

## Getting started

### Read our principles

Before designing and developing the components of your dreams, please read over our principles. Reading our principles will help frame the entire process before any design or development occurs.

After reading our principles please submit your component idea to using our [support channels.](/resources/process/support)

---

## Design

All components follow a design process and approval process before any development starts. We have generated a Figma template file that you can reference as a designer to ensure all areas are covered when designing a new component or making refinements. It has a required checklist for each phase. The high-level process is as follows:

### Phase 1: Audit

1. **Audit our current website:** Look at our site for similar patterns related to your present component. If you find a pattern on the site that matches this component document with screenshots, annotate behaviors and variants. It may be the case we do not have this component, and if that is the case, note it in your designs.

2. **Audit the web:** Visit popular sites and document patterns, behaviors, and variants. The chances are that these popular sites will help inform expected visual and interaction patterns users come to expect from a component.

3. **Audit other design systems:** It is always best practice to audit other design systems as patterns at a component level is shared between systems. It is best to understand why that pattern, style, or behavior fits that specific product.

4. **Audit our design system:** Last but not least, audit our own system. Often, we tend to think about visual patterns in isolation, but a design system is a series of interconnected patterns shared across many components. Document the similar patterns, behaviors, or variants of our existing components.

### Phase 2: Concept

1. **Distill the audit findings:** Distill the audit findings into actionable insights. These insights should result in a clear direction on conceptual exploration.

2. **Think in WPDS:** When designing the component, please think holistically and not for one specific use case. It may require getting in touch base with other designers, product managers, and engineers to understand what this component is trying to resolve.

3. **Design in context and out of context:** One of the pitfalls when designing a component is that we tend to design in isolation, resulting in a poorly tested component. However, designing for a single context also results in a hyper-specialized component, resulting in a very unflexible component.

4. **Use our system:** When starting your concepts start with our system. All of our components must utilize our tokens. That means to avoid creating new tokens to fit the concept. Exhaust our system before making new tokens within a new component.

### Phase 3: Decide

1. **Options:** When thinking about component options, consider future use cases and current ones. Don’t feel a need to have multiple options. Some components have only one option, and that is okay.

2. **Behaviors:** Documenting behaviors include defining states, overflow behavior, responsive behavior, and conditional behavior. You want to make sure your component is flexible and ready to be tested.

3. **Guidance:** Create clear guidance on the component for others to reference when using it. The direction will help avoid component misuse.

4. **Accessibility:** All of our components must meet the minimum accessibility requirements for the site laid out by WCAG for AA standards. Please review your component based on those standards. They differ from component to component.

5. **Specs:** Define the specs using our tokens. Be clear in a fixed size, positioning of elements when scaled, and any other requirements.

### Phase 4: Deliver

1. **Submit:** At the end of the design process comes the submission. At this stage, you have already completed what has outlined above, completed the required checklist in the Figma template, and have received approval from all the parties necessary (Design leadership, WPDS, and other Stakeholders). Next, submissions move to our backlog awaiting development for an engineer to contribute or to be contributed by WPDS team.

<BR size="lg" />

---

## Code

All components must follow a predefined design spec. Without a design spec, development cannot occur. If you are interested in a [component not in our backlog](https://arcpublishing.atlassian.net/jira/software/c/projects/WPDS/boards/721/backlog?issueLimit=100), please reach out.

### Core Tenets

When developing a component, use these core tenets for component design:

1. They should be controlled by their API or left uncontrolled.
2. If a component has multiple DOM nodes such as an Accordion's trigger and its
   display it should be split into multiple components, such as AccordionTrigger and AccordionDisplay, and use a provider component to manage the state across the two (e.g. AccordionRoot).
3. We should avoid using any DOM APIs that are not supported by evergreen browsers.
4. We should allow modification of styles via the css prop using our tokens (locally and globally scoped components and theme).
5. We should use our theme tokens to style our components.

### Ready to Code

1. Check our Jira backlog to make sure that your component is not [currently being worked on](https://arcpublishing.atlassian.net/jira/software/c/projects/WPDS/boards/721/backlog?issueLimit=100) and check the component section on the docs site double check that it does not already exists. Reach out to the WPDS team on slack if you have any questions.

2. Components live in the [wpds-ui-kit](https://github.com/washingtonpost/wpds-ui-kit/). Make sure you can spin up the local dev environment. If you are running into any issues, double check that the node version matches that on the `.nvmrc` file and that you're using npm v8.3. See [WPDS-ui contribution doc](https://github.com/washingtonpost/wpds-ui-kit/blob/main/docs/CONTRIBUTING.md) for more information.

3. We use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary) for **every** commit. We don't squash our commits from our PR into one before merging to main. We like to keep our git history clean. For example, `feat: add new component and stories` or `fix: update props`.

4. On the command line run the new-component scaffolding script `npm run new-component <component-name>` to get things started. This command will create a component directory for you that includes an `index.ts` file, a `play.stories.jsx`, and a `<component-name>.tsx` file.

5. Add all of your component's logic in the .tsx file. Remember, you should split up complex components into multiple files. We have [a list of props](https://www.notion.so/wpds/c48e64598ff7445e914158c58ed00b2a?v=364f79cb1dab47868ccba2e7edd94a13) we use to make sure we stay consistent. If you need a prop that doesn't fit into one of these, feel free to add your own. Don't forget to document it!

6. Add a storybook example with interactive props so that it's easy for others to see how your component works. If there are multiple variants of your compoment, please add some headers to distinguish them. This should also make it easy to see the different states your component has (what happens on hover, on click, etc.).

7. Add your component to the server side testing page `app/pages/index.tsx`. This page helps us catch possible server side render issues with all of our compoments.

8. Make a PR and include @WPDS for review. Feel free to add your teammates as well so they can see how easy it is to contribute to WPDS! Once your PR is approved, it's documentation time.

9. All component documentation lives in [wpds-ui-kit/build.washingtonpost.com](https://github.com/washingtonpost/wpds-ui-kit/tree/main/build.washingtonpost.com). As the main contributor, you are responsible for documenting your new component. Together with your designer, come up with and document some content, assets, best practices, and any other helpful things someone consuming your component needs. Don't forget to document implementation details and code specific things in the component's README.

10. All components have a Zeplin code snippet available to all who use Zeplin. As the main contributor, you are responsible for connecting your component to Zeplin and creating a code snippet. Follow the steps in [Connecting to Zeplin](https://www.notion.so/wpds/Zeplin-connect-2c7a6da2b486407995133a8f32c61c70) to get your component synced up to Zeplin. Note: in order for this to work, design needs to have added your component to the [styleguide](https://app.zeplin.io/project/625db54ff0892110f1f9fa03/styleguide).

11. Congratulations, your component is now ready to ship 🎉. Review the [release documentation](https://github.com/washingtonpost/wpds-ui-kit/blob/main/docs/RELEASING.md#upload-bundled-code-to-latest-channel) and [latest releases](https://github.com/washingtonpost/wpds-ui-kit/releases) to see how we release components. New components are released on a monthly basis.

12. Now that your work is live, others can start to use it! Please note that you are expected to **commit to two weeks of support and triage**. Please review the [support process](https://build.washingtonpost.com/resources/process/support).


This document describes the process of contributing a component to our system. We are always excited when our community looks to expand our design system. Thank you for taking the time to contribute.

Contribute a Component


---

## Intro

There may be some instances where your team needs to use an icon with an asset that does not currently exist in WAM.

While we aim to help as much as we can, other commitments could mean that we are unable to add an icon to WAM within your timeframe.
It is also possible that you need an icon for a domain specific use case and it does not make sense to add this asset to the system.
For both of these instances, a custom icon might be what you need.

### Prerequisites

This guide assumes that you are working with ReactJS and are using the WPDS Icon Component.

---

## Design

1. **Double-check**: Please make sure that the icon you are looking to use doesn't currently exist in WPDS. You can check Figma or go to the [Icon Assets Page](https://build.washingtonpost.com/foundations/icons) in our docs site to look through what assets we currently make available.

2. **Follow contribution guidelines**: When creating your icon, please follow the contribution guidelines outlined in the [Making an Icon](https://build.washingtonpost.com/foundations/wam#Contributing) section of our docs

3. **Export as SVG**: Please ensure that your new icon is a SVG. In WPDS, all icons are 16x16 pixels.

---

## Code

1. **Add svg to repo and make it a React Component**: Add the svg file to your repo and make it a React Component. There are a couple of different ways you can do this.

   - If you are going to be using a lot of SVGs in your repo, then you might consider using something like [@svgr/webpack](https://react-svgr.com/docs/webpack/) and setting up your webpack configs to convert your SVGs to React Components for you automatically.

   - You can use an online conversion tool such as [SVGR Playground](https://react-svgr.com/playground/) to convert your SVG into a React Component. You can then simply copy and paste that new component into your code.

   - You can cast your SVG into a React Component from your import statement. This might be an okay solution if you are going to be using this icon less than a handful of times. Otherwise, you might want to consider using one of the first two options.

2. **Pass SVG into the Icon component**: Once you have your SVGs available to you as React Components, you can now pass them into the WPDS Icon component like you would a WPDS icon. They will behave the same.

   ```jsx
   import * as React from "react";

   import { Icon } from "@washingtonpost/wpds-ui-kit";
   import { Bell } from "@washingtonpost/wpds-assets";

   // Casting our Crop SVG as a ReactComponent
   import { ReactComponent as Crop } from "./crop.svg";

   export default function App() {
     return (
       <>
         <Icon label="icon" size="200">
           <Bell /> //Our WPDS icon
         </Icon>
         <Icon label="icon" size="200">
           <Crop /> //Our custom icon
         </Icon>
       </>
     );
   }
   ```


How to use our Icon component with your own SVGs to create a custom Icon.

Creating Custom Icons


## When to use

**If you're using emojis, they should ideally meet all the following criteria:**

- Used as an enhancement (but not in place of words)
- Used sparingly
- Used when the overall tone of the experience is light

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      Emojis chosen should also be light in tone (i.e. confetti is OK;
      tombstones for a Halloween email, not so much)
    </Box>
  </Box>
</Box>

- Used when there's no chance of the emojis appearing juxtaposed with grim, serious articles

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{

      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}

>

    <Box role="listItem">
      For example, Microsoft doesn't have flag emojis. Check to make sure your
      emojis convey what you're intending.
    </Box>

  </Box>
</Box>

<BR/ >

## How to use

**If you use emojis:**

- Use widely recognized emojis that translate well across devices.

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      For example, Microsoft doesn't have flag emojis. Check to make sure your
      emojis convey what you're intending.
    </Box>
  </Box>
</Box>

- Make sure the emoji has enough contrast for both light and dark modes.
- Place them at the beginning or end of sentences, not in the middle.
- Use within text (as opposed to an image or any other format).

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">This is required by Apple's guidelines.</Box>
  </Box>
</Box>

- Make sure related copy stands on its own — emojis should be able to be deleted without affecting the meaning.

<BR/ >

## When to avoid

**Avoid using emojis:**

- To represent our core product offerings.

<Box css={{ position: "relative", paddingLeft: "$200" }}>
  <Box
    role="list"
    css={{
      "&::before": {
        content: '"○"',
        position: "absolute",
        left: "$100",
        fontSize: "$100",
        color: "$gray20",
      },
    }}
  >
    <Box role="listItem">
      If we need art to represent core product offerings, we should evaluate if
      the use case warrants creating custom art.
    </Box>
  </Box>
</Box>

- If there's any chance of the emojis appearing juxtaposed with grim, serious stories.


Use these guidelines to help make decisions about emojis in product and marketing contexts. (Newsroom follows its own style guide.)

Emoji Guide


---

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

<Alert dismissable={false} variant={"warning"}>
  <b>Note:</b> If you are not upgrading to our Q2 2022 color tokens this guide
  is not for you and you can review our{" "}
  <a href="/foundations/color">color tokens</a>.
</Alert>

<BR />

Before getting started and reviewing all of our new beautiful colors, we need to spend some time reflecting on just where we are coming from and by that I mean we need to look at our old colors. Long ago before we were even where we are today, our colors used a naming convention based on their perceived lightness against a white background. While that may have worked at one time, we have long since outgrown this naming convention.

<BR />

<Container caption="Example of tokens named by perceived lightness">
  <InlineSVG
    path="/img/guides/color-migration/light_dark_darker.svg"
    width="695px"
    height="115px"
  />
</Container>

<BR />

---

## The problem & resolution

The old way of naming our color tokens presented issues for us to scale as a system. The main issues were the following:

1. **Inconsistent terminology**
   -- The first problem with the way we were naming our tokens was that it was not consistent across color families. What was `lightest` in one color scale, was `pale` in another.

2. **Limited color scales**
   -- The second problem was our inability to grow our color scales. For example how might we add a color between `gray-light` and `gray-lighter` (_gray-semi-light?_). In our new palette there was a need for more colors in each family and this forced us to take a more scalable approach.

3. **Confusing when going from light to dark contexts**
   -- Lastly there is the problem of generating token names based on perceived lightness. In our previous system of color tokens, all perceived lightness was measured against a white background. The problem becomes when we change that background to a dark context, the visual relationship between light and dark is inverted, which is not reflected in the token name. As we want our colors to be adaptive using the same contrast across different contexts, percieved lightness was not a viable approach.

### The resolution

To resolve many of the issues outlined above we have changed our naming convention to use numbers instead of perceived lightness. This has unlocked the ability for our color tokens to flex according to the context, scale to support more colors in a family and avoid inconsistencies across color families.

---

## Phase 1: Translation

If you are an early adopter of our new design system, you have already been using our new color token naming convention. This phase is referred to as a "translation" because our color tokens did not disrupt or add any new colors to our legacy system. We simply translated the previous tokens to a normalized color scale. This provides the runway to begin to scale our color scales accordingly, while having minimum impact when we integrate into our unified palette.

<Container caption="Example of gray-dark translating to gray-80">
  <InlineSVG
    path="/img/guides/color-migration/dark-80.svg"
    width="345px"
    height="115px"
  />
</Container>

<BR />

### Old convention → New convention

<Alert dismissable={false} variant={"warning"}>
  <b>Note:</b> all other Subs colors were deprecated in this translation as
  there was uncertainty on which colors would remain after the final color
  consolidation of our new palette of phase 2.
</Alert>

<Collapsible maxHeight={350}>

| **Old convention** | **New convention** |
| ------------------ | ------------------ |
| black              | gray0              |
| off-black          | gray20             |
| gray-darkest       | gray40             |
| gray-darker        | gray60             |
| gray-dark          | gray80             |
| gray               | gray100            |
| gray-light         | gray200            |
| gray-lighter       | gray300            |
| gray-lightest      | gray400            |
| offwhite           | gray500            |
| white              | gray600            |
| blue-dark          | blue80             |
| blue               | blue100            |
| blue-bright        | blue200            |
| blue-pale          | blue300            |
| red-dark           | red80              |
| red                | red100             |
| red-bright         | red200             |
| red-pale           | red300             |
| orange-dark        | orange80           |
| orange             | orange100          |
| orange-bright      | orange200          |
| orange-pale        | orange300          |
| green-dark         | green80            |
| green              | green100           |
| green-bright       | green200           |
| green-pale         | green300           |
| gold-dark          | gold80             |
| gold               | gold100            |
| gold-bright        | gold200            |
| gold-pale          | gold300            |
| subs-blue-dark     | vividblue80        |
| subs-blue          | vividblue100       |
| subs-blue-bright   | vividblue200       |
| subs-blue-pale     | vividblue300       |

</Collapsible>

---

## Phase 2: Growth & Adoption (Final Phase)

The introduction of one unfied system of color tokens represents the evolution of our color palette across the organization. This palette was contributed to by a collection of individuals from many different departments. Our main goal with this palette is to bring together our vast spectrum of colors and eliminate arbitrary deviations that we encountered throughout our product at large.

### Which colors changed in phase 2?

<BR />

#### Grayscale tokens

The grayscale now ranges from `0` to `700`
| Token | Notes |
| ------- | ---------------------------------- |
| gray0 | no change to value |
| gray20 | no change to value |
| gray40 | no change to value |
| gray60 | new color value |
| gray80 | no change to value |
| gray100 | new color value |
| gray200 | new color value: equivalent to gray100 in phase 1 |
| gray300 | new color value: equivalent to gray200 in phase 1 |
| gray400 | new color value: equivalent to gray300 in phase 1 |
| gray500 | new color value: equivalent to gray400 in phase 1 |
| gray600 | new color value: equivalent to gray500 in phase 1 |
| gray700 | new color value: equivalent to gray600 in phase 1 |

<BR />

#### Vivid blue

<Alert dismissable={false} variant={"error"}>
  <b>Note:</b> vividblue is no longer a supported token. All of the vividblues
  have been merged into one family of blue. Please review the blue tokens to map
  to the desired blue value.
</Alert>

<BR />

#### Blue

All colors for blue have changed in value and now support a scale from `40` to `600`:

| Token   | Notes                                                  |
| ------- | ------------------------------------------------------ |
| blue40  | new token added                                        |
| blue60  | new token added                                        |
| blue80  | change to value                                        |
| blue100 | change to value: equivalent to vividblue100 in phase 1 |
| blue200 | change to value                                        |
| blue300 | change to value                                        |
| blue400 | new token added                                        |
| blue500 | new token added                                        |
| blue600 | new token added: equivalent to vividblue300 in phase 1 |

<BR />

#### Red

All colors for red have changed in value and now support a scale from `40` to `600`:

| Token  | Notes                                            |
| ------ | ------------------------------------------------ |
| red40  | new token added                                  |
| red60  | new token added                                  |
| red80  | change to value                                  |
| red100 | no change to value                               |
| red200 | change to value                                  |
| red300 | change to value                                  |
| red400 | new token added                                  |
| red500 | new token added                                  |
| red600 | new token added: equivalent to red300 in phase 1 |

<BR />

#### Green

All colors for green have changed in value and now support a scale from `40` to `600`:

| Token    | Notes                                              |
| -------- | -------------------------------------------------- |
| green40  | new token added                                    |
| green60  | new token added                                    |
| green80  | change to value                                    |
| green100 | no change to value                                 |
| green200 | change to value                                    |
| green300 | change to value                                    |
| green400 | new token added                                    |
| green500 | new token added                                    |
| green600 | new token added: equivalent to green300 in phase 1 |

<BR />

#### Gold

All colors for gold have changed in value and now support a scale from `40` to `600`:

| Token   | Notes                                                    |
| ------- | -------------------------------------------------------- |
| gold40  | new token added: equivalent to gold80 before the change  |
| gold60  | new token added: equivalent to gold100 before the change |
| gold80  | change to value: equivalent to gold200 before the change |
| gold100 | change to value                                          |
| gold200 | change to value                                          |
| gold300 | change to value                                          |
| gold400 | new token added                                          |
| gold500 | new token added                                          |
| gold600 | new token added: equivalent to gold300 in phase 1        |

<BR />

#### Orange

All colors for orange have changed in value and now support a scale from `40` to `600`:

| Token     | Notes                                               |
| --------- | --------------------------------------------------- |
| orange40  | new token added                                     |
| orange60  | new token added                                     |
| orange80  | change to value                                     |
| orange100 | no change to value                                  |
| orange200 | change to value                                     |
| orange300 | change to value                                     |
| orange400 | new token added                                     |
| orange500 | new token added                                     |
| orange600 | new token added: equivalent to orange300 in phase 1 |

<BR />
### [Please see our Color tokens to see all of our tokens](/foundations/color)


This guide will help you understand the evolution of our color palette. It will also help you if you are using our v1 tokens or even using our v0 tokens to migrate to use our latest unified palette! So let's jump right in!

Migrating to our new palette


---

## Introduction

Web performance and SEO are crucial aspects of a website's success. Both contribute significantly to the overall user experience, user engagement, and the website's visibility in search engines.
Web performance refers to the speed and efficiency with which a website loads and operates. A website with good performance ensures a smooth and enjoyable user experience. The importance of web performance lies in the following aspects:

- **User Experience**: Fast-loading websites provide a better user experience, which is essential for keeping users engaged and encouraging them to explore content.
- **Conversion Rates**: A website that loads quickly and functions efficiently can lead to higher conversion rates, as users are more likely to complete desired actions (e.g., making a purchase, signing up for a newsletter).
- **Mobile Users**: With the increasing use of mobile devices, it's crucial to ensure that a website performs well on various devices and network conditions. A well-performing site caters to a broader audience and ensures a positive experience for mobile users.
- **Search Ranking**: Google and other search engines consider web performance as a ranking factor. Faster websites are more likely to rank higher in search results, leading to increased visibility and organic traffic.

SEO is the process of optimizing a website to improve its visibility in search engine result pages (SERPs). The importance of SEO can be summarized in the following points:

- **Organic Traffic**: Effective SEO helps increase the website's visibility in search engines, leading to more organic traffic. Organic traffic is valuable because it is targeted and often has higher conversion rates than paid traffic.
- **Credibility and Trust**: Websites that rank higher in search results are often perceived as more credible and trustworthy by users. Good SEO practices can help improve a website's reputation and authority.
- **Cost-Effective Marketing**: SEO is a cost-effective marketing strategy compared to paid advertising. Once your website ranks high in search results, you can enjoy a continuous stream of organic traffic without incurring additional costs.
- **Competitive Advantage**: By optimizing a website for search engines, it gains a competitive edge over competitors with less effective SEO strategies.

Web performance and SEO are vital for providing a positive user experience, increasing website visibility, driving organic traffic, and ultimately, improving a website's overall success. By focusing on these aspects, you can create a strong foundation for a website's growth and long-term success.

---

## Web Performance

### Loading performance

- Optimize images by compressing them, using responsive images for different screen sizes, and implementing lazy loading to defer the loading of off-screen images until they are needed.
- Minify and compress CSS, JavaScript, and HTML files to reduce their size and improve load times.
- Use Content Delivery Networks (CDNs) to distribute static assets across a network of servers, reducing latency and improving load times for users around the world.

### Rendering performance

- Optimize the critical rendering path by minimizing the number of critical resources and prioritizing the loading of above-the-fold content. This helps ensure that users see content faster.
- Use efficient CSS selectors to minimize browser work during the rendering process, and avoid layout thrashing by batching DOM updates and minimizing forced reflows.
- Optimize JavaScript execution by deferring or asynchronously loading non-critical scripts, profiling and optimizing JavaScript performance, and using requestAnimationFrame for animations.

### Responsiveness

- Design websites for various screen sizes and devices to ensure a consistent and enjoyable user experience across different contexts.
- Implement responsive design techniques, such as fluid grids, flexible images, CSS Flexbox, and Grid Layout, to create adaptable layouts that adjust to different screen sizes and orientations.
- While JavaScript can be used for certain aspects of responsive design, it's generally recommended to prioritize CSS for controlling the layout and visual presentation of the page at different viewport sizes. CSS-based solutions typically perform better, require less code, and can be managed within stylesheets, keeping the separation of concerns between style and functionality.
- JavaScript should ideally be used for interactivity and enhancing the user experience, not for managing core layout changes wherever possible. In some complex scenarios, JavaScript might be required to achieve advanced responsive behaviors that CSS alone can't handle. In these cases, care should be taken to ensure performance and accessibility are not negatively impacted.

---

## SEO (Search Engine Optimization)

### On-page SEO

- Use descriptive and concise title tags to accurately represent the content of each page, helping search engines understand its purpose and relevance.
- Optimize meta tags for both users and search engines:
  - Write informative and unique `meta description` tags to give users a preview of the page content, improving click-through rates from search results.
  - Utilize `meta lang` tags to specify the language of the site's content for better search engine understanding and accessibility.
  - Implement `Open Graph` meta tags to enhance how the pages appear in social media shares, providing richer snippets that attract more engagement.
  - Use `meta robots` tags to guide search engines on what to do with the site's pages. For instance, you can instruct them not to index a page, or not to follow any links on a page.
  - Remember, each meta tag serves a distinct purpose, so ensure they are used appropriately and are relevant to the page's content.
- Use header tags (H1, H2, H3) effectively to structure content and provide hierarchy, making it easier for search engines to understand the content's importance.
- Optimize URL structures by making them readable, descriptive, and concise, helping both users and search engines understand the page's content.

### Content optimization

- Write high-quality, unique, and engaging content to satisfy user intent and increase the likelihood of ranking higher in search results.
- Use proper keyword targeting by including relevant keywords naturally within the content and avoiding keyword stuffing, which can harm rankings.
- Optimize images by using descriptive alt text, relevant file names, and compressing images to reduce file sizes, improving page load times.

### Technical SEO

- Improve site speed by optimizing page load times, as faster-loading pages are more likely to rank higher in search results.
- Implement structured data (schema markup) using JSON-LD to provide additional context for search engines, potentially improving search result appearance and click-through rates. Here are some resources to delve deeper:
  - Understand how to structure data in JSON-LD format. You might use schemas such as `NewsArticle`, `LiveBlogPosting`, and more depending on the content (here is an [example](https://validator.schema.org/#url=https%3A%2F%2Fwww.washingtonpost.com%2Flifestyle%2F2023%2F03%2F15%2Fdog-adoption-potcake-turks-caicos%2F)). Check the JSON-LD website and the Google's guide for further learning.
  - Always validate the schema markups for correctness. Use tools like the Google's Structured Data Testing Tool or Schema Validator to ensure the JSON-LD is error-free and up to standard.
  - Remember, a well-structured schema markup can enhance visibility in search engine results, improve click-through rates, and provide a better understanding of the page content to search engines.
- Ensure crawlability and indexability by properly configuring robots.txt and creating XML sitemaps, helping search engines discover and index the site's content.
- Use canonical tags to avoid duplicate content issues and signal to search engines which version of a page should be considered the original.
- Implement HTTPS and secure the site to protect user data and improve trust with both users and search engines.

### Off-page SEO

- Build high-quality and relevant backlinks from authoritative websites, as they serve as signals of the site's credibility and trustworthiness.
- Utilize social media for content promotion, expanding the content's reach and potentially attracting more backlinks and organic traffic.
- Consider guest posting and content outreach to build relationships with other websites and influencers, increasing the site's visibility and authority.

---

## Monitoring and Reporting

- **Use web performance monitoring tools**: Utilize tools such as Lighthouse and WebPageTest to analyze the site's performance. These tools provide insights into various aspects of performance, including loading speed, rendering, and responsiveness. They also offer recommendations for improvements, making it easier to identify areas that need optimization.
  - **Lighthouse**: An open-source tool by Google that audits websites for performance, accessibility, progressive web apps, SEO, and more. Lighthouse can be run in Chrome DevTools, from the command line, or as a Node module.
  - **WebPageTest**: A free web performance tool that allows you to run tests from multiple locations and browsers, providing detailed information on load times, rendering, and other performance metrics.
  - **Catchpoint (RUM)**: Real User Monitoring tools like Catchpoint help track real user interactions with the site, giving you an accurate picture of actual user experiences across various devices and network conditions. While synthetic tests are useful for simulating specific scenarios or devices, RUM data offers real-world insights that can inform optimization efforts.
  - **Track Core Web Vitals (CWV) trends**: Collaborate with the analytics team to request a report highlighting CWV improvements over a specific time range, or verify the trend directly in the Google Analytics CWV Dashboard, which allows for filtering by page type, date range, mobile versus desktop, and more. Verify trends in the Catchpoint RUM Web Vitals dashboard for the same time range. Although synthetic tests, like Lighthouse or Chrome extensions, can provide useful instant feedback, they are not sufficient to confirm impact at scale. Therefore, make sure to use a combination of these resources to gather comprehensive insights about the site's performance over time.
- **Set up SEO tracking and reporting**: Implement tools like Google Search Console and Google Analytics to track and report on the site's SEO performance. These tools offer insights into organic traffic, search queries, click-through rates, and other valuable SEO-related data.
  - **Google Search Console**: A free service offered by Google that helps you monitor, maintain, and troubleshoot the site's presence in Google Search results. It provides information on indexing status, search queries, and any issues that might be affecting the site's visibility.
  - **Google Analytics**: A comprehensive web analytics service that provides insights into website traffic, user behavior, and other performance metrics. With Google Analytics, you can track organic traffic, user engagement, and the effectiveness of the SEO efforts. Integrating Google Analytics with Google Search Console can provide more in-depth data on the site's SEO performance.

---

## Resources

### Web Performance

1. Google Web Fundamentals: Performance - https://developers.google.com/web/fundamentals/performance
2. Mozilla Developer Network: Performance - https://developer.mozilla.org/en-US/docs/Web/Performance
3. Web.dev: Fast load times - https://web.dev/fast/
4. PageSpeed Insights - https://developers.google.com/speed/pagespeed/insights/
5. High-Performance Browser Networking - https://hpbn.co/

### SEO

1. Google Search Central: SEO Starter Guide - https://developers.google.com/search/docs/beginner/seo-starter-guide
2. Moz: Beginner's Guide to SEO - https://moz.com/beginners-guide-to-seo
3. Yoast SEO: The beginner's guide to SEO - https://yoast.com/complete-beginner-guide-to-seo/
4. Backlinko: SEO This Year - https://backlinko.com/seo-this-year
5. Ahrefs: SEO Basics - https://ahrefs.com/blog/seo-basics/

### General Resources

1. Web.dev: Measure and Optimize - https://web.dev/measure/
2. Google Lighthouse - https://developers.google.com/web/tools/lighthouse
3. Google Search Console - https://search.google.com/search-console/about
4. Google Analytics - https://analytics.google.com/
5. W3C Web Performance Working Group - https://www.w3.org/webperf/


Proven strategies and guidelines for optimizing web performance and search engine optimization (SEO)

Web Performance and SEO Best Practices and Guidelines


---

We're going to build a "save to reading list" feature for the website.

### Pre-requisites

We will need a few things to get started. First, we need to install the React UI Kit. This guide assumes you have a Next.js project set up.

```bash
npm install @stitches/react
npm install @washingtonpost/wpds-ui-kit
```

Let's configure the project to support Server Side Rendering. This is a requirement for the React UI Kit in Next.js. We are following Stitches guide on how to do this. [Seen here.](https://stitches.dev/docs/server-side-rendering). You need to call ‘getCssText()’ in the document head to prevent FOUC during SSR.

```jsx
import React from "react";
import NextDocument, { Html, Head, Main, NextScript } from "next/document";
import { getCssText } from "@washingtonpost/wpds-ui-kit";

export default class Document extends NextDocument {
  static async getInitialProps(ctx) {
    const initialProps = await NextDocument.getInitialProps(ctx);
    return { ...initialProps };
  }

  render() {
    return (
      <Html lang="en">
        <Head>
          <style
            id="stitches"
            dangerouslySetInnerHTML={{ __html: getCssText() }}
          />
        </Head>
        <body>
          <Main />
          <NextScript />
        </body>
      </Html>
    );
  }
}
```

Create a new component file in your "components" directory with the following code:

```jsx
import { styled, Icon, theme } from "@washingtonpost/wpds-ui-kit";
import Add from "@washingtonpost/wpds-assets/asset/add";

export const SaveToList = () => {
  return (
    <Icon size="$200" label="Save to reading list" fill={theme.colors.primary}>
      <Add />
    </Icon>
  );
};
```

Let's walk through each line of code. We will be using the `styled` function to create a styled component. We will also be using the `theme` object to get the current theme. We will also be using the `Icon` component to create an accessible icon.

```jsx
import { styled, Icon, theme } from "@washingtonpost/wpds-ui-kit";
```

The `styled` function takes a component and returns a styled component. It uses [Stitches](https://stitches.dev/docs/introduction) under the hood.

The `theme` object lets us use our Theme tokens with type safety. We can also use the cool "interpolation" syntax to get the current theme. Like so `$primary` will return the current primary color.

The `Icon` component clones the SVG React element and adds accessibility attributes. We can use the `label` prop to set the `aria-label` attribute. We can also use the `size` prop to set the `width` and `height` attributes.

We will use a new asset from our [Assets Manager](/foundations/assets).

```jsx
<Add />
```

Let's create a new button component with the following code. We will use the `Icon` asset and apply the `fill` prop to set the color.

```jsx
import { styled, Icon, theme } from "@washingtonpost/wpds-ui-kit";
import Add from "@washingtonpost/wpds-assets/asset/add";

const Button = styled("button", {
  color: theme.colors.onPrimary,
  backgroundColor: theme.colors.primary,
});

export const SaveToList = () => {
  return (
    <Button>
      Save to reading list
      <Icon size="$200" fill={theme.colors.onPrimary}>
        <Add />
      </Icon>
    </Button>
  );
};
```

```jsx
import { styled, Icon, theme } from "@washingtonpost/wpds-ui-kit";
import Add from "@washingtonpost/wpds-assets/asset/add";

const Button = styled("button", {
  // remove all browser styles
  appearance: "none",
  border: "none",
  // add press effect
  "&:active": {
    transform: "scale(0.95)",
  },
  // give it some color
  color: theme.colors.onPrimary,
  backgroundColor: theme.colors.primary,
  // remove default spacing
  margin: 0,
  // add some padding
  padding: theme.space["050"],
  // add rounded corners
  borderRadius: theme.radii.round,
  // add a uniform box shadow to create a 'border' effect
  boxShadow: "0 0 0 1px currentColor",
  // remove extra space drawn when line height and font size are set
  lineHeight: 0,
  fontSize: 0,
  // add a pointer
  cursor: "pointer",
});

const SaveToList = () => {
  return (
    <Button>
      <Icon size="$200" fill={theme.colors.onPrimary}>
        <Add />
      </Icon>
    </Button>
  );
};

export default function Example() {
  return <SaveToList />;
}
```

### Further Reading

Further reading:

- https://ped.ro/resources/variant-driven-components
- https://ped.ro/resources/why-i-build-design-systems-with-stitches-and-radix
- https://stitches.dev/docs/tutorials
- https://stitches.dev/resources/using-nextjs-with-stitches

Further watching:

- https://www.youtube.com/watch?v=Gw28VgyKGkw


We're going to walk through how to build a feature for the website with our React UI Kit.

React Guide


---

## History

Our journey to Stitches began last year in January with an open discussion on [our community issues board](https://github.com/WPMedia/site-components/issues/584). The discussion topic was "Should we move to a new CSS Framework?" Many commented on loving our flavor of Tachyons and how it lends itself to rapid development especially for visual storytelling. However some commented that we should try a CSS-in-JS solution for our components.

---

## Supporting Community

The discussion continued with a few more comments and we decided to move forward with Stitches as our CSS-in-JS solution. We are still committed to supporting Tachyons for the community. We are going to add our Tokens (Theming!) to Tachyons. It's on our roadmap! Although what we realized during that discussion, we want to explore supporting other CSS frameworks for our commmunity like Tailwind, Styled Components, Emotion, etc by leveraging our Tokens.

---

## Non-negotiables

The open discussion helped us form our non-negotiables for our CSS solution for WPDS.

- [x] Download only used CSS to the browser

- [x] Server side rendering

- [x] Developer experience, fully typed APIs

- [x] Built in API for components/variants

- [x] Built in API for theming

- [x] Using CSS Properties for theming, extensiblity and customization

---

## Stitches - Ahead of the Curve

Stitches checked all of those boxes!

---

## Further Reading

- https://stitches.dev/docs/introduction
- https://stitches.dev/blog/introducing-stitches
- https://ped.ro/writing/why-i-build-design-systems-with-stitches-and-radix
- https://ped.ro/writing/variant-driven-components
- [Stitches demo with Lee Robinson](https://www.youtube.com/watch?t=1471&v=Gw28VgyKGkw&feature=youtu.be)


Learn about our choice of using Stitches for WPDS.

Why are we using Stitches for WPDS?


---

We will review what [WaPo Tachyons](https://tachyons.preview.now.washingtonpost.com/tachyons) is capable of and how it compares with Stitches. We will also review how to write a feature using one or the other to better understand the gaps in Tachyons and how Stitches can fit into them.

---

## Tachyons

[WaPo Tachyons](https://tachyons.preview.now.washingtonpost.com/tachyons) is a CSS framework for rapid development using small atomic CSS classes. It was an answer to the size limit imposed by [AMP](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/style_pages/?format=websites). With that in mind, the team wrote classes for what was needed for the work. This methodology led to eventual gaps in the framework that we will discuss in the next section.

---

## Stitches

> "CSS-in-JS with near-zero runtime, SSR, multi-variant support, and a best-in-class developer experience." From ([Stitches.dev](https://stitches.dev/))

It is fully typed using [CSSType](https://github.com/frenic/csstype) so you can write any CSS you need. There is no limitation by design.

---

## Writing CSS with Ui Kit

There are three ways to write [CSS](https://stitches.dev/docs/api) with Ui Kit using the Stitches API.

### Styled

A function to create a component including its styles and variants. It receives: element or component: a HTML element (div) or a React Component (Component), styles: as many styleObject as you need

```jsx hideNavBar
import { styled, css, Box } from '@washingtonpost/wpds-ui-kit';

const ActionButton = styled('button', {
  // base styles

  variants: {
    variant: {
      primary: {
        // primary styles
      },
      secondary: {
        // secondary styles
      },
    },
  },
});

// Use it
<ActionButton>Button</ActionButton>
<ActionButton variant="primary">Primary button</ActionButton>
```

### CSS

A function to generate class names from a style object. It receives as many `styleObject` as you need.

```jsx hideNavBar
const actionButton = css({
  // base styles

  variants: {
    variant: {
      primary: {
        // primary styles
      },
      secondary: {
        // secondary styles
      },
    },
  },
});

// Use it
<div className={actionButton()}>Button</div>
<div className={actionButton({ variant: 'primary' })}>Primary action button</div>
```

### Box

A component that uses the `styled` function to compose itself. It has all of the props from `styled`. It's a quick way to prototype a component using the `css` [prop](https://stitches.dev/docs/overriding-styles#the-css-prop).

```jsx hideNavBar
import { styled, css, Box } from "@washingtonpost/wpds-ui-kit";

export const Example = () => (
  <Box
    css={css({
      padding: "$100",
      background: "$subtle",
    })}
  >
    Box
  </Box>
);
```


We've written a dedicated blog post about the differences between Tachyons and Stitches.

Migrating from Tachyons to Stitches


## Stitches

The Washington Post Design System utilizes the css-in-js library, [Stitches](https://stitches.dev/), to optimize app performance and dev experience. For more context about why we use Stitches, [check out this post by the WPDS team.](https://build.washingtonpost.com/resources/architecture/stitches#Supporting%20Community)

---

## Stitches functions

Stitches functions make creating and styling components easy. Below, we’ll dive into the functions most useful to a user of our UI Kit, but check out Stitches’ [other functions](https://stitches.dev/docs/api) if you’re curious.

## Styled

The `styled` function is used to simply create React components with styles. The arguments to the function are:

1. either an HTML element or a react component
2. styles

Component variants may also be specified. For example:

```jsx
import { styled, css } from '@washingtonpost/wpds-ui-kit'

// create a new component, 'FancyButton', which modifies a 'button' element
const FancyButton = styled('button', {
	// base styles

	variants: {
		variant: {
			fancier: {
				// fancier styles
			},
			fanciest : {
				// fanciest styles
			},
		},
	},
});

// Use it
<FancyButton>I'm fancy!</FancyButton>
<FancyButton variant="fancier">I am fancier!</FancyButton>
```

## CSS

The `css` function can be used to create reusable styles through the application of a class name or used inline to style individual elements. Here’s an example of inline use, utilizing the already defined `FancyButton` from before:

```jsx
<FancyButton css={{ //base styles, optional variants }}>I'm fancy!</FancyButton>
```

And below demonstrates the application of css through the classname property:

```jsx
const newButton = css({
  // base styles
});

// Use it
<div className={newButton()}>I'm new!</div>;
```

\*\*note: style property names use camel case in these functions (example: `z-index` becomes `zIndex`)

## Keyframes

Another function available in Stitches is the `keyframes` function. Using the keyframe animation technique, Stitches allows the creation of global CSS keyframe rules, which lets transitions be easily reused across code. Below is an example of a simple fading-out animation:

```jsx
import { keyframes } from '@washingtonpost/wpds-ui-kit'

const fadeOut = keyframes({
	from: { opacity: 1 },
	to: { opacity: 0 },
});

// Use it
const fadingInButton = styled("button", {
	'&hover': {
		animation: `${fadeOut} 200ms ease-out`,
    "@reducedMotion": {
      animation: "none",
    },
	}
)};
```

---

## Theme object and tokens

The theme object contains useful token data that can be applied when styling an element. WPDS specifies its own tokens for many attributes, which can be explored throughout the [foundations section](https://build.washingtonpost.com/#Foundations) of our documentation. Tokens can be accessed in code by using the `theme` object, which is is preferred over using the `$` reference symbol because it provides additional checks. For more information about using our theme tokens, check out [this tutorial](https://build.washingtonpost.com/resources/tutorials/how-to-use-our-theme).\
The `const WPDS` is pre-defined in the UI Kit's [`stitches.config.ts` file](https://github.com/washingtonpost/wpds-ui-kit/blob/main/ui/theme/src/stitches.config.ts).

```jsx
const WPDS = stitches.createStitches({
  prefix,
  theme: {
    colors: {
      ...tokens.light,
      ...tokens.staticColors,
      ...tokens.defaultTheme,
    },
    sizes: tokens.sizes,
    ...
  },
  media: { ... },
  utils: { ... },
});

// Use it
const BestButton = styled('button', {
	// use the size token $200, which is equivalent to 2rem or 32px
	marginTop: theme.space["200"],
	// use the color token $primary, which is equivalent to rgba(17, 17, 17, 1)
	// color tokens change automatically when a color theme is applied
	color: theme.colors.primary,
});
```

## Breakpoints

Stitches is also capable of defining breakpoints, which are reusable media queries useful for responsive styling. The WPDS UI Kit supports [a variety of size breakpoints](/foundations/breakpoints) and custom themes, which can be explored in the kit's [`stitches.config.ts` file](https://github.com/washingtonpost/wpds-ui-kit/blob/main/ui/theme/src/stitches.config.ts). The button in the example below would be uniquely styled when the viewport is smaller than `768px`, or `sm`.

```jsx
const WPDS = stitches.createStitches({
  prefix,
  theme: { ... },
  media: {
    sm: "(max-width: 767px)",
    md: "(min-width: 768px) and (max-width: 899px)",
    lg: "(min-width: 900px) and (max-width: 1023px)",
		...
  },
  utils: { ... },
});

// Use it
const VariableButton = styled('button', {
	// Base styles
	"@sm" {
		// small-screen styles
	},
});
```

Note: the `"@dark"` and `"@light"` media queries are responsive only to OS preferences, so styles specified with these will not affect elements based on the theme toggled in the application. To style an element based on local theme, consider stying based on the parent `html` element using the syntax: `[".<className> &"]`. For example:

```jsx
// Adding opacity to an image when local dark mode is enabled.
const StyledImage = styled(Image, {
  paddingRight: "$075",
  [".wpds-dark &"]: { opacity: "0.9" },
});
```

## Utils

Utils allow the creation of custom shortcuts to write certain styling properties. For example, the WPDS ui kit has defined utils `px` and `py`, which affect horizontal and vertical padding, respectively. `px` could then be used in place of `padding-left` and `padding-right` when styling elements. Check out the other utils WPDS supports defined in [the config file](https://github.com/washingtonpost/wpds-ui-kit/blob/main/ui/theme/src/stitches.config.ts).

```jsx
const WPDS = stitches.createStitches({
  prefix,
  theme: { ... },
  media: { ... },
  utils: {
    px: (value: Stitches.PropertyValue<"padding">) => ({
      paddingLeft: value,
      paddingRight: value,
    }),
    py: (value: Stitches.PropertyValue<"padding">) => ({
      paddingTop: value,
      paddingBottom: value,
    }),
		...
  },
});

// Use it
<p css={{ px: "$075", py: "$100" }}>Paragraph with padding</p>
```

---

## Global styles

Another feature of the UI Kit that provides greater consistency is `globalStyles`. [In the `globalStyles` definition](https://github.com/washingtonpost/wpds-ui-kit/blob/main/ui/theme/src/stitches.config.ts#L102), default styles for certain properties are specified by using Stitches’ `globalCSS` function. A `darkModeGlobalStyles` modification is also specified, which alters default color styles in dark mode.

## Dark theme

The WPDS UI Kit currently supports a light and a [dark theme](https://github.com/washingtonpost/wpds-ui-kit/blob/main/ui/theme/src/stitches.config.ts#L94). Using the Stitches function `createTheme`, tokens specified in the `theme` object can be overwritten to create custom themes. In the case of our UI Kit, the dark theme is employed when the breakpoint `dark` is toggled.

---

## Contributing

If your team would benefit from an additional util, breakpoint, or something else, please [reach out](https://build.washingtonpost.com/resources/process/support) to the WPDS team!


Using Stitches to style your projects


---

## The Framework

Our framework is grounded in the principle of thoughtful disruption—balancing the need to inform users versus their primary goal for coming to the Washington Post: Reading and engaging with our content.

- Consider these assumptions when using the user education framework:
- Users only internalize a small part of user education.
- Users are scanning, not reading.
- Users are also likely to dismiss a message before reading.
- Clarity begins on the feature level. User education is additive, but can't do all the work.
- The best messaging experiences are valuable, only when needed, and not overlapping. Be mindful of the greater messaging ecosystem. Are there several messages at this moment? Will if feel spammy?

### Using the framework

1.  **Identify the Use Case**

    - Assess the detail required
    - Assess the level engagement level
    - Determine what type of communication

2.  **Design and Implement**
    - Select the appropriate component: Use our matrix of components to help determine the correct pattern of user education for your specific use case.
    - Ensure consistency in design and messaging with other experiences.
    - Test the implementation to ensure clarity and effectiveness.

<Box
  css={{
    display: "grid",
    marginTop:"$250",
    border: "1px solid $outline",
    gridTemplateColumns: "10% 45% 45%",
    gridTemplateRows: "34px 1fr 1fr",
    gridTemplateAreas: `
      "empty lEng hEng"
      "hDet hDlE hDhE"
      "lDet lDlE lDhE"
    `,
  }}
>
    <Box css={{
    gridArea:"empty",  
     background: "$gray600",  
    borderRight: "1px solid $outline",    
    borderBottom: "1px solid $outline"}}/>
    <Box
    css={{
        display: "flex",
        gridArea: "hDet",
        background: "$gray600",
        borderRight: "1px solid $outline",
        borderBottom:  "1px solid $outline",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>High Detail</span>
    </Box>

    <Box
    css={{
        display: "flex",
        gridArea: "lDet",
        background: "$gray600",
        borderRight: "1px solid $outline",
        borderBottom: "0px",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>Low Detail</span>
    </Box>

    <Box
    css={{
        gridArea: "lEng",
        background: "$gray600",
        display: "flex",
    borderRight: "1px solid $outline",
        borderBottom: "1px solid $outline",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>Passive Engagement</span>
    </Box>

    <Box
    css={{
        gridArea: "hEng",
        background: "$gray600",
        borderBottom: "1px solid $outline",
        display: "flex",
        alignItems: "center",
        justifyContent: "center",
        paddingTop: "$050",
        paddingBottom: "$050",
    }}
    >
    <span>High Engagement</span>
    </Box>
    <Box
        css={{
            gridArea: "hDlE",
            borderBottom: "1px solid $outline",
            borderRight:"1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b>High Detail & Passive Engagmenet</b>
        </div>
        Appropriate for information-dense content that doesn't demand
        immediate user action, but requires careful consideration
        (e.g., in-depth tooltips, instructional guides)
        </span>
    </Box>
    <Box
        css={{
            gridArea: "hDhE",
            borderBottom: "1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b> High Detail & Active Engagement</b>
        </div>
            Best suited for content that requires active user interaction,
            and involves complex information (e.g., detailed onboarding flows,
            multi-step product tours).
        </span>
    </Box>
     <Box
        css={{
            gridArea: "lDlE",
            borderRight:"1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b> Low Detail & Passive Engagmenet</b>
        </div>
        Fits content that is simple and primarily informational without
        requiring much interaction (e.g., notifications, passive alerts).
        </span>
    </Box>
    <Box
        css={{
            gridArea: "lDhE",
            borderBottom: "1px solid $outline",
            display: "flex",
            alignItems: "center",
            justifyContent: "center",
            padding: "$100",
        }}
    >
        <span>
        <div>
            <b>Low Detail & Active Engagmenet</b>
        </div>
        Ideal for interactive content that is easy to grasp,
        but still requires user participation (e.g., quick walkthroughs,
        feature discovery nudges).
        </span>
    </Box>

</Box>

<BR />

---

## Assess the Level of Detail

The level of detail is determined by several factors, primarily based on the complexity of the information, the user's experience level, and how critical the information is to avoid frustration. Consider the following:

1. **Complexity of Information**

   - High Detail: Necessary for complex information involving multiple steps or requiring thorough understanding (e.g., detailed instructions, complex workflows).
   - Low Detail: Suitable for straightforward or simple information, like quick reminders (e.g., single-step instructions, brief notifications).

2. **User Experience Level**

   - High Detail: Required for users new to the application or feature who need comprehensive guidance.
   - Low Detail: Appropriate for experienced users who only need brief reminders or notifications.

3. **Criticality of Information**

   - High Detail: Essential if missing the information could lead to significant issues, errors, or user frustration.
   - Low Detail: Adequate when the information is helpful but not critical to the user's success or safety.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={796.7}
    height={460}
    maxWidth="100%"
    src="/img/resources/guides/user_education_detail.png"
  />
</Container>
<BR />

---

## Assess the Level of Engagement

When designing user education content, consider the level of engagement needed based on user interaction requirements, learning goals, and the urgency of the communication. Here's how to approach it:

1. **User Interaction Requirement**

   - Active Engagement: Required if the communication encourages users to perform actions, make decisions, or interact with features (e.g., product tours, walkthroughs).
   - Passive Engagement: Suitable for informational content that doesn't require user action beyond reading or acknowledging (e.g., tooltips, system messages).

2. **Learning and Adoption Goals**

   - Active Engagement: Necessary when the objective is for users to learn and adopt new features or changes through hands-on interaction.
   - Passive Engagement: Appropriate if the goal is to inform users without requiring immediate engagement with the content.

3. **Frequency and Urgency**
   - Active Engagement: Ideal for messages that are urgent or infrequent and need immediate attention (e.g., critical alerts, onboarding).
   - Passive Engagement: Suitable for regular communications that serve as ongoing support or reminders.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={920}
    height={920}
    maxWidth="100%"
    src="/img/resources/guides/user_education_engagement.png"
  />
</Container>

---

## Determine the type of communication

It's crucial to identify the type of communication you need because it will guide decisions around language, messaging, UX, and more. We've categorized our user education into the following three buckets:

- **First Time User Experience**
- **Support**
- **Growth**

---

### First-Time User Experience (FTUX)

FTUX refers to a user's initial interaction with a product or feature. The experience should provide a smooth, engaging and informative introduction to the benefits and features. User education is often useful to show the value prop of our ever-evolving product offerings.

<BR />

**Common FTUX experiences include:**

- Onboarding
- Product Tours
- New Feature Announcements
- Feature Walkthroughs

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={398.28}
    maxWidth="100%"
    alt="A image with three items showing examples of First time user experience. From the left Product tours, Middle New feature annoucements, and last Feature walk-throughs"
    src="/img/resources/guides/user_education_ftux.png"
  />
</Container>

#### Considerations

**UX writing & content design**

- To create the most impactful experience, keep it as simple as possible, or consider if it's needed at all. If the goal is to teach a feature or interaction, make sure you're not leaning on the user education to fix unclear design.
- Many people close tutorials or similar without using them. The lengthier to tutorial, the more drop-off.
- If your user education has multiple steps, place them in order of importance to goals.
- Consider visuals or animation to improve comprehension and engagement.

---

### Support

Support provides users with contextual information and guidance, making it easier for them to understand and effectively use the product's features.

<BR />

**Common support experiences include:**

- Added context (information tooltips)
- System communication (e.g. server timeout and errors, form errors, successful interactions)
- Account messaging (e.g. status of payment, changes to policies, and terms)

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={268.31}
    maxWidth="100%"
    alt="A image with three items showing examples of First time user experience. From the left Product tours, Middle New feature annoucements, and last Feature walk-throughs"
    src="/img/resources/guides/user_education_support.png"
  />
</Container>

#### **Considerations**

**UX writing & content design**

- When providing system-level information (error, confirmation, info messages, etc.), be clear, concise and helpful.
- If it's an error, tell users what happened, why it happened, how to fix it and the next best option. See more details on writing error messages
- Use information tooltips to add non-critical context that helps users or builds trust. For example, “Why is this AI feature here?”
  **Semantic Color**
- Use our semantic colors for error, success, signal, and warning messages. These colors reinforce visual cues and help users quickly understand the context of the communication.

---

### Growth

Growth helps to expand a product'''s user base by encouraging user engagement, sharing, and retention through targeted messages and incentives.

**Common growth experiences include:**

- Upsell Visuals & Interactions
- Account/Subscription Upgrades
- Feature Adoption Campaigns

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={840}
    height={336.27}
    maxWidth="100%"
    alt="A image with two examples on the left account/subscription upgrades and on the right Driving a feature adoption"
    src="/img/resources/guides/user_education_growth.png"
  />
</Container>

#### Considerations

**UX writing & content design**

- User education can be useful to show our ever-evolving offering of features. Be thoughtful if the feature you're drawing attention is actually cool and new in the user's mind. Consider if the user education will feel helpful or spammy.
  -Make value proposition very clear.
- Understand this is an exchange. In exchange for my time, privacy or money, I will receive **\_\_\_**.
- Keep it short.
- Keep it simple. In general, only ask the user to make one choice at a time.
- Have the button/CTA be the appropriate level of commitment for the step. For example, “See subscription options” might come before “Continue to payment.” Example: See Google hotel booking case study
- The text underneath a button is called “trigger text”. It's often used to help someone make a decision, for example “Cancel anytime.”
  **Subscription Color**
- Use our designated subscription color whenever the communication specifically addresses subscription-related topics. This ensures visual consistency and reinforces the importance of subscription messaging.

---

## Selecting the Appropriate Component

We've aligned key components with their inherent interaction patterns within our framework for thoughtful disruption in user education. Each component offers different levels of support for handling complex details. Be sure to consult the component documentation for specific best practices.

<Container css={{ background: "transparent" }}>
  <InlineImage
    width={920}
    height={920}
    maxWidth="100%"
    alt="A image with that place components on a matrix the y axis being level of detail from low to high and x axis being engagement from passive to active."
    src="/img/resources/guides/user_education_matrix.png"
  />
</Container>


This guide is an introduction to our user education framework. By the end of this document, you will have learned the following - Evaluate user education needs based on detail, engagement, and communication type. Apply best practices to select the right components and design effective user education experiences.

User Education 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.

Guides