Mixin Design Tokens

Design tokens manage and store User Interface (UI) decisions such as spacing, color, typography, and motion. These decisions are stored in a config-like format to support the needs of any platform (Web, mobile OS, etc). In this blog post, I’ll demonstrate how you can leverage design tokens and SCSS mixins to capture a system’s design language. The final output will be a collection of SCSS mixins that map to design tokens and can help to reel in messy CSS inconsistencies amongst dev teams and close the gap between designers and developers with great success.

Background: The visual language of your product

A product’s visual design, at its core, is defined by basic visual elements.

All components and layouts of any digital design system fit into those categories. In a design system, this is referred to as the visual language. Unfortunately, many products define their visual language across a wide gap; from design mocks to CSS files, these elements are defined and redefined over again. This is often the root cause of design inconsistencies, tangled CSS files, and expensive iterations. Design tokens bridge the gap by moving a design language to its own layer where designers and developers can draw from and contribute iterations to. Essentially, it serves to dry up the visual language to a single location. It’s a simple, yet powerful concept with a list of advantages:

• Controlled change — Designers can iterate with confidence knowing design decisions cascade across all digital teams from a single location.
• Strengthened design and developer communication — Designers and developers manage the design layer together, digitally and conceptually.
• Speeds up UI development — Developers draw from a limited pool of UI decisions which takes out the guesswork.
• Eliminates visual bugs — Teams of developers pull digital design decisions from the same shared resource that are applied directly to their UI code. This cuts away common inconsistency bugs in CSS that occur on small and large teams.
• Increased design consistency — Teams of designers share managed design decisions.

The following touches on these principles and builds up a basic working example.

Moving these decisions to its own layer (like the tokens file above) in the production process creates harmony between design effort and development effort. UI inconsistencies are eliminated and changes to UI decisions cascade immediately.

Naming convention

A naming convention applied to the scale of each design property make values accessible to both designers and developers. This example uses a t-shirt size naming convention, incrementing the scale values between xxxl to xxxs.

A naming convention further fine tunes the relationship between the design and development effort. In the example below, a designer changes the button’s margin from a token value of xl to m. The developer uses that same token value to apply the update.

SCSS Mixins

SCSS mixins allow you to group CSS declarations into reusable pieces and therefore are a good fit for delivering and accessing the values captured in design tokens.

The concept of design tokens is not limited to SCSS, in fact, just the opposite. Design tokens can be platform agnostic (e.g., JSON file) which allow them to support any environment. You can follow the Design Tokens Working Group here.

Putting it all together

Below you can see how tokens, mixins, and functions are combined together to write components that use the design system. Following that is a running sandbox example.

Tokens

tokens.scss

The tokens here are stored directly in a SCSS file.

If this were a production product, the tokens could later be moved into a JSON file and the SCSS could be generated in a build process. Libraries like JSON-TO-SCSS could help.

Mixins

styles.scss

This file creates all the mixins to be consumed by the application. The mixins take care of accessing the design tokens.

The decision behind the naming style for each mixin is based around a mental mapping to traditional CSS. For example, a CSS developer should already understand what padding-left means and therefore a mixin with the same naming is easily digestible.

We chose this naming scheme because one of our team goals was:

“Support a large audience of varying expertise with limited training and high flexibility”

The CSS-like naming scheme made it approachable for users of varying experience levels to work with the design system. In another circumstance, you might decide that it makes more sense to reach for a terse naming convention, like Tachyons:

In Nathan Curtis’s article, Space in Design Systems, he takes an approach that maps design tokens into spatial concepts. Offering limited flexibility to encourage greater consistency. In the article’s spacing section, he abstracts groupings of CSS into single classes to choose from, each one being a spatial “concept”. For example, squish-inset reduces space by 50% top and bottom which could generate this output:

SCSS Functions

Along with the mixins, there are SCSS functions (like getSize()) included to gain direct access to a design token's value. This way you can compose CSS property/values that aren't available as mixins, but still dip into the design system. Here, getColor() is used to reach into the color palette:

Component example

button.component.scss

The mixins are imported into a module’s SCSS file and consumed in a CSS class.

Sandbox example

Takeaways

For some projects, the barrier to entry of implementing a full-blown design system is fairly great. Design tokens, however, can be applied to your existing project without the sign-off of a design system. Design tokens offer great value in their own right and implantation effort can start relatively low.

Design tokens can also serve as a gateway to opening up the conversation about how a design system can help align process, design, development, and governance around your product.