Design tokens are special variables used to maintain a scalable visual system for UI development and brand consistency. Cedar design tokens store the visual design attributes that define the foundation of REI’s visual language, including color, typography and spacing.
Design tokens are key-value pairs. For example:
Key: value; cdr-text-primary-lightmode: #292929;
- The key name defines the usage or how to apply the value to a specific context, such as using text on a light background
- The key stores visual design attributes
- The key replaces hard-coded values, such as hex values for color or pixel values for spacing
- Contract of intent will not change when a variable value is updated over time
Contract of Intent
- Tokens are versioned and maintained by the design systems team
- Consumers are required to stay within one major version of the current release
Improved UI Development
- Promotes greater visual consistency and maintainability (when there are changes to brand elements)
- Aligns with brand standards
- Consumers 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 by consumers
- Teams can consume these changes from SEMVER releases to our supported packages
Brand Consistency on Any Platform
- Extends the distribution of the REI visual language across platforms
- Ensures brand consistency across all digital channels
- Designers and developers have access to tokens when creating custom components for their applications (within brand standards)
Tokens can be used by teams:
- To supplement components when designing page layouts
- To create custom components that are visually aligned to the REI brand styles
- To create new components that can be contributed back to the system
- When there are technical limitations to consuming components
Don’t Use When
- Don’t use tokens to make modifications to an existing component. Instead, submit a request using the Feature Request Form for an existing component
- Don’t use tokens to only access a value or values. Instead, create a new token in the shared-tokens repo that meets your specific semantic use case
Questions about when to use tokens? Ask the Cedar team in #cedar-user-support
Is “cdr-color-text-primary-lightmode” a token?
|Is “cdr-color-text-primary-lightmode” used in several components or layouts?||Yes|
|Is it clear where this is to be used based on its name?||Yes|
|If I apply this token in my component and use it to specify the color for primary text will it still be used for the primary text color in a future design update?||Yes|
|Is this token used for multiple elements and NOT specific to one element?||Yes|
Result: All of the criteria are met and so “cdr-color-text-primary-lightmode” qualifies as a token.
Is “cdr-color-background-button-secondary-disabled” a token?
|Is “cdr-color-background-button-secondary-disabled” used in several components or layouts?||Yes|
|Is it clear where this is to be used based on its name?||Yes|
|If I apply this token in my component and use it to specify the background color for a secondary button when disabled will it still be used for the secondary button in a future design update?||Yes|
|Is this token used for multiple elements and NOT specific to one element?||No|
Result: The fourth criteria is false so “cdr-color-background-button-secondary-disabled” does not qualify as a token. Instead it is considered an UI Element variable that is specific to buttons.
Is “easily-excited” a token?
|Is “easily-excited” used in several components or layouts?||Yes|
|Is it clear where this is to be used based on its name?||No|
|If I apply this token in my component and use it to specify a color will it still be used for that color in a future design update?||Yes|
|Is this token used for multiple elements and NOT specific to one element?||Perhaps but it is not used consistently|
Result: Only two criteria are met and so “easily-excited” does not qualify as a token.
Naming Structure for Tokens
The naming structure for 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
- Mode: Defines tokens based on themes, such as a dark or light background
The below tables for the naming structure show that levels will be skipped when not used.
How to Use Tokens
- A base requirement for accessing Cedar tokens and using them in designs and wireframes is that you are able to use Sketch version 53.2
- Toolkits are platform specific. If designing for the web, use the UI Web Toolkit
- Tokens are available in Cedar’s UI Toolkit and found on the Tokens page
- When using tokens, it’s your responsibility to pass the entire token name to the developer during the design hand-off process—this can be through automated or manual methods
A base requirement for using Cedar tokens is that you are able to consume and maintain packages through the following development processes:
- Web consumers:
- Your project can compile CSS variables
- You can import NPM packages
- Native iOS consumers using CocoaPods
- Android consumers using Android package manager
This repository follows SEMVER practices and will notify users of changes and updates on the #cedar-user-support Slack channel.
Adding Tokens to the Repository
The number of tokens Cedar provides is kept small intentionally as it is critical for a token to meet all requirements based on the above criterium prior to being added to Cedar’s Token list.
Ensure that the token meets the following requirements:
- Token is used in several components or layouts
- Token is used for multiple elements and NOT specific to one element
- Token name will continue to have the same semantic meaning in future releases
- Token name follows platform requirements:
- Web: Uses Kebab case. For example, cdr-color-background-dark
- iOS: Uses Pascal case. For example, CdrColorBackgroundColor
- Android: Uses Snake case. For example, cdr_color_background_dark