Guide8 min readUpdated
Design Tokens Explained: Making Design Readable by AI
Design tokens are named colour, spacing and type decisions. See a worked example, the shared token format, Style Dictionary and why AI tools need names.
Suppose a coaching centre in Siliguri has an app for its 300 students. The home screen uses one blue. The fee screen uses a slightly lighter blue. The results screen uses a third blue, because a different developer built that screen. Nobody chose three blues. Three people each typed a colour code by hand.
Design tokens are named design decisions, such as a colour, a spacing value or a text size, stored once and reused everywhere. With tokens, every screen asks for "primary colour" instead of a typed code. This guide gives you design tokens explained with a small worked example. Then it shows why names help developers and AI coding tools.
Checked in November 2026. Tools change quickly, so confirm details on the project's own page.
What are design tokens, in plain words?
A design token is a name attached to one design value. The name describes the purpose. The value can change later without changing the name.
Think of a contact saved in your phone. You tap "Ma" and you do not type her 10-digit number each time. If her number changes, you update the contact once. Every later call uses the new number. A token works the same way for a colour or a spacing value.
Tokens usually cover 4 kinds of decision:
- Colour: brand colour, text colour, error colour, background colour.
- Spacing: the gaps between items and the padding inside cards.
- Type: font family, text sizes, font weights and line height.
- Other details: corner radius, shadows and animation timing.
My guide on a design system for startups explains the wider system of components and rules. Tokens are the smallest layer of that system, and this guide stays on that layer.
What does a small token set look like? A worked example
A first product needs only a small token set, and I would start with fewer than 25 tokens. Imagine a tiffin subscription app in Durgapur called "Dabba Daily". The values below are invented for this example.
| Token name | Kind | Value | Where the token is used |
|---|---|---|---|
| color.brand.primary | Colour | #E4572E | Main buttons, active tab |
| color.text.default | Colour | #1F2933 | Body text |
| color.feedback.error | Colour | #C62828 | Error messages, failed payment |
| space.sm | Dimension | 8 px | Gap between an icon and its label |
| space.md | Dimension | 16 px | Screen side padding, gap between cards |
| space.lg | Dimension | 24 px | Gap between sections |
| font.size.body | Dimension | 16 px | Paragraphs and form fields |
| font.size.title | Dimension | 24 px | Screen titles |
| font.weight.bold | Font weight | 700 | Titles and prices |
Two habits make this set work.
First, name tokens by purpose, not by appearance. The name "color.brand.primary" survives a rebrand. The name "color.orange" becomes wrong on the day the brand turns green.
Second, let one token point to another. A token called "color.button.background" can point to "color.brand.primary". This pointer is called an alias. Suppose Dabba Daily wants a festive red for Durga Puja week. The team changes one value, and every button follows. After the festival, the team changes that one value back.
What is the design token format from the Design Tokens Community Group?
The design token format is a shared way to write tokens in a file, so that different tools can read the same file. The Design Tokens Community Group describes itself as a community of designers, developers and tooling vendors. According to its website, the group is standardising how design tokens are defined and exchanged. The website announces a first stable version of the specification.
According to the group's format specification, a token file is a JSON file. JSON is a plain text format for structured data that most software can read. The specification sets out these basics:
- A token is an object that has a "$value" property. The value is the actual colour, size or other decision.
- A "$type" property states the kind of token, such as color, dimension, fontFamily or fontWeight.
- An optional "$description" property explains the purpose of the token in plain text.
- Tokens can be organised into groups, like folders.
- An alias uses curly braces, for example {colors.blue}, to reuse the value of another token.
- A composite type called typography combines font family, font size, font weight, letter spacing and line height.
- The recommended file extensions are .tokens and .tokens.json.
My table above is simplified for reading. The specification writes colours and dimensions in a more structured way than a short code. Your developer should follow the specification and the documentation of the tool in use.
A founder should care for one reason. A token file in a shared format belongs to you, not to one design tool. If your team changes tools later, the decisions can travel.
What does Style Dictionary do with design tokens?
Style Dictionary turns one token file into the different files that each platform needs. According to the Style Dictionary documentation, the project is a build system that parses and transforms design tokens. It then exports them to platforms such as iOS, Android, CSS and JavaScript.
According to the documentation, the process works in these steps:
- The team keeps tokens in source files.
- Style Dictionary merges the token files and resolves references between tokens.
- Style Dictionary transforms the values separately for each target platform.
- Style Dictionary writes output files, such as CSS variables for a website and resource files for Android and iOS apps.
The practical meaning is simple. The website and the Android app both receive the same orange from one source. Nobody retypes a colour code.
The Style Dictionary documentation says the tool has first-class support for the Design Tokens Community Group format. The same page also says the newest version of that format is not fully supported yet. Ask your developer to check the current status before relying on newer parts of the format.
Why do named tokens help AI coding tools keep a product consistent?
Named tokens give an AI coding tool a short list of allowed choices, so the tool has less room to guess. This is my reasoning as a designer, not a guarantee from any tool.
An AI coding assistant writes code by following what it can read. Suppose the codebase has a typed colour code in 60 places. The assistant will copy that habit and add place number 61. Suppose the codebase has tokens instead. The assistant can see a small set of names and reuse them.
A name also carries intent. The name "color.feedback.error" tells a person and a model when to use that colour. A description on the token works like a short instruction. This is what a design system for AI coding tools means in practice: decisions written down in a form a machine can read.
Review also becomes easier. A developer can search generated code for raw colour codes and raw pixel values. Every raw value found is a mistake to fix. Named tokens also make the handoff in my Figma developer handoff checklist much shorter.
How can a small team start using design tokens this week?
A small team can start in one afternoon by auditing a few screens and naming what is already there.
- List every colour, text size and spacing value on your 5 most important screens.
- Merge the near-duplicates. Three blues become one blue.
- Name each value by purpose, as in the table above.
- Save the values as variables or styles in your design tool, so designs use names.
- Ask your developer to keep one token file in the code and generate the platform files from it.
- Add one rule to your team's AI coding tool instructions: "Use only tokens. Never type a raw colour code or pixel value."
- Check that text colours pass contrast on their backgrounds. My post on colour contrast in UI design explains how.
A designer at this step would audit the screens and propose the merged set. In an app project, I define tokens at the "Design the interface" stage, before the screens multiply. An app or website design usually takes me 2 to 4 weeks, and the token set is part of that work.
What are the limits of design tokens, and what stays human work?
Design tokens keep values consistent, but they do not make a design good. A poor layout built with tokens is a consistently poor layout.
- Too many tokens too early. A two-person team does not need 200 tokens. Start small and add a token only when a real need appears.
- Names need an owner. If anyone can add "blue2", the drift returns within weeks.
- Standards and tools are still moving. Moving tokens between tools may need manual cleanup. Check each tool's current documentation.
- AI tools can ignore tokens. A language model can still invent a value. A person must review generated screens, and model usage has a running cost.
- Privacy. A token file is rarely sensitive, but the codebase around it often is. Check what your AI provider does with your code.
Some work stays with people. A person chooses the values in the first place. A person tests line height with real Bengali or Hindi text, which often needs more room than English. My post on Bengali typography in UI and logo design covers that. Real users on real phones still decide whether 16 px body text is readable. For dark themes, my dark mode UI design guide shows how the same token names take different values.
If you want a token set and components designed for your product, my UI/UX design service includes them as part of the interface work.
Sources
Frequently asked questions
Are design tokens the same as a design system?
+
No. Design tokens are the smallest layer: named values for colour, spacing and type. A design system also includes components, patterns and rules for using them.
Does a small startup need design tokens?
+
A small token set helps even a product with 10 screens, because it stops near-duplicate colours and spacing from spreading. Start with fewer than 25 tokens and add more only when a real need appears.
Do design tokens work for both a website and a mobile app?
+
Yes. That is one of the main purposes. A tool such as Style Dictionary can convert one token file into separate files for web, Android and iOS, according to its documentation.
Can an AI coding tool follow design tokens automatically?
+
An AI coding tool can reuse tokens it can read, especially when the team instructs it to use only tokens. A language model can still invent values, so a person must review the generated code.
Working on something like this?
Tell Tithi what you are planning. You get a clear scope, a fixed price and a timeline before any work begins. I reply to every enquiry within 24 hours.