Skip to main content

Design Tokens

In a design system we often speak of small components as "atoms", and perhaps complex/compound components as "molecules". Sticking with that metaphor we could say that tokens are "quarks". They're the smallest building block of the design system, representing individual colors, font sizes, spacings, etc.

You can think of tokens as variables that are repeated throughout the component code, and also made available to be used in application code as well. While values may be different between brands, their contextual meanings will stay the same.

Examples:​

  • Background Color Primary
  • Font Family Primary
  • Font Size Heading
  • Padding Large

@curology/ui-tokens​

Squeeze's design tokens live in their own package and are defined in JSON files that adhere to Amazon's Style Dictionary format. There is one set of tokens shared between brands, and brand-specific tokens for Curology and Agency.

These tokens are technology agnostic. Although today they're only used to generate web-specific CSS, they could be used to create tokens for other platforms as well.

When @curology/ui-tokens builds, brand-specific stylesheets and JS files are exported. The JS files are used by this documentation site to generate a list of available utility CSS values, and the stylesheets expose global CSS Custom Properties that are imported by applications to apply values to Squeeze's custom Tailwind Config.

@curology/ui-styles-web​

This package creates custom Tailwind and PostCSS configurations for using when building a web UI. It is consumed by @curology/ui-components-web to build its components, but can be integrated into any web project.

The tokens exported by @curology/ui-tokens are referenced in a custom Tailwind configuration that is used by Squeeze and by applications that implement Squeeze. To create a layer of abstraction that allows for the same Tailwind classes to be used across multiple themes, Squeeze uses CSS Custom Properties to provide values for Tailwind classes.

Importing different token stylesheets means different values will be used by Tailwind when applying classes. This is the basis for how themes are applied in Squeeze.

For example, the color of a primary button is set by applying a Tailwind class of cur-bg-surface-brand. Instead of setting the background color of a button to rgba(101, 84, 232, 1) directly, we set it to var(--cur-bg-surface-brand). The value of --cur-bg-surface-brand is set by importing @curology/ui-tokens/curology that contains the value for that token. Importing @curology/ui-tokens/agency would change the value of that token to a different color.