A step-by-step guide to making a page using Next.js and UI Kit.

Coding a page

## Video tutorial

<YoutubeEmbed videoid="wYCuVCa5uek" />

In this tutorial, we will learn just how our theme tokens work and interact with our greater color palette. You will understand why you would use a theme token over just using the same color token. Theme tokens are powerful and will help define how we abstract intention from color in the future as we grow.

How to use theme tokens?

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

 

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

 

### Old convention → New convention

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

 

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

Foundations

Components

Resources

Release Notes

Welcome

What's new

Getting started

Foundations

Components

Guides