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


---

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


---

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).

```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`,
	}
)};
```

---

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


---

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

Resources

Release Notes

Guides

Coding a page

Contribute a Component

Figma Guide

Migrating to our new palette

React Guide

Why are we using Stitches for WPDS?

Migrating from Tachyons to Stitches

Using Stitches to style your projects

Zeplin Guide

FoundationsChevron Icon

ComponentsChevron Icon

ResourcesChevron Icon

Resources

Release Notes

Coding a page

Contribute a Component

Figma Guide

Migrating to our new palette

React Guide

Why are we using Stitches for WPDS?

Migrating from Tachyons to Stitches

Using Stitches to style your projects

Zeplin Guide