Design tokens in the system

There are a lot of commonalities between a designer’s design system and developer’s theme.json. Knowing what all could be defined in your design system which developers can readily use saves time and effort.

Color palette

The theme.json supports as many colors as the design system needs, but this does not mean we can bloat it with colors that are not used or that should not be in the file.

Following is the list of color definitions a design system should have: 

1. Primary, secondary, tertiary and accent colors
2. Text and background color combinations
3. Feedback colors: info, success, warning, error

An important consideration while designing the palette is to keep the colors (and color combinations) accessible. A designer should aim for WCAG Compliance of at least AA. Also, WordPress supports gradients in the theme.json file, so feel free to add gradients to the design system.

One of my favorite examples for a styled system palette is Chakra UI’s default color palette. Figure 2.16 shows the gray swatch ranging from 50 (lightest) to 900 (darkest). 

Typography

WordPress’ theme.json also supports typography. We can add font sizes, font weights, font families, etc. 

Following are the typography-related settings a design system should have and theme.json supports.

1. Heading and body text styles
2. Font size and line height scales
3. Font weight variations
4. Special typography styles (e.g., for quotes, captions)
5. Responsive typography settings (see: Handling Responsive Designs)

Some users may be accessing the website in languages like Arabic, therefore it may also important to add support for text directionality, i.e. RTL / LTR.

Figure 2.17 shows a simple typography scale ranging from small (S) to extra large (XXL). You may notice that we are not using pixels (px) but instead we use rem (16px = 1rem); however, this is not a requirement for theme.json, it supports all the units.

Spacing

For consistent spacing, a design system needs consistent spacing. WordPress also supports spacing tokens in the theme.json.

We can add following tokens in our design system:

1. Spacing values
2. Margin and padding values
3. Inter-block gap

A designer should aim to have consistent spacing throughout the design system. Spacing scale can either be additive or multiplicative. We can define the addition/multiplication factor, the medium value, number of steps, and unit.

In Figure 2.18, you can see a multiplicative spacing scale. The scale values are: 0rem, 0.13rem, 0.25rem, 0.5rem, 1rem, 2rem, 4rem, 8rem.

In Figure 2.19, you can see an additive scale. The scale values are: 0rem, 1rem, 3rem, 5rem, 7rem, 9rem, 11rem, 13rem.