A Design System Is More Than Tokens

For a long time, I thought of a Design System as a collection of components, tokens, and documentation.

Colors. Typography. Spacing. Buttons. Inputs. Modals.

Everything neatly organized, named, and ready to be reused.

And while all of those things are important, I've recently realized that they don't fully describe what a Design System actually is.

A Design System is more than tokens.

Tokens describe what. They don't always explain why.

A design token can tell me that our primary color is #2563EB.

It can tell me that our spacing scale is based on 4px.

It can tell me that a button has an 8px border radius.

But it doesn't necessarily tell me:

• When should I use the primary color?
• When should I avoid it?
• Should every CTA use the primary button?
• Why did we choose an 8px radius?
• What should happen when two components compete for attention?
• How should a designer approach a completely new screen?

Tokens describe decisions that have already been made.

They don't necessarily communicate the reasoning behind those decisions.

And that distinction becomes increasingly important when we start designing with AI.

The Design System as a language

I've started thinking about a Design System less as a library and more as a language.

Tokens are part of that language.

Components are part of it too.

But a language also has grammar, meaning, rules, and context.

Imagine giving someone a dictionary containing every word in your language and asking them to write a good article.

Knowing the words isn't enough.

They also need to understand how those words are supposed to work together.

I think Design Systems have the same problem.

A collection of tokens and components tells us what exists.

A good Design System also tells us how to think.

From reusable assets to reusable decisions

This changes the way I think about documentation.

Traditional Design System documentation often focuses on questions like:

What is this component?

What properties does it have?

What variants are available?

Those questions are useful.

But I think we also need to ask:

When should I use it?

When shouldn't I use it?

What problem is it solving?

What alternatives exist?

What hierarchy should it create?

What are the common mistakes?

These aren't implementation details.

They're design knowledge.

And that knowledge is part of the Design System.

Why Markdown suddenly makes sense

This is what caught my attention when I came across Open Design and the idea of using a DESIGN.md file as part of a Design System.

At first, it might seem strange.

Why Markdown?

We already have JSON.

We have CSS variables.

We have Figma libraries.

We have Storybook.

We have component APIs.

But Markdown has something those formats don't optimize for:

communicating intent.

A document can explain:

## Buttons

Use the primary button for the main action
of a section.

Avoid using multiple primary buttons within
the same visual context.

Use secondary actions when the user has an
alternative path that is important but not
the primary goal.

That's very different from:

{
  "button": {
    "primary": {
      "background": "#2563EB",
      "radius": "8px"
    }
  }
}

The JSON describes the implementation.

The Markdown can describe the reasoning.

Both are valuable.

They simply answer different questions.

This becomes even more interesting with AI

This is where I think the idea becomes particularly relevant.

When a human designer opens a Figma library, they can inspect components, look at examples, and use their own experience to understand the system.

An AI agent doesn't naturally have that same context.

If I ask an agent:

Build a Product Detail Page using our Design System.

Giving it access to a list of colors and spacing tokens is not enough.

It needs to understand the rules behind the system.

For example:

• What is the visual hierarchy?
• How many primary actions should a page have?
• How should content density be handled?
• What type of card should be used for secondary information?
• Which components are preferred?
• Which patterns are intentionally discouraged?

This is why I find the idea of a human-readable Design System definition particularly interesting.

The Design System becomes not only something the application can execute, but also something an AI can reason about.

A possible future architecture

I'm starting to think about Design Systems as having multiple representations of the same underlying system.

Something like:

                  DESIGN SYSTEM
                        │
         ┌──────────────┼──────────────┐
         │              │              │
      DESIGN          TOKENS        COMPONENTS
       .md             .css          / React
         │              │              │
    Intent & rules   Values        Implementation
         │              │              │
         └──────────────┼──────────────┘
                        │
                   Product UI

Each layer has a different job.

DESIGN.md can describe principles, decisions, usage, and anti-patterns.

CSS variables can provide the actual values used by the product.

Components can provide the reusable implementation.

Figma can provide the visual design environment.

Documentation can connect all of these things together.

The goal isn't to replace one with another.

It's to make sure that each representation communicates what it's best at communicating.

Design Systems should preserve knowledge, not just assets

This might be the bigger realization for me.

A Design System shouldn't only answer:

"What components do we have?"

It should also preserve the knowledge that the team has accumulated while designing the product.

Why did we choose this pattern?

Why don't we use that one?

What should happen in this situation?

What does "good" look like?

What mistakes have we already learned to avoid?

That knowledge is incredibly valuable.

And when designers or developers leave a team, a lot of it disappears.

The Design System can become a place where that knowledge survives.

The AI-native Design System

I don't think AI changes what a Design System is.

I think it exposes something we were already missing.

If we want AI to design within our system, we can't only give it the building blocks.

We need to give it the rules.

Tokens tell the agent:

"These are the values."

Components tell it:

"These are the building blocks."

Documentation tells it:

"This is how they work."

But principles and decisions tell it:

"This is how we think."

And that may be the most important part.

A Design System isn't just a collection of reusable UI.

It's a collection of reusable decisions.

And perhaps that's what it means to say:

A Design System is more than tokens.