Making Token Documentation Dynamic

Jan 21, 2025
We've all been there - staring at a mountain of design tokens, knowing there has to be a better way to document them. Yesterday, I decided it was time to find that better way. Finding this article by Sam Gordashko on Living Documentation.
So my morning started with what seemed like a straightforward plan: convert our design tokens into living documentation using Automator. Simple enough, right? Armed with optimism and my cup of coffee, I dove in.
Time is a Funny Thing
The first hurdle appeared almost immediately. The script took one look at my system, shrugged its virtual shoulders, and refused to run. The culprit? A missing typeface - Satoshi Variables, to be specific.
Instead of letting this derail the project, a quick modification, replacing the missing font, not only solved my problem but would help future users avoid the same roadblock.
Now it was working properly! Time to laugh at my initial timeline estimates. When I started processing our foundational tokens, I thought, "This shouldn't take too long." Then I watched as the color documentation for our Radix Color scales took a full 30 minutes to generate. It was a humbling reminder that good things take time.

But here's what fascinated me - I found myself mentally visualizing for better organization. Thinking about how a team would interact with this documentation, and planning improvements for the next iteration. Sometimes, forced pauses give us our best thinking time.
Now we are cooking, time to plate up!
The real adventure began in the afternoon. The generated documentation was complete but came in a single-column format that isn't going to serve any team well. What followed was hours of careful reorganization, particularly with the color documentation. It wasn't just about making it look good - it was about making it useful, intuitive, and maintainable.

Looking Back, Looking Forward
As I wrapped up yesterday, I realized this experience had become about much more than just documentation. It was about understanding our design system at a deeper level, about finding ways to make our tools work better for our team, and about growing my own problem-solving toolkit.
The experience reinforced something I've always believed: in the world of design systems, there's always room for improvement, always a new challenge to tackle, and always more to learn. Sometimes the most growth happens not when everything goes smoothly, but when we hit those unexpected bumps in the road.
What's Next?
This is just the beginning. While I'm excited of what was accomplished in a day, I'm even more excited about the possibilities ahead. There's still so much we can do to make our design system more robust, our documentation more useful, and our processes more efficient.
For anyone considering a similar journey - yes, it will probably take longer than you expect. Yes, you'll hit unexpected challenges. And yes, it will absolutely be worth it.
After all, isn't that what professional growth is all about? Taking on challenges that seem simple at first glance, discovering their hidden complexity, and emerging with new skills and insights? I know I'm already looking forward to the next challenge.