Design tokens

Variables storing REI's visual design attributes

Design tokens represent elements of style, the core design decisions that make up a brand. When these design decisions are given a name and paired with a corresponding code value, you have a token. Tokens are conceptual by nature, replacing hard-coded values with a meaningful layer of common language that can easily deploy across platforms and products.

Cedar tokens store the visual design attributes defining REI’s visual language. These include attributes for color, typography, spacing and more. Using them creates consistency when designing at scale. ::

Improved UI development

Tokens are aligned with brand standards to ensure consistency across all digital channels and platforms. Teams can stay in sync with any changes to the visual language with minimal impact to the code.

Ease of maintainability

Tokens can streamline redesign processes when the Cedar team updates a value (such as with a new typeface or color hex value). The tokens do not need to be changed in code. Teams can consume these changes from SEMVER releases to our supported packages.

Extensibility

Designers and developers have access to design tokens when creating custom components for their applications (within brand standards).

When to use

  • Supplementing components while designing page layouts
  • Creating custom components that are visually aligned to the REI brand styles
  • Creating new components that can be contributed back to the system
  • There are technical limitations to consuming components

When not to use

  • Making modifications to an existing Cedar component—instead, come talk to us during weekly office hours or message us on our Slack #cedar-user-support channel
  • Accessing a value or values when the token name doesn’t match the application—instead, create a local variable in your project or hardcode the desired value

As a designer

When you create a new file in Figma, token libraries are automatically available in the Assets panel. These libraries contain color, type, spacing, prominence, and icon styles that correspond to Cedar tokens.

As a developer

A base requirement for using Cedar design tokens is your ability to consume and maintain packages through these development processes:

For web:

  • Compile CSS variables (optional)
  • Import NPM packages

For native iOS:

Import CocoaPods.

How to consume tokens

First, install the tokens package.

Next, you can import tokens in your needed format.

npm install --save-dev @rei/cdr-tokens

  • SCSS variables at dist/scss/cdr-tokens.scss
  • LESS variables at dist/less/cdr-tokens.less
  • JS as both commonJS and ES module at dist/js. Also noted in package.json as main and module respectively
    • dist/js/cdr-tokens.common.js
    • dist/js/cdr-tokens.esm.js

GitHub repo

Once you’ve installed the tokens package, you’re ready to dive into the GitHub repo for Cedar tokens.

Using Cedar design tokens

SCSS example:

@import '@rei/cdr-tokens/dist/rei-dot-com/scss/cdr-tokens.scss'; /* import the design tokens file */
.your-default-text-class {
  /* use mixins to apply many properties at once */
  @include cdr-text-default;
}
.your-other-default-text-class {
  /* using SCSS placeholder selectors instead of mixins can optimize your final CSS output */
  @extend %cdr-text-default;
}
.your-other-text-class {
  /* use scss variables if you need to apply specific properties */
  color: $cdr-color-text-error;
}

LESS example:

@import '@rei/cdr-tokens/dist/rei-dot-com/less/cdr-tokens.less'; /* import the desogn tokens file */
.your-default-text-class {
  /* use mixins to apply many properties at once */
  .cdr-text-default();
}
.your-other-text-class {
  /* use variables if you need to apply specific properties */
  color: @cdr-color-text-error;
}

JavaScript example:

import { CdrBreakpointLg } from '@rei/cdr-tokens'; /* import the design tokens file */
let screenWidth = window.innerWidth || 0;
// Detect Large Breakpoint
if (screenWidth >= CdrBreakpointLg) {
  // Do Something
}

This repository follows SEMVER practices and will notify users of changes and updates on the #cedar-user-support Slack channel.

  • Tokens are versioned and maintained by the design systems team
  • Consumers are required to stay within one major version of the current release
  • Contract of intent will not change when a variable value is updated over time

The naming structure for design tokens follows:

  • Category: Top level that contains foundational elements such as text, color, spacing
  • Sub-Category: Describes and narrows category for token. For instance, color-text will define a color for text and can be used for icons
  • Item: Continues to narrows usage for token. For example, if text is a property, the item could be form to indicate text used in a form control
  • Sub-Item: Describes and narrows category for token. For instance, form could be modified by input
  • Variant: Describes prominence or state for a token
  • Size: Describes size for a token, if applicable

Review this table to see how the naming structure levels will be skipped when not used.

CategorySub-CategoryItemSub-ItemVariantSize
colortextinputlabel
colorbackgroundprimary
textheadingserif800