Ripple Design System

Design tokens

Design tokens store our design decisions in the Ripple Design System. They are the single source of truth.

What is a Design token?

Design tokens store our design decisions that, together, make up the Ripple Design System’s visual style.

Tokens apply values in a consistent, reusable and scalable way. They ensure the same style values are used across design files and code.

By storing design decisions, they replace the need to use static values (for example, hex code values for colour).

Ripple Design System has tokens for:

  • colour
  • typography
  • spacing
  • elevation
  • borders
  • motion values.

Why use design tokens?

Using design tokens keeps your UI consistent across different platforms.

Design tokens are the single source of truth. You can use them across designs and code.

Since design tokens let you make value changes at scale, design language changes are easier to make.

Design tokens aren't hard-coded. Avoiding hard-coded values in your design system makes it easier to build, maintain and scale products.

Ripple design tokens

A Ripple token has 2 parts:

  • a token name, such as rpl-clr-primary
  • an associated value, such as #0052C2.

The token's value can be one of several things: colour, a typeface, a measurement or even another token.

How to read Ripple design token names

Knowing how to read a token name helps you find the right token faster.

Parts of design token names

  1. rpl: design system
  2. clr (colour) or type (typography) or sp (spacing) for example: token type
  3. primary-accessible (a descriptive name) or 3 (a number), for example: see below


  • rpl-clr-primary-accessible
  • rpl-sp-4

Steps and explanations

  1. Start all design tokens with the system name: rpl is for Ripple.
  2. Then, place an abbreviation for the token type: clr is for colour; type is for typography; sp is for spacing.
  3. End the token name with a descriptive name or number to show the token’s role relative to other Ripple design tokens. For example, primary-accessible in rpl-clr-type-primary-accessible shows this is a colour token that applies one of Ripple’s primary colours (from the colour palette available in Ripple Design System) and is suitable for accessible content. 4 in rpl-sp-4 shows this is a spacing token where 4 is the fourth spacing step (16x), in size order, from the spacing options available in the Ripple Design System.

Best practices

  • Choose tokens based on meaning rather than appearance only
  • Choose the token with the most specific meaning that is available and applies to your content’s role on the site
  • Do not choose tokens based only how the end result looks on your site
  • For example, for a heading, it is important to choose rpl-type-h3 (heading token) instead of a rpl-type-p-large (type token), even though the end result looks similar
  • For example, if your content needs to be accessible and a certain colour, you should pick rpl-clr-type-primary-accessible instead of rpl-clr-primary
  • Don't pick a token just because the colours seem to match - this can break the consistency across other themes and confuse the user’s experience
  • If you do choose tokens based on appearance only, updates to themes, colours, or other features will not apply properly or consistently later

Why are tokens important for design?


Tokens can be created with a specific purpose or goal in mind. For example, improve accessibility, enhance visual consistency or make it easier to update and maintain a website or app.

Since tokens are purpose-driven, designers and developers can make system-wide updates focused on achieving specific purposes. For example, systematically apply a high-contrast colour scheme for improved visibility, or change the type scale.

Single source of truth

Design tokens are like reusable building blocks. They give a design system a single source of truth for making changes to the way a website looks and works.

Having a single source of truth lets a design system implement features like global theming, responsive design and user customisation.

System-wide updates

They let developers and designers change system-wide themes and contexts, using only a single update.

Design tokens prevent or reduce the need to find and replace thousands of instances of hard-coded values in the code.

For developers

For information for developers using tokens to theme Ripple components see the theming guide

Propose a change to this page on GitHub.