--- title: Saying no to Diez (for now) teaser: 'Evaluating Diez, a framework for creating and maintaining design tokens. ' tags: design tokens,design,process,app author: Eric Bailey published_on: 2020-09-18 --- [Diez][diez] is a design token framework that “radically reduces the cost of delivering a consistent visual identity across your company’s apps and websites.” [Design tokens][design-tokens] are a platform agnostic way to capture and describe the building blocks of a branded interface. Unlike variables (which are project-relative), design tokens are intended to be used cross-project and cross-platform as a way to keep things in sync. They are especially helpful if you manage separate iOS, Android, and web apps all branded the same way. ![Demonstrating how design tokens' single source of truth simultaneously updates iOS, Android, and Sass.](https://images.thoughtbot.com/blog-vellum-image-uploads/ilgFFvTHQMW9xgZ6LFKr_design-tokens.png) thoughtbot is a good candidate for design tokens. We have several external and internal websites and apps that share common branded elements. Additionally, we recently undertook an initiative to clean up and unify our underlying Sass. This puts us in a position to make integrating design tokens significantly easier. I had some time to evaluate a different few design token solutions, and decided to give Diez a shot. Here are my impressions: ## What I liked about Diez ### Setup Diez can be [set up][set-up] in a matter of minutes, including a live-reloading demo. It’s straightforward enough that I second-guessed myself and looked for additional steps in the documentation, a bad reflex learned from trying to get many other projects up and running. ### Platform examples The demo Diez uses is an example of one of three sample projects it creates. In addition to a webapp, Diez sets up a demo iOS and Android project. All three projects consume the tokens it sets up as a single source of truth, with no extra effort on your end. This works out of the box, which is a testament to the promise of design tokens. ### Integration In addition, Diez can [integrate with design tools][integrations] such as Figma and Sketch. This means that codified values such as color and text/effect styles can be created in design tooling in the moment, and then codified and updated later by a designer with minimal fuss. This is a little hint of [the direction I think the design industry is headed][smarter-tools], where the tooling is working in more of a systems-based approach than a one-off, static composition one. ## What I didn’t like about Diez Diez runs into a problem shared by many frameworks: it comes with opinions. If you disagree with its approach it creates a lot of friction. ### Reserved words Due to using TypeScript objects for the input language, certain words are verboten for the creation of design token names. For example, `color` is a [reserved word][reserved-word], but existing thoughtbot color variables use `color-` as a prefix. This means we’re already going to be subverting thoughtbot developer’s expectations if we try and implement tokens via Diez. It’s a little thing, but ease of adoption is paramount for integrating design tokens into an existing project. ### Decoupling example design tokens Diez sets up predefined example tokens to run its demo. Unfortunately, if you try and remove these tokens, the project refuses to compile. While you could set up tokens separate of the ones used for the demo, Diez’s output will still generate tokens for the demo project. This pollutes the token namespace—a new developer won’t know the difference between these two types of tokens, and will probably reach for whatever works best in the moment. ## Design token chaining Design tokens should have [a single responsibility][single-responsibility]. A component should ingest design tokens, but be built in the project it is used in. Diez’s demo tokens are grouped together to create things like a palette and typography components. In addition to namespace pollution, I don’t think this is the appropriate place to do this kind of work. One problem we have in thoughtbot’s Sass is circumstantially chaining one variable to another. In theory, it’s a great way to create semantic variable names (ex: `$action-color: $color-red;`). In practice, this adds unnecessary cognitive overhead and becomes a maintenance nightmare. In addition, chained tokens create confusion about which token is the appropriate one. What is the difference between `colors` and `palette`? If I, the author, am unsure, I’m certain someone unfamiliar with the project is going to be even more at a loss. ### Literal output Diez is very thorough about generating tokens for the data you supply it, sometimes to its own detriment. Say you define: `spacing-3` as a design token. Diez will output the following tokens for Sass: - `$spacing-space3: 3;` - `$spacing-space3-px: 3px;` - `$spacing-space3-pt: 3pt;` - `$spacing-space3-em: 3em;` - `$spacing-space3-rem: 3rem;` `3px` is a whole lot different than `3em`. Oftentimes, our spacing values represent an abstract step in a [modular scale][modular-scale] sizing system. So, it is less about a component being placed exactly `3rem` away from another component, and more about it being distanced by a factor of 3. This might seem nit-picky, but experience has taught me that many developers take a “closest match” approach for using variables. Like with decoupling issues mentioned earlier, it’s vital to keep your selection of design tokens focused and relevant. ## Going forward Diez seems better-suited towards building apps in native code, as well as React Native, with the web seeming more like a secondary concern. Don’t get me wrong: despite my criticisms, I really enjoyed experimenting with Diez. Overall, it feels like the right approach at the right moment. I should also mention that Diez is still new and under active development, so I am hopeful that some of these issues can be ironed out in future releases. This is all to say: if you are working on a multiplatform experience, I strongly encourage adopting a design token approach. [diez]: https://diez.org/ [design-tokens]: https://css-tricks.com/what-are-design-tokens/ [set-up]: https://diez.org/getting-started/#set-up [integrations]: https://diez.org/getting-started/design-tools.html [smarter-tools]: https://css-tricks.com/smarter-design-systems-tools/ [reserved-word]: https://en.m.wikipedia.org/wiki/Reserved_word [single-responsibility]: https://en.m.wikipedia.org/wiki/Single-responsibility_principle [modular-scale]: https://www.modularscale.com/