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.