
---

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


Why are we using Stitches for WPDS?

<Alert dismissable={false} variant="information">
 Note: 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.

 

---

## Code

All components must follow a predefined design spec. Without a design spec, development can not occur. If you are interested in a component not in our backlog, 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 it's
 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 (AccordionRoot).
3. We should avoid using any DOM APIs that are not supported by evergreen browsers.
4. We should should allow modification of styles via the css prop using our tokens (component (locally scoped and global) and theme).
5. We should use our theme tokens to style our components.

### Ready to Code

1. Review the components of our roadmap. The components are listed in the order of priority. Find a component that is not already assigned to a contributor(s). The components already have design & code specs along with a JIRA ticket. Please review them with your team before you start.If you are not sure, please ask a question on our community Slack channel.

2. Now that you have reviewed the specs and the JIRA ticket, please reach out to the Core team on our Slack channel. We're review the specs and the JIRA ticket and will assign the ticket to you.

3. You are now ready to start contributing. Review the component design resource post for how we design components. Now that you have reviewed our component design architecture, open the codebase up and review the contributing guidelines. We have a way to stub out a new component using some boilerplate code (`npm run new-component <component-name>`).

4. Once you're in a good spot for rubber duck session, reach out to a team mate. We want you to get the most out of the UI kit. This is a great opportunity to learn and grow from others who might not be familiar with the UI kit. This is not a place for a formal code review. This is a safe space for you to receive feedback and ask questions.

5. Once you're happy with your work, please submit a pull request to the UI kit repo. Please include a link to your JIRA ticket. The core team and contributors will be notified and will review your pull request.
6. Once your pull request is approved, we will begin the documentation process with you. As a contributor, you will be responsible for the documentation process. Please review the component documentation for how we document components.

7. Now the component has been documented. The component is ready to be shipped. Please review the releases resource for how we release components. We will be releasing new components on a monthly basis.

8. Our new component is live to the world! You are expected to commit to two weeks of support and triage. Please review the support process here.

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" />
</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.

 

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

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"}>
 Note: 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>

 

Before getting started and reviewing all of new beautiful colors we need 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 of their precieved lightness according to a white background. While that may have worked at one time we have long since out grown the naming convention.

 

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

 

---

## 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. **Inconsistency**
 -- 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 another would be using `pale`.

2. **Unable to scale**
 -- The second problem was our inability to grow our color scales. For example how do you scale and 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 use a more scalable approach.

3. **Confusing in other contexts**
 --Lastly there is the problem of naming something in precieved lightness against a given background. Our old color tokens used the target background of white and all precieved lightness was measured against that white background. The problem becomes when we change that background to maybe a dark context the color light becomes confusing when its the darkest color. As we want our colors to be adaptive using the same contrast across different contexts precieved lightness was not something we could use.

### The resolution

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

---

## Phase 1: Translation

If you are a early adopter of our new design system you have already been using our new color token naming convention. This phase is called a transition because our color tokens did not disrupt or add and new colors to our legacy system. We simply translated the previous tokens to a normalized color scale. This allowed for us to provide the run way to begin to scale our color scales accordingly and avoid 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>

 

### Old convention → New convention

<Alert dismissable={false} variant={"warning"}>
 Note: all other subs color were depracted in this transition as there
 was uncertainty on which colors would remain after the final color
 consilidation 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 evolution of our color palette is the introduction to our unfied color palette. This palette was worked across the orginzation with many different departments. Our main goal with this palette is to unifiy and remove the variance in color that we find throughout our product at large.

### Which colors changed in phase 2?

 

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

 

#### Vivid blue

<Alert dismissable={false} variant={"error"}>
 Note: 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>

 

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

 

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

 

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

 

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

 

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

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

---

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're written a dedicated blog post about the differences between Tachyons and Stitches.

Migrating from Tachyons to Stitches

---

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

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

Zeplin Guide

## Cycles

- Bug fixes are released in the form of a patch release. This is the most frequent release type. A patch release is a release that fixes a bug in a token or a component (design or in code). We ship patches on a weekly basis. For example, "1.0.1" is the first patch release.

- Feature releases are released in the form of a minor release. This is the second most frequent release type. A minor release is a release that adds to our tokens or components (brand new components, tokens too) (design or in code). We ship minor releases on a monthly basis. For example, "1.1.0" is the first minor release.

- Major releases are releases that add new features to the platform. We ship major releases on a quarterly basis. For example, "2.0.0" is the first major release.

<InlineSVG
 path="/img/process/release/release-diagram.svg"
 width={400}
 height={200}
/>

##

Components are released batches but only components with full documentation are fully supported. Any other components that are released in the batch without docs will be consider in draft and will be indicated on the doc site as draft. Those will not be fully supported until official release.

Releases


### Support channels

- Slack channel (#wpds)
- GitHub issues

---

## Change/request

So you have an idea? Great, we love to hear it! Our design system aims to listen to all of the needs and ideas of our community of adopters. The team will work together with you to determine the result of the idea submitted. If you are interested in contributing, read more about [our process.](resources/guides/contribute-a-component)

### Using our slack workflow

1. Head over to our #WPDS slack channel where you will kick off your idea!
2. In the channel, type /change or /request, and you will see the option to submit an Idea to DS
3. Now, a form will open up with some questions. Please be as detailed as possible to the best of your knowledge.
4. Hooray! You submitted an idea. The WPDS team will be notified, and now it is open for public discussion across many teams that use WPDS. The team will generate a ticket and prepare it for the next steps of our workflow.

## Not at the Washington Post?

Contact us at wpds@washingtonpost.com


Support

<Alert dismissable={false} variant="information">
 Note: We reevalute our supported platforms at the end of our fiscal
 year.
</Alert>

 

## Browsers

We support the following browsers (up to the latest 2 stable versions):

- Google Chrome
- Apple Safari
- Mozilla Firefox
- Microsoft Edge

 

## Server environments

We support Node.js 14 and as far back as Node.js 12.

 

## React

We are researching support for React 18.

- 16
- 17

 

## React frameworks

We are open to adding more React frameworks here. Contact us through our [support](/support) channels.

- Next.js 9.3.3
- Next.js 10+
- Next.js 11+
- Next.js 12+

 

## Typescript

Ui Kit requires a minimum version of TypeScript 3.8. This aims to match the policy of DefinitelyTyped, with the support of the versions of TypeScript that are less than two years old.

Ui kit provides support for these platforms

Supported platforms

## Video tutorial

<YoutubeEmbed videoid="ocTg0ZLvE3o" />

---

## Written steps

### Before starting

Slots are not an actual componet you will find in our coded design system but rather a figma only component that's only purpose is to be swapped out for a pattern, or local component you are designing. When you see a slot either by how its labeled or its name in the layer of a component you can be sure it is a signal for you to replace it with your own local component.

### When to use

Slots are used to avoid having to detaching a component to access nesting content inside of it. For example a tooltip or accordion can hold a lot of different type of content. Rather than the figma component accounting for ever possible variation it is better to just have slot. This then allows for infinite possiblities without having to detach at all.

### The steps

1. First be sure that the component either has a slot by name or you have asked if it is okay to replace.
2. Create your local pattern either using our library of components or just our foundaitons like our typography tokens. This could be anything a headline with a blurb or a image with a headline.
3. Be sure to frame the entire pattern and name it appropriately.
4. Add an auto layout to the frame and convert it to a local component.
5. Select the slot in the component and replace it with the local component.
6. Done!

### Common pitfalls

Sometimes things do not look right when you replace the slot if this is the case check the following:

- Does you component have a auto-layout and is it position correctly.
- Check the nested version of your component and be sure the it is sized appropriately either fill-container or hug-contents.

Slots is a new concept that you will find in our figma ui-kit. It empowers you to nest and build out paterns with our components without detaching. Follow along on this tutorial where you will learn all about slots.

How to use slots?

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

<YoutubeEmbed videoid="cODayPp8b_U" />
 

**Chapters:**

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

 

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

Learn everything you need to know about the new WPDS

WPDS v1 - Design Workshop

{" "}

## What we learned

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

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

 

---

## The workshop video

<YoutubeEmbed videoid="e_jzDfTdjow" />

Continuing our deep dive in our new design system.

WPDS v1 - Design Workshop 2

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

<YoutubeEmbed videoid="CN-vbXz0asI" />

WPDS v1 - Developer Workshop

## What's happening

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

 

## Topics discussed

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

 

<YoutubeEmbed videoid="pDQK-UJ2LJQ" />

Foundations

Components

Resources

Release Notes

Resources

Architecture

Why are we using Stitches for WPDS?

See all entries

Guides

Contribute a Component

Figma Guide

Migrating to our new palette

React Guide

Migrating from Tachyons to Stitches

Zeplin Guide

See all entries

Process

Releases

Support

Supported platforms

See all entries

Tutorials

How to use slots?

See all entries

Workshops

WPDS v1 - Design Workshop

WPDS v1 - Design Workshop 2

WPDS v1 - Developer Workshop

WPDS v1 - Developer Workshop 2

See all entries