I've been wrestling with a token architecture challenge lately, and I think I might have found an approach that could change how we think about platform-specific design systems. Let me walk you through my thinking process and the solution I'm exploring.

So I've been tinkering with this idea for a while now - what if design tokens didn't have to live buried in some JSON file that only developers ever see? What if designers could actually play with them? With the Automator script no longer working due to Figma's API changes, I decided it was time. That's how I ended up building this Living Documentation Tool. It's a visual preview for design tokens where you can click on color swatches, get a preview of the typography, and actually see spacing in action. No more digging through Figma files or squinting at code.

Another day in improving the design system documentation applying Living Documentation steps. Focused on making Radix color scales more contextual for the team. Make it make sense for your team While Radix provides excellent documentation, there's often a disconnect when team members need to constantly switch between external resources and our internal design system. This context-switching can lead to reduced productivity and potential misalignment in implementation.

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.

Language matters. In design systems, the words we choose to describe concepts shape how they are understood and adopted across teams. One term that has gained traction is “primitives.” It refers to the foundational building blocks—like color scales, typography, and spacing—that underpin a design system. While widely used, I believe “primitives” can feel vague and even a little alienating, especially for those outside the design or development bubble. This blog explores why we might need a clearer, more inclusive term and proposes alternatives that could enhance collaboration and understanding across all levels of a team.