Looking for the current Rivet documentation? View the v1 site.

Design Tokens

A method of codifying the values (like color and spacing) at the core of IU's visual identity and design system, enabling consistency across platforms and design executions.

Chat icon Comment on this document

Use your IU Login to access and comment on this RFC in Google Docs.

Design tokens are values used to design interfaces that aren't tied to any one specific technology, programming language, or framework. Some values that might be represented by design tokens include how much space is between two elements or colors. By standardizing and documenting them in our design system, they can serve as the single point of reference for all of the primitive values we use to design and build digital products, helping to increase visual consistency across all of our websites and applications.

This quote from the Salesforce Lightning design system site does a really great job summarizing the benefits of design tokens.

Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development.

Salesforce Lightning Design System

When we use the term primitive values, we mean the raw materials used in digital design like pixels, spacing, and color values. Whether you are using static design tools like Figma or Sketch, or you are writing HTML and CSS, you use these primitive values to express the visual attributes of design.


Rivet gives developers a pre-built set of interface components they can use to assemble any number of interfaces. But, there will always come a time where we need to design new components, customize existing ones, or design for other digital mediums like email or TV screens.

When developers create websites and applications, they store the values used to specify color, space, and type in variables that can be referenced throughout their codebase and updated in one central location. With design tokens, our goal is to bring this same kind of consistency to the way we approach visual design.

An Example

The big benefit of design tokens is that they help us choose values we use in visual design with intention. Using a predetermined set of values also makes it much easier to translate visual UI design to code. Let’s look at the card component, a common design pattern found on many websites.

A typical Card UI component with a cover image, title, teaser, and some tags

In this example there are multiple font sizes, colors, and amounts of space between the elements that make up the card. The font size of the heading and the amount of space between the content and edge of the card are chosen with intention. The heading size makes it stand out against the content of the teaser paragraph below, the space around the edge of the card helps draw focus to the content inside.

Expressing visual design with tokens

Almost all of the visual design attributes that make up this card component can be expressed in the same values that we store as variables in the Rivet codebase. All of the space between elements, font sizes, and colors are taken from design tokens in the Rivet system.

This animation shows specific design token values overlaid on the final design.

Here's what all we hope to make into tokens that you can use in your projects regardless of technology.

  • Responsive Design Breakpoints
  • Colors (primary IU palette and secondary colors)
  • Font families
  • Font sizes
  • Shadows
  • Spacing
  • Sizes for width and height
  • z-index

A common language

With a well-documented set of design tokens in place, designers and developers can start to communicate using the same terms. For example every color in the Rivet color scale for black has a name that follows this format color-black-000, color-black-100, and so on. Those colors names are mapped to hexadecimal codes for every tint of black used throughout the Rivet codebase. All of these colors can then be documented on the Rivet website, allowing designers and developers to reference a common set of values.

Some technical details

Design tokens are part conceptual strategy for keeping designs consistent across a large organization, but there is also an underlying technical implementation that makes them really powerful.

We store the master design token values in the Rivet codebase as a set of JSON files. JSON is a standard data format that we can use tools to process and output as other formats. For example, we used the CSS preprocessor Sass in the Rivet codebase. From our master design tokens (JSON files) we can output the Sass variables we use in Rivet as well as almost any other format. We could also generate Less (another popular preprocessor) variables, CSS custom properties, or event proprietary formats like pallet files for static design tools like Sketch.

This makes for a very flexible system and allows us to be able to use the same values in our designs whether we are designing a website, an HTML email template, or for some other platform that we don’t know about yet.

Feedback prompts
  • Are there values you often use when building or design interfaces that aren’t listed in this RFC that might be beneficial to document as design tokens?
  • If you’re a designer, how do you think about and manage values like spacing and font sizes in your design documents? Does the concept of a standard set of values seem useful to you?
  • If you’re a developer, how do you manage CSS property values for things like spacing (margin or padding), and font-size across your project(s) to keep them consistent? Does the potential of having access to variables in your format of choice, for example Sass, Less, or CCS variables (custom properties) seem valuable to you?
Give feedback on this document
Chat icon Comment on this document

Use your IU Login to access and comment on this RFC in Google Docs.