Design tokens

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:

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.

A Ripple token has 2 parts:

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

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

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

Start all design tokens with the system name: rpl is for Ripple.
Then, place an abbreviation for the token type: clr is for colour; type is for typography; sp is for spacing.
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.

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