DEV Community: Dmitry Bychinsky

An LLM Thinks in Tokens

Dmitry Bychinsky — Wed, 01 Jul 2026 14:03:10 +0000

When a person looks at an interface, they see an image: buttons, spacing, colors, and the overall mood of the layout. We rarely think about it: perceiving design through a picture feels completely natural.

A language model has no such channel. It never looks at a screen. And that
changes almost everything about how you should feed it a design.

Everything Becomes Numbers

It is tempting to think that modern multimodal models solve the problem: since they can work with images, you could just give the model a screenshot and it would see the design the way a human does.

But multimodality is beside the point. Whatever you feed the model, text, image, or sound, becomes numbers on the inside. The model never handles a picture as a picture. It handles a numeric representation of one.

So the question isn't whether the model "sees" the design. It's which numeric representation the model ends up with.

And this is where a screenshot falls short. An image becomes numbers that describe pixels: lighter here, darker there, an edge over here. From that, the model can roughly guess that the spacing is around sixteen pixels and the color is some kind of blue. But that's guesswork from a picture, not knowledge of the design.

Which Numbers, Exactly

The difference is roughly like the difference between a photo of a book page and the text of the book itself.

The text is in the photo too. But to use it, you first have to recognize the letters, piece the words back together, and work out where a paragraph starts and where that's just a shadow on the page. Working with the text directly skips all of that guesswork.

Design works the same way. A screenshot, or even HTML with styles, makes the model reconstruct intent from form. But you can give it the intent directly, spelled out. That's what design tokens do.

A design token isn't a pixel or a line of CSS. It's a meaningful value with a name: the primary action color, the surface background, the padding inside a card, the corner radius of a panel. Tokens describe design the way a team talks about it: not "this blue right here," but "the primary action color, used everywhere there's a primary action."

As it happens, a language model's basic unit is also called a token. They're not the same thing: a model token is a chunk of text, a design token is a named design value. But they meet at the same point. Both are about turning meaning into a structure a machine can work with.

Why HTML and CSS Are Noise

You might object: HTML and CSS are text too, and the model reads them just fine. It does. The problem isn't that the model can't understand CSS. The problem is that HTML and CSS are full of things that have nothing to do with design.

Markup, nesting, utility classes, layout wrappers, color values copied from a mockup by hand over and over. The design is in there, but it's buried in noise. To work out that the same color in three different places is one and the same "primary color," the model has to guess all over again.

Tokens clear that noise away. What's left is just the design and the relationships between its parts, and the model no longer has to reconstruct anything.

The Experiment: One Task, Two Paths

Rather than argue in the abstract, we ran a small blind experiment.

We gave the task to several independent agents running on the same model, split into two groups. The design task was the same for everyone: build a product card. Only the prompt differed.

The first group got a straight assignment:

Create a product card with an image, title, price, rating and a buy button.
Return the HTML and a separate CSS file.

The second group got the exact same task, with one requirement added on top: describe the design in tokens first.

Create a product card with an image, title, price, rating and a buy
button. Return the HTML and a separate CSS file.

Before writing the CSS, define design tokens in the DTCG format in
three layers: primitive (raw values), semantic (roles referencing primitives), 
and component (component values referencing semantics).
The component styles must reference the tokens and must not hardcode values.

Nothing else differed between the groups. Neither group knew about the other approach or that the results would be compared. The difference was exactly one thing: whether the model had to build a design vocabulary first or could jump straight to markup.

Path One: Straight to HTML and CSS

The first observation caught us off guard. Even in direct mode, a modern model doesn't write colors straight into properties. It pulls the values out into CSS variables on its own:

:root {
  --color-surface: #ffffff;
  --color-accent: #4f46e5;
  --color-accent-hover: #4338ca;
  --radius-lg: 18px;
  --radius-md: 12px;
  --shadow-card: 0 10px 30px rgba(17, 24, 39, 0.08);
}

So the model largely settles the "variables versus magic numbers" debate by itself. But look closer and you can see where the direct approach still comes up short.

First, each variable does double duty. --color-accent is both a specific color from the palette and the "primary action" role. A single name answers two separate questions: "which color is this" and "what is it for." While those questions stay fused, you can't answer one without disturbing the other. Change the brand color in the palette, and you change the role along with it. Reassign the role to a different color, and you're back editing the same name. And nothing in the code tells you that a color and its hover variant are one brand color and its shade; that link lives only in the head of whoever wrote it.

Second, some values still ended up hardcoded in the components: a border-radius: 12px sitting next to a radius variable here, an outline with a color written as a standalone rgba(...) that ties back to nothing there.

Third, and this is the big one: the independent runs didn't line up. Different variable names (--color-accent versus --color-primary), different radii (18px versus 16px), one generation added a button shadow and the others didn't. Each agent reinvented its own vocabulary. No shared language emerged.

Path Two: Tokens First

The second mode looks different. The component styles hold no raw values at all, only references to tokens:

.card {
  background: var(--component-card-default-background);
  border-radius: var(--component-card-default-radius);
  box-shadow: var(--component-card-default-shadow);
}

.card__price {
  color: var(--component-card-price-color);
}

.card__button {
  background: var(--component-card-button-background);
}

.card__button:hover {
  background: var(--component-card-button-background-hover);
}

Behind those names sits a structure that pulls apart the two questions the direct version fused together. "Which color is this" lives in the primitives. "What is it for" lives in the semantics. A raw value shows up exactly once, in the primitives, and everything after that is references:

{
  "primitive": {
    "color": {
      "indigo-600": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.31, 0.275, 0.898],
          "hex": "#4f46e5"
        }
      },
      "indigo-500": {
        "$type": "color",
        "$value": {
          "colorSpace": "srgb",
          "components": [0.388, 0.4, 0.945],
          "hex": "#6366f1"
        }
      }
    }
  },
  "semantic": {
    "color": {
      "action-primary": {
        "$type": "color",
        "$value": "{primitive.color.indigo-600}"
      },
      "action-primary-hover": {
        "$type": "color",
        "$value": "{primitive.color.indigo-500}"
      }
    }
  },
  "component": {
    "button": {
      "primary": {
        "background": {
          "$type": "color",
          "$value": "{semantic.color.action-primary}"
        },
        "background-hover": {
          "$type": "color",
          "$value": "{semantic.color.action-primary-hover}"
        }
      }
    }
  }
}

The format is explicit and unambiguous: every token states its type, and a
reference to another token is plain to both a human and a tool. The model parses a format like this without misreading it, because there's nothing left to guess.

But the individual file isn't the interesting part; what happened across the independent runs is. Every agent in this mode built almost the same structure. Three levels: primitive, semantic, component. The same roles: surface for the background, action for the primary action, text-primary and text-secondary for text, rating for the rating. Different palettes, but the same skeleton.

Different agents, the same task, and out came a consistent design vocabulary. The direct mode never got there.

What the Experiment Showed

The experiment didn't measure whether the card comes out "prettier." All the variants look fine. It measured something else: how steadily and consistently the model describes the design.

In direct mode the model pulls values into variables, but a variable name carries the color and its role together, and the vocabulary comes out different every run. In token mode color and role sit on separate levels, the component has no raw values, and independent runs converge on one vocabulary.

The reason is the one already covered above. Tokens hand the model a way to think: base values first, then roles, then usage. That's closer to how the model works with data anyway, so the results come out more predictable.

There's one more takeaway, about the format. The model builds the structure with confidence, but it slips on the fine points of DTCG itself. Not one token run was valid on the first try: in one, dimensions were written as a string instead of a value-and-unit pair; in another, the primitive groups weren't grouped by type. But that's precisely the kind of problem tooling handles (see Design Token Kit).

The Design Lifecycle: With and Without Tokens

The difference doesn't show up at one moment, it runs through the whole life of a design.

Creating. Without tokens, the model scatters values through the code, or through a list of variables where color and role are fused, and it drifts out of sync from one run to the next. With tokens it sets up a design vocabulary first and then draws on it, so decisions get reused instead of reinvented.

Changing. Without tokens, "make the brand color darker" becomes a hunt across the whole project. With tokens it's one line in the primitives, and the change flows out to every place that references it.

Theming. Without tokens, a dark theme is often written almost from scratch. With tokens a theme is just a different set of values for the same roles, and the structure stays put.

Checking. Without tokens, it's hard even to say what counts as an error. With tokens the rules are clear: a reference points nowhere, a type doesn't match, a component reaches straight into a primitive and skips the semantics. All of that can be checked automatically.

At every stage tokens give the model the same thing: an explicit structure instead of a guess from form.

Token Formats

The same tokens can be written in more than one format. They don't differ in meaning, only in what the notation is optimized for.

DTCG (Design Tokens Community Group) is developed by the group of the same name at the W3C as an industry standard for describing tokens. It's already the de facto reference, even though work on the spec is still underway. Its main purpose is interoperability: the same tokens should be understood by different tools, and themes should be buildable on top of them. As the format's site puts it, DTCG JSON unlocks interoperability and theming between tools. That makes it a common language, a design written in DTCG moves between editors, build steps, and documentation without being rewritten. This is the format we gave the model in the experiment.

HRDT (Human-Readable Design Tokens) comes from the authors of design-token-kit, a more readable way to write the same tokens in YAML by hand. It's more compact than DTCG and round-trips to it without loss, so you can edit in YAML and still move tokens between tools in shared DTCG.

DESIGN.md comes from Google: Markdown with tokens in the YAML frontmatter, which design-token-kit supports. It covers a subset of a design (colors, typography, spacing, corner radii, components) and works well for keeping a short description of the system next to the docs. Richer types, such as shadows and gradients, fall outside it.

design-token-kit

Working with tokens is more than writing them: you have to check the structure, catch broken references, turn tokens into CSS, and see the result. Design Token Kit handles all of that.

It checks tokens, converts them, and builds a showcase. The DTCG tokens from the experiment are what we ran through it.

Checking tokens:

dtokens check tokens.json

Converting to CSS:

dtokens convert --outform css --out tokens.css tokens.json

Generating a showcase page:

dtokens showcase --out showcase.html tokens.json

Converting between formats:

dtokens convert --inform dtcg --outform hrdt --out tokens.yaml tokens.json

Conclusion

A person takes in design through an image. A model takes it in through numbers, and the only question is how meaningful those numbers are.

A screenshot, or even clean CSS, hands the model a design where the value and its meaning are fused and the links live only in the author's head. Design tokens hand it a structure instead: value on one side, role on the other, explicit references between them. In that form the model describes design far more consistently, which is what the experiment showed.

Design tokens aren't just for people. They turn out to be a good fit for the model too. And Design Token Kit makes that language easy to speak, without the busywork.

Design Token Kit: A Practical Toolkit for Design Tokens

Dmitry Bychinsky — Mon, 22 Jun 2026 09:53:18 +0000

Design tokens help keep colors, spacing, radius values, shadows, and other UI values in one place. It sounds simple: you create a JSON file, and things get better. In real work, validation, links between tokens, CSS variables, themes, showcase pages, and manual editing quickly appear around this simple idea.

What problem we wanted to solve

In the simplest form, design tokens can look like a normal set of values:

{
  "color": {
    "primary": "#3366ff",
    "background": "#ffffff",
    "text": "#111111"
  }
}

This format is easy to read, but it is not enough for a full tool. We need
types, rules, structure, theme support, aliases, and a clear processing
pipeline.

In a real project, questions appear very quickly: how to validate the token structure, how to make the format easy to edit by hand, how to convert tokens to CSS, and how to show the result on a static HTML page.

We wanted to make a small and clear tool that covers the basic workflow:
describe tokens, validate them, convert them to CSS, and view the result in a showcase.

What is Design Token Kit

Design Token Kit is an npm tool for working with design tokens.

It helps you go from a token file to a result that can already be used in a project: check the structure, find errors, generate CSS variables, and build a simple HTML page for viewing tokens in a browser.

The idea was not to create a large platform for design systems with everything inside. We wanted to build a clear tool: validation, conversion, and visual review.

DTCG JSON support

For the main JSON format, we decided to use DTCG, the format from the Design Tokens Community Group. The idea is to describe design tokens in a predictable way and move them between different tools without many custom rules.

In DTCG, a token is not just a value. It is an object with a clear structure. For example, a color token can look like this:

{
  "brand": {
    "color": {
      "$type": "color",
      "primary": {
        "$value": {
          "colorSpace": "srgb",
          "components": [0.2, 0.4, 1],
          "hex": "#3366ff"
        }
      }
    }
  }
}

This format is longer than a simple JSON file with colors, but it is easier for a tool to work with it. The tool can see the token type, check the structure, process references, find errors, and then safely use this data for conversion.

In Design Token Kit, DTCG JSON is one of the main input formats. It can be
validated, converted to CSS custom properties, converted to another format, and used to generate a showcase.

There is also an obvious downside: writing this JSON by hand is not always
comfortable.

When there are many tokens, themes, aliases, and nested groups, the file quickly becomes large. That is why we added a more compact format for manual editing together with DTCG JSON: HRDT YAML.

Why we needed HRDT YAML

HRDT means Human-Readable Design Tokens. Its goal is to make token files more compact and easier for people to read, but still keep the same processing pipeline.

It is not always convenient to write $type, $value, colorSpace, components, and several levels of nesting when you only need to add a new color or change a spacing value.

In HRDT YAML, the same set of tokens can look much simpler:

primitive:
  color:
    white: "#ffffff"
    brand-500: "#2549f6"

semantic:
  color:
    background-page: "{primitive.color.white}"
    action-primary: "{primitive.color.brand-500}"

component:
  button:
    primary:
      background: "{semantic.color.action-primary}"

This file is easier to read, easier to edit, and easier to discuss with the team. Fewer brackets also mean fewer chances to get lost. YAML does not pretend to save the world, but for writing tokens by hand it is much more convenient.

In real project files, HRDT is built around three top levels: primitive, semantic, and component. primitive stores base values. semantic describes roles like background, text, or spacing. component connects these roles to specific parts of the interface. Because of this, the structure shows where the base values are, where the meaning is, and where component settings are.

At the same time, HRDT YAML does not replace DTCG JSON. Inside the tool, YAML is converted to the common token model and then goes through the same path: checking, CSS conversion, and **showcase **generation.

Architecture: core and cli

We split the project into two parts: @design-token-kit/core and
@design-token-kit/cli.

core is the main logic. It reads tokens, converts them to a common internal model, validates them, converts them to CSS, and prepares data for the showcase.

cli is the layer for terminal usage. It parses commands, accepts file paths and options, and calls the needed features from core.

This split helps keep the main token processing logic separate from the command line. The CLI stays as a convenient way to run the tool, and core can grow as a separate library.

This is useful for the future. The same logic can be used not only through the dtokens command, but also in other places: for example, in a project build, a CI pipeline, a separate interface, or design system documentation.

As a result, the CLI is responsible for how the user runs commands, and core is responsible for what happens with the tokens inside.

CLI commands

The main work with Design Token Kit is done through the dtokens command.

Most examples below use files, but the tool can also read tokens from stdin and URLs. This is useful for pipelines, CI, and cases where tokens are passed between commands without a temporary file.

When no output file is specified, command results can be written to stdout.

Right now, the CLI has three main commands: check, convert, and showcase.

Check

The check command is the main way to validate token files:

dtokens check tokens.json
dtokens check tokens.yaml

It helps find errors before tokens get into CSS or into the application.

The command supports three scopes.

Schema checks only the input structure:

dtokens check tokens.json --scope schema

Validate runs schema checks and model-level checks:

dtokens check tokens.yaml --scope validate

Lint runs everything from validate and then adds architecture checks:

dtokens check tokens.yaml --scope lint

This split is useful because not every problem is the same kind of problem. A file can be structurally valid, but still contain broken references or architecture mistakes.

At the validate level, the tool checks problems such as missing references, circular references, references to groups instead of tokens, type mismatches, deprecated references, and duplicate gradient stop positions.

At the lint level, the tool also checks token architecture rules. For example, it can report invalid cross-layer references and raw values used above the lowest layer.

Convert

The convert command converts tokens between formats:

dtokens convert tokens.json
dtokens convert tokens.yaml --inform hrdt --outform css --out tokens.css
dtokens convert tokens.json --outform hrdt

With this command, you can get CSS custom properties, convert DTCG JSON to HRDT YAML, or convert HRDT YAML back to DTCG JSON.

For example, if tokens are written in YAML, they can be converted to a CSS file and used in a project:

dtokens convert tokens.yaml --inform hrdt --outform css --out tokens.css

The result will be a normal CSS file with variables.

Showcase

The showcase command generates an HTML page for viewing tokens:

dtokens showcase tokens.yaml --out showcase.html

The showcase can be built from token files or from CSS.

This is useful when you want to quickly check what you got after conversion: colors, spacing, radius values, shadows, and other values. You do not need to start a separate app or build large documentation. You just open an HTML file in the browser.

The tool can be installed in a project, installed globally, or run with npx.

For us, it was important that the basic scenario stayed simple: you have a token file, and you can validate it, convert it, and view the result.

Working with themes

Design tokens rarely live in only one version. Usually, a dark theme or extra color schemes appear next to the base values quite quickly.

That is why we treated theme support as one of the basic scenarios in Design Token Kit.

The idea is simple: some tokens describe default values, and some tokens
describe values for a specific theme. During CSS conversion, this becomes a set of variables for the base state and separate blocks for themes.

For example:

:root {
  --background-color-base: #ffffff;
  --text-color-primary: #111111;
}

:root[data-theme="dark"] {
    --background-color-base: #111111;
    --text-color-primary: #ffffff;
}

Themes are also important in the showcase. The showcase should not only show a list of tokens. It should also help users understand which values belong to the base set and which values belong to a specific theme. Otherwise, you can get a table of variables, but still not really see how tokens are split between themes.

For now, we keep theme display simple: we show information about available
themes and the tokens themselves, without a complex switcher. For the first step, this is enough to check the structure and see that the theme was included in the result.

What was the hardest part

At first, design tokens look like a clean list of values: colors here, spacing there, radius values somewhere nearby. Almost like a shopping list, but instead of bread and milk, you have primary, background, and spacing.

But the more you work with them, the clearer it becomes: the values are not the only important part. The links between them matter too. You need to understand the input format, convert tokens to a common model, check the structure, process references, keep themes working, and still return a result that can be used later.

Errors are a separate story. Just saying “something went wrong” is not very helpful. The tool should show where the exact problem is: a reference points to a missing token, a circular dependency appeared, types do not match, or a whole group was used instead of a real token.

Another difficult part is the balance between a strict format and comfort for people. A format that is too flexible is hard to validate. A format that is too strict is hard to write by hand. A good design token tool lives somewhere between these two sides.

What's next

Right now, Design Token Kit covers the basic scenario: tokens can be described, validated, converted to CSS, and viewed in a showcase. Next, we want to make the tool smarter when working with tokens.

One direction is diagnostics: finding unused tokens, empty groups, tokens
without descriptions, and other token hygiene problems.

Some architecture diagnostics are already implemented. For example, the tool can already report invalid cross-layer references and raw values used above the primitive layer. The next step is to expand this set with more design-system rules and clearer diagnostics.

We also want to improve the showcase. Right now, it is a simple HTML page for viewing tokens, but later it can become more useful: show themes better, group values better, add more visual examples, and help users understand faster what is really inside a token file.

Another direction is export support. CSS custom properties are a good basic option, but tokens may also be needed in other formats: SCSS, Tailwind config, Android XML, and iOS Swift.

Ideally, Design Token Kit should stay small and easy to understand, but slowly take more routine work around tokens: check them, give hints, show them, and convert them.

Design Token Kit started as a small tool for our own workflow.
Over time, it became a useful way to validate, convert, and inspect design tokens. We hope it can also be useful for other teams working with design systems.

GitHub repository