Design System Documentation Reimagined
Overview
In 2025, I set out to rethink how design system documentation could live, breathe, and evolve across multiple platforms — without creating a single point of failure. The goal was simple but ambitious: build a documentation architecture that connected tokens, design decisions, and implementation context in real time, while remaining approachable to designers, developers, and stakeholders alike.
The Challenge
Most documentation frameworks are one-dimensional. They’re either designer-centric (Figma-based), developer-centric (code-based), or static repositories (Notion, Confluence).
The problem: design tokens and component systems evolve faster than traditional documentation can keep up with. I needed a model that:
Updated dynamically from Tokens Studio data
Served different audiences with tailored depth
Could exist across multiple environments (Figma, web, internal tools)
Avoided dependency on a single platform or subscription
My approach
I began by breaking documentation into three structured layers — each with its own intent and audience:
Designer Layer (Figma-integrated)
Focused on applied usage and design intent. Each token and component included context directly in Figma — where designers needed it most. I used tooltips, local descriptions, and Universal Component Templates to embed best practices.Developer Layer (External platform)
Built in a third-party documentation environment, this layer visualized tokens, code snippets, and implementation logic. Developers could explore token JSON structures, usage examples, and theming guides side by side.Stakeholder Layer (Surface documentation)
Provided concise overviews explaining why tokens or patterns existed — helping non-designers understand how system changes impacted the product roadmap or brand alignment.
To unify these layers, I established a documentation source map — effectively a routing system that linked each token, component, or style reference to its corresponding location in the other layers.
The Execution
Implemented live-updating token references using Tokens Studio JSON exports
Built visual previews for typography, color, and spacing tokens
Designed a layout system that scaled from single-token documentation to component-level architecture
Authored a writing framework (short-form for Figma, structured markdown for dev docs, narrative summaries for stakeholders)
This approach ensured that every change to a token or component had a traceable, platform-agnostic representation.
The outcome
Documentation is often an afterthought in design systems — but it’s the backbone of continuity.
By designing for multi-audience adaptability and tool independence, I built not just a documentation site, but an operational model for maintaining system integrity at scale.
The result: a living system that communicates its own logic — wherever you meet it.