x
Design systems

A step-by-step guide to using design tokens in InVision DSM

4 min read
Martin Laws, Ryan Neufeld  •  Nov 4, 2019
Link copied to clipboard

One of the most frustrating experiences for designers and developers is keeping code in sync with current designs. InVision Design System Manager (DSM) tries to solve this problem by putting the power of design tokens in the hands of designers and developers.

Design tokens act as variables that store your styles so that your color, text, and other style attributes will always be up-to-date. To put DSM’s design tokens to the test, we (Martin, developer) and (Ryan, designer) designed and built two prototype web apps of our favorite to-do list framework, One Big Thing.

“One Big Thing” aka “1-3-5”

In case you’re wondering why this to-do list looks funny, it’s because we modeled it after a framework called One Big Thing, aka “1-3-5.” If that name sounds familiar it’s probably because you follow Jake Knapp, the author of “Sprint” or “Make Time,” who invented the concept.

In this to-do framework, a piece of paper is divided into three sections. The first section should contain your largest and most important to-do item, or your “big thing.” The second section is further divided into three boxes which contain your three medium things. Finally, the last section is for your small things (five are recommended, but I often do more).

Source: Twitter

The prototype

Here’s a working version of our simple prototype that you can follow along with. We ended up building two prototypes: the one we’re discussing here, and another more advanced prototype that includes the use of an enterprise-level component library (Alibaba’s ANT design component library for Vue, for those interested). Both designs are similar and look something like this:

Let’s get that bread!

Look at our app, now back at me, now back at our app

Want to see something cool? This to-do list application uses 7 design tokens to define all of the colors in the application. Once a color is changed for any of those tokens in DSM, the moment I refresh the page, the change will be reflected LIVE. IN. THE. BROWSER.

That means no handoff. No hunting down individual hex codes. No begging developers to change the shade of blue on a button. A designer can make a change, push that change to DSM, and it will be reflected live in the browser. Check it out below 👇

What is a design token?

Design tokens are the visual design atoms of the design system—specifically, design tokens are named entities that store visual design attributes. They are used in place of hard-coded values, such as hex values for color or pixel values for spacing, to maintain a scalable and consistent visual system for development.

Check them out yourself in InVision’s Design System Manager.

Imagine a world where you can change a color in a Sketch file, and then all a developer needs to do is sync the changes made to that file. This is especially great for designers who don’t code or don’t use a Git/GitHub workflow making it easier to sync up on changes.

This is what the design tokens for color looks like for this project in DSM. Check them out here

Design tokens are versatile and can be used for any number of things including:

  • Color Palettes (DSM supported)
  • Font Families (DSM supported)
  • Icons (DSM supported)
  • Borders
  • Breakpoints
  • Z-index
  • Sizes
  • Spacing

Here are some examples of where we’re using them:

The design token ‘—color-primary’ in use as purple in the header.

The tools you’ll need

Here’s what you’ll need to get started building an app as we did:

DSM need-to-knows

To use DSM, just download Craft and send your developer this API link. You can read everything else there is to know about DSM on the website.

Here are some important things to know before you start using DSM:

The sample library 📚

  • If you have an InVision account then you have access to DSM. It comes with a sample library that you can browse through on the web and in Craft. Additionally, you can download the source Sketch file and see how they set things up. This is your best friend when it comes to learning the ins and outs of DSM.

DSM’s design tokens 🌈

  • Right now DSM only supports colors, text styles, and icons.

DSM API 👾

  • This resource is the only documentation out there for DSM’s API. It’s important to know that you can use your design tokens without it, but this just adds a little automation to the process if you want to be fancy.

A step-by-step guide to setting up your design tokens in DSM

  1. Log in to the InVision web app. Navigate to DSM. Click the ‘New Library’ button.

  2. Fill out the New Library Form and click “Create.”

  3. Click the DSM icon in Sketch with your file open.

  4. Click ‘View’ in the new library snack bar, or click the dropdown in the top left to manually sync your new library.

  5. Select the objects in Sketch that contains the color(s) you want to add to your library and click the ‘+’ icon in the bottom right corner of the ‘Colors’ folder in the DSM overlay. Then confirm your selection from the “colors from selected layers.”

  6. Click on the ‘Untitled Color’ label under each color swatch and rename your colors to whatever you want your token names to be.

  7. Next, open your ‘text styles’ folder on the DSM overlay and click the ‘+’ icon in the bottom right of the DSM overlay to select the text styles you want to add to DSM.
  8. Note: you have to create text styles in Sketch before they can be added to DSM. If you’re not sure how to do that here is a great guide.
  9. Optional: Rename your text styles by clicking the label underneath each card. Text styles inherit their names from Sketch by default.
  10. Open the web view of your DSM library.

  11. Click the ‘</>’ icon in the top app bar and select ‘Design Tokens’ in the dropdown.

  12. Select your preferred format for ingesting your design tokens on the left.
  13. Either click the ‘download’ button to download a file containing your design tokens and their style values or copy the ‘Styles’ link and send them to your developer. Alternatively, from the primary web view click the ‘invite’ button and follow on-screen instructions to invite your developer to your library and they can complete steps 16–18 by themselves.
  14. The tokens are in the computer?

    Thinking in terms of design tokens can help inform front-end development, especially in relation to component structure and CSS. If design tokens are the individual atoms of our application, components are our molecules. We’ll mix and match design tokens to create reusable components—which we’ll piece together to create a scalable user interface. Here’s a link to the source code for this live demo.

    In our case, our design tokens mapped to ten front-end variables:

    1. -color-background-app
    2. -base-font-size
    3. -base-font-color
    4. -header-font-size
    5. -header-font-color
    6. -color-background-app
    7. -color-background-card
    8. -color-empty-border
    9. -color-incomplete-border
    10. -color-complete-border

    Now, we add a tag to pull in the CSS file that DSM auto-generates (and hosts) for us, and in the case of a modern JavaScript app, we add the tag to our index.html:


    If you visit that URL directly, you’ll see that DSM’s stylesheet simply sets CSS variables on the :root of our application—it’s up to us to consume those variables.

    Want to try it yourself? Check out InVision’s Design System Manager today.

    Three of our variables map 1:1 to design tokens returned to us by DSM. Let’s wire those up first in our top-level App component:


    Not quite as simple are our –base-font-size and –base-font-color variables. Our design tokens are set up to return three font sizes – small, medium, and large, with each font size mapping to a viewport size (desktop, tablet, and mobile, respectively). We’ll be setting our variables dynamically, using media queries to switch which DSM variable we assign to our in-app CSS variable:


    Now, in our components, we can simply assign styles using the CSS variables above, the values of which will update according to the size of our user’s viewport. We can also tap into the remaining DSM variables we aren’t yet using, like –color-background-card or –color-empty-border. Here’s an example, in TodoItem.vue:


    A word to the wise—before jumping into code, make sure you’ve thought about the structure and nomenclature of your design tokens. Naming conventions matter—you’ll save time and energy by defining your design tokens (and their names) early on. Ask yourself: are your design tokens clearly-defined atoms or bloated molecules? Will you be able to reuse them across various components? Draw out a visual hierarchy showing the progression of grouping individual design tokens into components, then into full-featured user interfaces.

    Conclusion

    Design tokens work, they’re damn cool, and they solve a big problem.

    Using DSM’s Design Tokens in a relatively simple product development environment works really well. Using DSM’s Design Tokens with a pre-existing component library is also cool but a lot more work, as you’ll have to tailor your tokens (and naming conventions) to the component library, so if you’re trying to be efficient, DSM might not play nicely with your component library right away, and this might add quite a bit of work (it did for us). That said, I would consider using DSM to manage styles using their Design Tokens with future collaborators on smaller projects.

    Ultimately, DSM did allow us to solve our original problem: the endless back-and-forth between designer and developer to update our code every time a design token changes. This affords designers the same flexibility that a developer has in a “dev” environment, allowing for quick, easy exploration of design token updates, and the ability to roll those out without any code changes or expensive deployments.

    Regardless of whether or not you’re using design systems in your current design process, design tokens are awesome and I would encourage you to try them out on one of your future projects.