Skip to main content
Styles

Design tokens

Draft

Tokens are a set of foundational design decisions represented as reusable data. These tokens are shared across all platforms, iOS, Android, and Web, and control the entire visual part of our design system.

Anatomy​

Each design token has a unique name and its corresponding value. This name/value pairing is similar to a dictionary data structure found in engineering, where a key is associated with a value, and the key/value pair can be used to store and retrieve data.

RequiredName"color-action-primary"
OptionalType$color
RequiredValue #266EF1
OptionalDescription"Primary interactive color"

Name (required)​

The most integral part of a design token is its name — it is how it will be known and referenced across all platforms.

Naming is inherently complex — you can always reference the naming convention of each token type on its respective documentation page for more details.

There are two main properties when thinking of how we construct the name of a design token, its Tier and Type.

Type​

There are established formats and best practices for naming we follow based on the token type (color, typography, sizing, etc.) to ensure high comprehension and usability for designers and developers alike.

Tier​

Depending on how context specific a design token is, its naming can vary. For our most foundational tier, naming will often consist of the token type, followed by a numeric or ordinal scale. The more narrow the token's intended usage is, the more precise its name will be.

Type (optional)​

While design tokens can represent any design decision, there are a handful of established token types in W3C that summarize the purpose of the token and are often referenced by our tooling.

NameDefinition
ColorColor values, including both named colors and hexadecimal values.
DimensionNumeric values with units, such as pixels or ems.
Font familyFont families, such as "Inter".
Font-weightFont weights, such as "bold" or "normal".
DurationTime durations, such as "0.5s" or "2ms".
Cubic BezierEasing functions with cubic Bezier curves.
NumberSimple numeric values without units.

Value (required)​

A design token's value is the specific data that defines a design property and is associated with a particular token name. Depending on the token and its complexity, there are several types of data supported:

Data types​

Data typeDescription
StringA sequence of characters that can represent text, such as font or color names.
NumberA numerical value that can represent various design properties, such as size, spacing, or duration.
ColorA value that represents a specific color, typically in hexadecimal or RGB format.
BooleanA value that is either true or false, and can be used to represent binary properties such as whether an element is visible or hidden.
ObjectA collection of key/value pairs, which can be used to represent more complex design properties, such as gradients or shadows.
ArrayA collection of values of the same data type, such as a list of font sizes or spacing values.
NullA special value that represents the absence of a value.

Composite tokens​

The last tier of tokens supported is a composite — a token that combines or derives its value from one or more child tokens. Composite tokens are created by specifying a calculation or formula that references other tokens as input values and uses those values to produce a new output value.

There are two main use cases for composite tokens — supporting calculation-based value reference (such as dynamic sizing of a component) and defining more complex component tier tokens (card, tile, etc.)

Composite types​

W3C currently recognizes 6 composite token types.

TypeDefinition
StrokeComposite of an array of widths (dashArray) and a string to define the shape (lineCap) property.
BorderComposite of a color token, width number, and style object (usually a stroke composite).
TransitionComposite of duration, delay, and a timing array.
ShadowComposite of a color token, X and Y offsets, blur, and spread.
GradientComposite of color tokens and a finite amount of positions they take.
TypographyComposite of a font family, size, weight, letter spacing, and line height.

Group vs composite tokens​

Composite tokens are not to be mistaken for group tokens. A group token does not have a value of its own but simply serves as a container or grouping mechanism for related tokens. Group tokens can be used to organize related tokens by category or context, such as color tokens for a specific brand or typography tokens for a specific component.

Description (optional)​

Beyond name and value, a design token can have a description property to provide additional information to the user. It's most often used to:

  • Provide purpose & context
  • Provide usage guidance
  • Any relevant design considerations
  • Caveats & Limitations

W3C Definition & Format​

"Design tokens are a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies. They help establish a common vocabulary across organizations." — W3C Design Tokens

We aim to be as close to the proposed W3C design token format and follow best practices, however, we will be holding off on doing a migration to achieve full compliance until its official release.

Resources​

Tiers​

Design tokens follow a 3 tier model based on whether the token stores an option or a decision. Each tier is referenced by the one above it (refer to as aliasing).

color-blue-600
color-action-primary
button-bg-default
input-border-focus
color-text-info
badge-text-info
alert-text-info
primitive layersemantic layercomponent layer

Primitive tokens​

Primitive tokens store all the raw data in a platform and usage-agnostic way. In most cases, this level of tokens is not intended for standalone usage and serves as a foundational level of abstraction.

File location: packages/tokens/src/primitive/

color-gray-50       →  #F3F3F3
color-blue-600      →  #266EF1
color-red-600       →  #DE1135
spacing-4           →  4px
spacing-16          →  16px
radius-sm           →  4px
radius-md           →  8px
shadow-sm           →  0 1px 4px hsla(0, 0%, 0%, 0.16)
motion-duration-fast →  100ms

Semantic tokens​

A semantic token, also known as an alias token, is an abstraction layer that reflects the usage of a value in the UI instead of the literal value.

File location: packages/tokens/src/semantic/

color-background-default     →  {color.white}        →  #FFFFFF
color-text-default           →  {color.gray.900}     →  #282828
color-text-subtle            →  {color.gray.600}     →  #727272
color-action-primary         →  {color.blue.600}     →  #266EF1
color-action-primary-hover   →  {color.blue.700}     →  #175BCC
color-action-destructive     →  {color.red.600}      →  #DE1135
color-border-focus           →  {color.blue.500}     →  #068BEE
color-feedback-success-bg    →  {color.green.50}     →  #EAF6ED
spacing-component-md         →  {spacing.12}         →  12px
radius-component-md          →  {radius.md}          →  8px
shadow-component-sm          →  {shadow.sm}          →  0 1px 4px ...

Component-specific tokens​

Component-specific tokens are primarily found in our codebases and not so much in Figma. Their primary role is to represent the properties associated with a component.

Unlike the previous two tiers, these tokens are self-contained, meaning modifying the underlying value of the token will not affect anything outside the component it's used in.

File location: packages/tokens/src/component/

button-bg-default    →  {color-action-primary}
button-bg-hover      →  {color-action-primary-hover}
button-text-default  →  {color-action-primary-text}
input-border-default →  {color-border-default}
input-border-focus   →  {color-border-focus}

Principles​

Shared language​

Design tokens provide a common language between designers and developers.

Consistency​

Remember that it takes a long time to cement a consistent "feel" with our users, but it takes very little to break it. Design tokens ensure consistency in our design system, connecting each element to a predefined style and, therefore, a design token.

Reusability​

Design tokens provide a predefined set of options that can be applied to multiple use cases across our system, driving system adoption on the subcomponent level.

Using raw values directly in code is poor practice for maintenance and future changes, mainly because we support themes and accessibility features like Dark Mode. Proper tokens allow themes to work seamlessly across multiple platforms -- iOS, Android, and the Web.

These styles have been defined with a system in mind; the moment you deviate from them, you break this system. By adhering to this system instead, you help consolidate a distinctive look & feel driven by our brand guidelines.

It's your job as a designer to reinforce the consolidation of a single voice in every detail of your work.

Supported types​

Arch UI defines tokens across 8 categories. Each category has its own foundation page with detailed values and usage guidance.

Color

A two-tier system of primitive palettes and semantic tokens that keeps every surface, text, and border themeable without touching component code.

Typography

Arch typography is flexible and modular and can be used in various ways. Below are the principles behind how our type system was created and examples of how it can be used.

Icons

Our icon system is built for clarity and consistency. It aims to be bold, communicative, and functional, complementing typography and fitting naturally within every component.

Spacing

Arch UI leverages standard sizes and spacing created from increments of 4. This provides consistent sizing and components that snap into place.

Layout grids

We use layout grids to ensure that our content aligns properly on the page.

Corner radius

Arch UI allows for rounded corners to a variety of components. For simple reference, the metric values for corner radius are 16, 12, 8, and 4. These radius metrics are dependent on the size of the component that it is applied to.

Elevation

Elevation provides cues about the surface depth and stacking order of elements in an experience.

Motion

Tokenised duration and easing values that communicate relationships, provide feedback, and guide attention cohesively.

Accessibility

WCAG 2.1 AA conformance out of the box — semantic HTML, keyboard support, and screen reader compatibility in every component.