Reading the Interface
The Hidden Questions Behind Every Token
Every design token in your system is like a sentence in the story of your interface. If you “read” your design system closely, you’ll find each token silently asking questions. Have you ever paused at a token name in your code and wondered, “What is this for?” That little moment of uncertainty is the hidden question behind an unclear token name. In this issue, we explore how design tokens are more than just variables – they reflect decisions, assumptions, and even user perceptions. By the end, you’ll see how naming a token is an act of design storytelling and why the words we choose matter.
Every Token Tells a Story (or Should)
Design tokens aren’t just technical specs; they’re the narrative glue between design and development. In fact, “design tokens act as reusable pieces of code that describe colors, typefaces, spacing, and other visual elements in a design system,” and choosing proper names for them is critical for maintainability, clarity, and efficiency, just like naming variables in programming
A token is often described as a “shared lexicon” between designers and developers – a common language that bridges design decisions and code implementation.
If that language is clear, everyone reading the design (in Figma or in code) understands the story. If it’s muddled, the plot gets lost, and confusion creeps in.
Good token names instantly communicate purpose, while bad ones raise doubts. A well-chosen name instills trust that the token does what you think it does. For example, if you see color.text.primary, you can guess it’s the primary text color and use it with confidence. But if you encounter mysteryColor123 or a vaguely named blue-1, you’re left wondering what it’s meant for. A teammate might ask, “Is this for backgrounds, or text, or borders?” – an extra round of questioning that slows everyone down. A clear, contextual name is like a signpost: it tells you where to go without needing to stop and ask for directions.
Names That Ask (and Answer) the Right Questions
Think of design tokens as interrogative tools in your design system. Each token name should answer the questions a designer or developer might ask at the moment of use: “What is this for?” “Where should I use it?” “Why does it exist?” If the token’s name doesn’t answer these, then those questions remain hidden, waiting to trip someone up later. Consider the difference between an ambiguous token name and a descriptive one:
Ambiguous:
blue-1– This name is devoid of context. Is “blue-1” a text link color? A background shade? An accent for alerts? The name offers no clues, forcing everyone to guess or hunt through documentation.Descriptive:
color.background.primary– This name tells a story at a glance: it’s the primary background color. No guesswork needed – designers and developers immediately know where this token applies.
In the second case, the token name itself effectively asks and answers, “What is this for?” (a primary background) and “Where do I use it?” (where a primary background is needed). The clarity speeds up design and implementation because nobody has to play detective.
When token names are phrased as answers, the design system starts to feel like a well-written Q&A with each token effortlessly explaining its role.
On the other hand, unclear or overly generic token names can lead to chaos. A poorly defined naming convention can trigger “token sprawl,” where redundant or ambiguous names proliferate.
Imagine multiple teams each creating a token for the same color because none of them are sure which name to trust. This isn’t a hypothetical scenario – it happens often. For instance, one company’s design system ended up with tokens named primary-color, main-color, primary-500, button-primary-bg, brand-main, and base-color-1 all referring to the exact same shade. Each team had coined their own term for “the main brand color.” The result was confusion and duplicate tokens everywhere. When the brand color eventually changed, updating these scattered tokens became an overwhelming task. This kind of misalignment erodes trust: if developers and designers aren’t sure which token to use, they might bypass the system altogether or introduce hacks. In essence, the narrative of the design system breaks down – it’s as if different chapters of a book started contradicting each other.
A Button, a Story: An Example of Naming Clarity
Let’s bring this to a concrete example. Consider a design token meant for a button’s color. Originally, we might name it buttonColor. At first glance that seems straightforward – until a developer new to the project asks, “Does buttonColor mean the button’s text color? Its background fill? The border color on focus?” The name alone doesn’t tell us. In fact, it raises a hidden question: “Which aspect of the button does this target?” In our case, say buttonColor was intended to be the background color for primary buttons. If someone mistakenly uses it for text, the interface could fail accessibility or just look wrong. The token’s name wasn’t telling its full story.
How do we refine that token’s narrative? By renaming it to something that answers the unasked question. We might choose button.primary.bg (short for “button primary background”). Now, anyone encountering this token can instantly parse its meaning: it’s the background color for primary buttons. The next developer won’t have to wonder or ask for clarification – the name itself has answered “what is this for?” and “where do I use it?” This small change can prevent a lot of misinterpretation. In our team, the renaming led to immediate improvements: designers stopped second-guessing whether they picked the right token, and developers applied the styles more quickly, confident they had the intended one. We effectively turned a cryptic token into a self-explanatory snippet of design language.
This exercise might seem minor, but it highlights a powerful principle: naming is designing. When we refine a token name, we’re refining the design system’s communication. We’re making the interface more readable not just for machines, but for humans. It’s akin to editing a sentence so that its meaning is clear and cannot be misconstrued. A well-named token builds trust – the team trusts that the token will do what its name implies, and that trust leads to smoother collaboration.
Even Systems Have Narrative Power
It’s easy to think of a design system as a cold collection of guidelines and code. But in the Ink to Interface philosophy, we recognize that systems have narrative power when crafted with clarity and intent. The way your tokens are named and organized can tell a story about your product’s design values. Is your system chaotic, with arbitrary names? That tells a story of its own – one of rushed decisions or fragmented teams. Is it orderly and meaningful? That narrates a tale of thoughtful design and cohesive vision.
When each token carries a clear meaning, the entire design system becomes like a well-composed piece of writing. You can read the interface by reading the tokens.
For example, a glance at a stylesheet might reveal tokens like color.alert.error, button.primary.bg, spacing.form.padding.
Without seeing the actual UI, you already know so much: there’s an error state with a specific color, primary buttons have a defined background, forms have consistent padding. The tokens are telling you the design story. This level of clarity emerges only when tokens are named with purpose and context.
By contrast, if you saw red-2, blue-1, padding-small-2 in that stylesheet, you’d have a much harder time picturing the design. The story is lost. You’d probably have to dig into documentation or ask someone what each token is for – analogous to a reader having to consult footnotes for every other sentence. That’s not the experience we want for anyone working with our design system.
Ultimately, clarity in token naming isn’t about pedantry; it’s about empathy. It’s recognizing that every token will be read by someone – a colleague, your future self, or even a different team at your company.
By crafting token names that answer the hidden questions, we show care for those readers. We ensure the design system’s narrative is accessible and trustworthy.
Take a moment this week to examine one token in your design system that has always felt a bit unclear or “generic.”
Ask yourself: what question is this token’s name not answering? Is it “What component is this for?” or “What exact role does it play?” See if you can rename it (even hypothetically) to better tell its story. By treating tokens as tiny narratives, you’ll start to strengthen the overall story your design system tells.
Reflect on how this small naming tweak could align designers and developers more closely. After all, big picture alignment often starts with a single source-of-truth word.