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

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

<BR />

<Container caption="Example of tokens named by precieved 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. **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>

<BR />

### Old convention → New convention

<Alert dismissable={false} variant={"warning"}>
  <b>Note:</b> 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?

<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


---

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

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

Foundations

Components

Resources

Release Notes

Guides

Contribute a Component

Figma Guide

Migrating to our new palette

React Guide

Migrating from Tachyons to Stitches

Zeplin Guide