Skip to main content

Tokens Overview

An introduction to design tokens in the Abyss Design System.

Tokens overview

Introduction & overview​

What are design tokens?​

Design tokens are the variables of a design system. They contain UI data such as colors, border width, elevation, and even motion. They are used in place of hard-coded values such as hex codes or pixels to maintain scalability and consistency.

Further reading​

Nathan Curtis on Tokens in design systems

To go directly to setup guides, check out the Theme Guides.

Token system architecture​

3-tier token system​

Abyss uses a 3-tier token system:

Core tier​

Contains primitive values, with no specific meaning - the name of the token and its raw value (HEX code for colors, and numbers for borders, corner radius, opacity, etc.) These are restricted by brand. For example, UHC and Optum have different sets of available core colors, which align with the brand's identity.

Example: $core.color.brand.100 → #0071e3

Semantic tier​

Communicates design decisions on the exact usage of a Core token system-wide.

Example: $semantic.color.surface.container.primary → $core.color.brand.100

Component tokens​

This is the lowest level token -- passed directly into the component and references a semantic.

Example: $rating.color.surface.icon.filled → $semantic.color.surface.accent.decorative.3

Inside implementation of Rating:

<IconSymbol
  size={iconSize}
  icon="star_rate"
  color={isActive ? '$rating.color.surface.icon.filled' : 'transparent'}
  {...abyssProps('rating-star')}
/>

Token categories​

Abyss supports tokens for:

  • Colors: Brand, neutral, semantic colors
  • Spacing: Padding, margins, gaps
  • Sizing: Width, height, component dimensions
  • Border Width: Border thickness values
  • Border Radius: Corner rounding values
  • Opacity: Transparency levels
  • Typography: Font sizes, weights, line heights, families
  • Shadows: Box shadow definitions

Composite tokens format​

typography and shadow tokens are formatted differently, as they are objects that contain multiple properties. Depending on the token, these properties can be a mix of core tokens and raw values. Not all properties are found in every token. For example, some shadow tokens only have shadowColor and shadowOffset, while others also include shadowOpacity and shadowRadius.

Example:

'semantic.typography.p.sm-bold': {
  fontWeight: '$core.font-weight.bold',
  fontSize: '$core.font-size.p.60',
  lineHeight: '$core.line-height.60',
},


'semantic.box-shadow.focus.error': {
  shadowColor: '$core.color.red.100',
  shadowOffset: {
    width: 0,
    height: 0,
  },
  shadowOpacity: 1,
  shadowRadius: 4,
},

They are used with the typography and shadow props:

const SmallSectionTitle = styled('Text', {
  typography: 'semantic.typography.p.sm-bold'
  shadow: 'semantic.box-shadow.focus.error'


})

Token format support​

The Abyss token system uses DTCG (Design Tokens Community Group) token format, but flattenTokens supports both DTCG and legacy token formats.

DTCG format (current standard)​

{
  "brand": {
    "$value": "#0071e3",
    "$type": "color"
  }
}

Legacy format (deprecated)​

{
  "brand": {
    "value": "#0071e3",
    "type": "color"
  }
}

The system automatically detects which format is being used and handles both identically.

Table of Contents