Contextual Documentation for Design Tokens

Today we announce the release of Diez 10.3.

Learn how to bring contextual documentation to your design system — plus find out what else is new in Diez 10.3.

Diez is the Design Token Framework — an open-source tool for expressing visual styles that can be shared across codebases, native platforms, and teams. Learn more at https://diez.org

Documentation is an integral part of any design system. Better documentation means better collaboration — and isn’t that why we build design systems in the first place?

But where should documentation live? Or better yet: where can it live? What if, in addition to your centralized docs, wiki, or website — your documentation could visit designers and developers where they work? Like design tools and code editors. That’s contextual documentation, and it’s uniquely enabled by the portability of design tokens. Document once, read everywhere.

Documentation plus the portability of design tokens means your docs can go anywhere your tokens do — like code editors and design tools

“Autocomplete for design tokens” has been a core feature of Diez since our first release— thanks to Diez’s static typing, any modern code editor is a natural “design token browser.”

In 10.1, we introduced the ability for design token code comments also to show up in autocomplete popovers, in Xcode, Android Studio, VSCode, and most modern code editors & IDEs — the beginnings of contextual documentation.

Today, with the release of Diez 10.3 we’ve further enhanced design token autocomplete to include the values of the design tokens in addition to their names and types —making that little pop-up window a one-stop-shop for understanding the what, how, and why of any token. No plugins or special configuration required — this all comes for free with any modern code editor.

Now developers on any platform can refer to the latest documentation for any token, in context.

See what else is new in Diez 10.3

Diez 10.3 also features:

• Enhanced token extraction from design tools
• Support for CommonJS modules
• Fixes and improvements

All of these benefits are non-breaking and fully backwards compatible. Here’s how to upgrade or install from scratch:

# if using npm, upgrade with:
npm install diez @diez/engine @diez/prefabs @diez/compiler-core @diez/extractors @diez/start @diez/stdlib
# or install from scratch:
npx diez create
# if using yarn, upgrade with:
yarn upgrade diez @diez/engine @diez/prefabs @diez/compiler-core @diez/extractors @diez/start @diez/stdlib --latest
# or install from scratch:
yarn create diez

Enhanced token extraction from design tools

Improved Typography extraction from Figma

Running diez extract on a Figma URL now also extracts settings like line height, text alignment and character spacing. No special configuration is required and the output is backwards compatible with prior versions of the extractor.

Improved sanitization of design token names

Although it’s important to have the flexibility to name your tokens when defining them in your design tool of choice, not all names are valid in JavaScript. For example, having a token name start with a number like 10Blue, or using a JavaScript reserved word like default

In this release, we improved the detection of invalid token names, and now we wrap invalid tokens in quotes to make them accessible in your Diez code.

You can use bracket notation to access tokens with invalid JavaScript property names:

import {myProjectTokens} from './MyProject.sketch'
myProjectTokens.colors['10Blue']

Support for CommonJS modules

When you compile a Diez project for the Web via yarn/npx diez compile -t web you get your tokens ready to consume in different flavors: SCSS, CSS or JavaScript with type definitions.

With this release, we enhanced the JavaScript output so you can now directly import your design system in codebases using CommonJS modules.

import {Diez, DesignLanguage} from 'my-design-system';
const diez = new Diez(DesignLanguage);
diez.attach((designLanguage) => {
    designLanguage.myColor
});

Fixes and improvements

This version also includes many fixes and improvements like:

• Warning for users trying to extract from Figma with an invalid authentication token.
• Stability improvements for Windows and Linux users
• Use web as the default target to when running diez compile.
• Read the full changelog here.

Stay in the loop

Want to be part of the future of design tokens? Diez is free & open-source, powered by community contributions.

• Check out Diez on Github
• Join the conversation on our Slack Community.
• Consider joining the Diez creators on the W3C Design Tokens Community Group

Until next time! With ✌️ & ❤️,

The Haiku Team, maintainers of Diez