Missing Tokens

Missing tokens is the silent killer of design systems, particularly for typography. It happens when your meticulously crafted type scale, font pairings, weight rules, and spacing standards exist only in design tools like Figma or Sketch, but fail to make the leap into the codebase as explicit, named design tokens or CSS custom properties. Imagine designing a precise blueprint for a house, specifying every dimension and material. Then, the builders receive only a picture, forcing them to guess exact measurements and finishes. For typography, this means your H1 might be 48px in Figma, but without a `font-size-h1` token, a developer might hardcode `48px`, `3rem`, or `2.5em` depending on their preference or framework. Your carefully chosen line height of 1.2 for headings becomes an arbitrary `120%` or `1.2em` in CSS. Letter spacing, paragraph spacing, responsive adjustments, all these nuanced decisions get lost in translation. The system exists in theory, a beautiful artifact in your design file, but it doesn't exist where it matters most: in the actual product code. This disconnect guarantees inconsistency, design drift, and endless visual QA cycles where designers point out "it doesn't look right" and developers respond "it matches the Figma file." The problem isn't that the design system is bad; it's that it's incomplete, lacking the critical bridge that connects design intent to coded reality.

Missing tokens isn't just a developer problem, nor is it solely a designer's fault. It's not a bug that can be fixed with a quick patch. It's not solved by simply having a "style guide" document that developers are expected to read and interpret. A PDF or Confluence page detailing your typography rules is helpful for context, but it's not an executable contract. It isn't about designers needing to write all the CSS themselves; that's a misinterpretation of roles. Design tokens are framework-agnostic; they are abstract values consumable by any technology stack. Furthermore, missing tokens isn't the same as having a poorly designed typography system. You can have the most elegant, mathematically perfect type scale and font pairings in the world, but if those values aren't tokenized, they remain aspirational. It's not a lack of design effort; it's a lack of systemization at the crucial handoff point. It's not about "eyeballing it" being inherently wrong; it's about making "eyeballing it" the only option because the precise, codified values aren't available. It's not a temporary oversight; it's a fundamental gap in your design system's infrastructure that will compound over time, making every new feature and design iteration a battle against inconsistency.

Imagine "InnovateCo," a tech company known for its sleek interfaces. Their design team spent months crafting a sophisticated typography system in Figma: a Major Third type scale, Inter for UI, Lora for editorial, precise line heights, subtle letter spacing. Their Figma file is a masterpiece. Now, a new dashboard feature needs building. The front-end team, using React and Tailwind CSS, starts implementation. Designers hand over the Figma link. Developers see "H1" in Figma at 48px, bold. They see "Body Text" at 16px, regular. But they find no `text-h1` or `font-size-body` tokens in their codebase. They have `text-4xl` from Tailwind, which is `2.25rem` (36px), and `font-bold`. For the H1, they might override Tailwind with `text-[48px]` or `text-[3rem]`. For body text, they use `text-base` (16px), but the line height defaults to `1.5` in Tailwind, not the custom `1.4` the designers specified for dense data tables. A few weeks later, the marketing team launches a new landing page using Gatsby. Their developers, seeing the same 48px H1, might use a CSS variable like `--heading-1-size: 3rem;` and `--heading-1-weight: 700;`. The email team, using a custom templating engine, just hardcodes `font-size: 48px; font-weight: bold;` directly into their HTML. The result? Three different products, all ostensibly using the "same" typography system, but with subtle, infuriating differences in font size, weight, and spacing. The H1 on the dashboard is slightly smaller than the H1 on the landing page. The body text in the email has a different line height than the app. The brand feels "off," inconsistent, even though everyone is technically using Inter and Lora. This is missing tokens in action: a beautiful design system, fractured into a thousand inconsistent implementations because the values were never codified into a single source of truth for developers to consume.

You must implement design tokens to prevent "missing tokens" from the very inception of your design system. This isn't an optional step; it's foundational. Start tokenizing your typography values as soon as you've defined your base font size, type scale ratio, and core font families. As you establish weight rules, line heights, letter spacing, and responsive behaviors, each decision must be translated into a corresponding token. For example, `font-size-h1`, `font-weight-bold`, `line-height-body`, `letter-spacing-display`, `font-family-primary`, `font-family-secondary`. These tokens should be generated and made available to developers in formats they can consume: JSON, CSS custom properties, Sass variables, JavaScript objects. Tools like Style Dictionary, Figma Tokens (now Tokens Studio), or custom scripts can automate this. Use tokens to ensure `text-h1` in your React app, `mdc-typography--headline1` in your Angular app, and `font-headline-large` in your iOS app all resolve to the exact same pixel value, weight, and line height. Use them to enable global changes, like switching to a new brand font or adjusting base size for accessibility, with a single token update. Empower developers to build new components with confidence, knowing they inherit correct, system-approved typographic styles. Conversely, you absolutely do not skip tokenization. There is no scenario where "we'll do it later" makes sense for a typography system. Delaying tokenization is like building a house without a foundation; it will inevitably crumble under the weight of future development. Do not rely on manual interpretation of design files. Do not expect developers to "just know" the correct values. Do not assume visual QA will catch every subtle typographic inconsistency across hundreds of components and pages. Do not fall into the trap of thinking that because your design system is "documented," it is also "implemented." Documentation is descriptive; tokens are prescriptive. If your design system is a set of rules, tokens are the enforcement mechanism. Without them, your typography system is a suggestion, not a standard. The cost of retrofitting a token system into an existing, inconsistent codebase is exponentially higher than building it in from the start. Prevent design drift by tokenizing your typography from day one.

If your typography system isn't tokenized, it's a beautiful idea, not a functional reality.