Part 2 - Create "living" documentation of design tokens

A step-by-step guide to creating design token docs in Figma that update automagically using Tokens Studio and Automator plugins.

Mar 13, 2024

Hi Designer, Sam I am here 🫶

In part 1, we went through the fundamentals of living documentation, how to set up Automator and created a template to use with the downloaded automation script.

← Head back to part 1 if needed

In part 2, I’ll walk you through how to run the Automator script to create your living design token docs and keep it “alive” with your most recent design decisions using Tokens Studio.

This guide will work on both the free and pro licences of Tokens Studio, and Automator is now free!

👀 Watch the full YouTube video or scroll down to read through the process.

Map of Contents

Create living documentation with Automator

This section is going to move pretty quickly as we covered all the context needed to understand how things work in part 1 of this series. If you find yourself feeling lost, confused, or frustrated, try watching the full end-to-end video on YouTube or heading back to part 1 for a refresh.

Step 1 - Copy+paste the Tokens Set name from Tokens Studio

The goal is simple. Tell Automator which Token Set we want to create living documentation for using our template.

However, its not always easy to get the Token Set name right. And if things go wrong, Automator won’t tell you how to fix it (no error messages!).

So (trust me and my 2 years of trial and error here), I highly recommend using this copy-and-paste method to save you from a lot of frustration and headaches.

Screenshot of a Token Set name of “themes/light” which might be mistaken as “light” had we not copy and pasted it from the Token Set.

Open the Tokens Studio plugin in Figma (short key: cmd/ctrl + p)

Find the Token Set for the tokens you want to document.

Pro Tip!
The first time you test the flow, work on a small token set.

In the left-hand menu of Tokens Studio:

Right-click on the Token Set name
Select Rename in dropdown menu
Highlight the full Token Set name from the field
Copy text (short key: cmd/ctrl + c or right click > copy)
Exit out (hit esc, click X, or click Cancel)

Record the token set name for easy reference.

Paste the copied set name (short key: cmd/ctrl + v or right click) in something like:

a sticky note or text element in the Figma file
the notepad or sticky note app on your computer

Step 2 - Run the Automator script (short key: cmd/ctrl + p)

✅ Before you get started

✓ The first time you test the flow, work on a small token set.
✓ Select the template before you complete the Automator plugin flow.
✓ If your template is a component, create an instance (opt/alt and drag) instead of the original.

Open the Automator plugin in Figma (short key: cmd/ctrl + p)

Ensure your Token Set name is copied to your clipboard

Select your template on the canvas
In Automator, select the Tokens automation script you configured in Part 1.
Paste the Token Set name you copied earlier in the input
- if you no longer have it, go copy it again to paste it in the input, then be sure to have your template selected on the canvas
Select done
You can leave the value for Token name (startsWith) empty if you wish
- this creates templates for all tokens in your set
Select done
Wait for Automator to work its magic.

Screenshot of Automator script with Token Set name pasted as the input with our template selected (instance of component).

Step 3 - Find the Automator template duplicates

The output frame might not be in the most obvious place on your Figma canvas.

You're going on a little search 🔍

The Automator duplicates of your template will be wrapped in a frame layer with a white background color. Keep this in mind to be able to locate it.

To find the frame, try either of the following:

Finding it on the canvas by zooming out and panning around, looking for a long white frame.
In the left-hand layers list in Figma, select the frame layer named “frame” at the top of your layers list.
- This is a great example of why not naming your layers gets confusing. 😉

You can either drag the frame back to where you were working, or you can cut it and paste it accordingly.

Screenshot of how far away the Automator “frame” was placed on the canvas from where the template is and how to find it in your layers list (left menu of Figma).

Troubleshooting tip 😫
If you find the Automator fame and it’s empty with no templates within it, start the steps over again, making sure that your template is selected before you run the script and your Token Set name is copy and pasted from Tokens Studio without any extra spaces.

Screenshot of Automator “frame” output that is empty do to the Token Set name not matching Tokens Studio.

Step 4 - Populate the templates with Tokens Studio

Select the “frame” output by the Automator in the last step.

Open the Tokens Studio plugin
Make sure the token set you copied the name of is "active"
- a checkmark will be next to the token set name in the plugin left menu
Configure the bottom button to "apply to selection" if it isn’t already
Select the button "apply to selection"
Wait while templates are populated with data from Tokens Studio
Inspect your work

Screenshot of Tokens Studio populating the selected “frame” of Automator templates. The Token Set I copied is active (checkmark) and the action is set to “apply to selection”.

Troubleshooting tip 🤔
If any parts of your template didn’t populate as expected, head back to the Rename your layers section in part 1 of this guide to make sure you don’t have any typos based on what you were trying to create.

Step 5 - Clean up your templates

The order in which the templates are created in Automator is still a mystery to me.

So you’ll want to spend some time organizing your files. You’ll notice the templates have been renamed to match the token name which is handy.

Sometimes the documentation template you created doesn't quite work with the data from your tokens, this is a classic content design challenge.

For example, if your template has a text layer for __description but your token doesn't have one, you might want to hide that layer.
If your template uses component properties, this part is easy.

In my experience, tokens with lots of information like typography, color gradients, or where I've used math functions typically need some love on the alignment and auto layout settings on my text layers to make them readable.

Screenshot of living docs for typography tokens with text layers that need some content design work on their alignment and auto layout settings.

Update living docs with Tokens Studio

Once the living docs are created and organized, there isn’t much to do to keep them “alive” and up to date. Whenever your design decisions change and you’ve updated your tokens, it’s the same process as when you populated the templates initially.

Select your living docs.

Open the Tokens Studio plugin
Make sure the token set you updated is "active"
Configure the bottom button to "apply to selection" if it isn’t already
Select the button "apply to selection"
Wait while living docs are populated with the new data from Tokens Studio
Inspect your work
- If you’ve changed the names of your design tokens, it’s possible they may not update until you manually remap the living docs to the new token names.
- This topic (name changes as breaking changes) deserves its own deep dive, so feel free to DM me on the Tokens Studio slack community if you are stuck before I tackle this one.

Pro tips for maintaining living docs

It’s no secret that Figma has some working memory limitations and Tokens Studio can start to run slow in files that have a lot of tokens scan.

Living documentation adds a LOT of tokens to a file. If you ever want to know how many tokens the plugin is scanning for, pay attention to the node counter in the top navigation bar the next time you perform an action in Tokens Studio.

Screenshot of the node counter in Tokens Studio scanning 6.2k nodes to populate living documentation templates for a token set with 200ish design tokens.

So, to take advantage of living docs without suffering from performance issues, here are a few strategies that work for me you might want to try.

“Apply to selection” as often as possible

When the plugin bottom action button is set to “Apply to selection,” it scans the minimum number of design elements possible, only the design elements you have selected on the canvas.

In large files or pages where you’ve been exploring ideas with tokens, this will help keep your workflow moving as fast as possible.

Sometimes, you have to apply your changes to the full page or the entire Figma file, so in that case, be patient. If you experience crashes or unusual performance issues, please reach out to the Tokens Studio team via their Slack community or website.

Place living documentation in a separate location from your components

If I’m working on my button components and they are all on the same page in my Figma file, and I have my living documentation also on the same page, every time I make an update and run the plugin on a “apply to page” command, I am asking Tokens Studio to scan 2-3x additional tokens.

But if my components are on page 1 of my file, and my docs are on page 2, I can wait until I’m done with my component work, then head over to the docs page to update those as a separate action.

Living documentation as components

I’ve even worked in headless design systems where every component has its own Figma file, and all the living documentation was in another file. I turned the docs into page-sized components and had instances of the component docs in the file.

Designers liked this because they could “turn on” the documentation library and search for whatever docs they needed, pull in the component with the notes and diagrams and have them handy while creating or collaborating with other designers, PM’s or engineers. They would be notified when the docs changed (because I pushed an update to the documentation library), and they never had to run the Tokens Studio plugin.

You did it!

That was a LOT of information! If you have questions, suggestions, or want to talk shop feel free to reach out. (:

Confessions from a design team of one

Discussion about this post