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

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

{" "}

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

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

Learn everything you need to know about the new WPDS

Foundations

Components

Resources

Release Notes

Welcome

Latest resources

Getting started

Foundations

Components

Guides