designtoken.md vs Style Dictionary

Build system vs machine-readable standard

Style Dictionary is a build system that transforms design token JSON into platform-specific outputs. designtoken.md is the machine-readable standard that gives coding agents rich design context — and its generator outputs DTCG-compliant JSON, CSS variables, and more. One is a build step. The other is a superset that includes that step.

The build system

What is Style Dictionary?

Style Dictionary takes design token JSON files and transforms them into platform-specific outputs: CSS variables, iOS Swift constants, Android XML resources. It's a build-time tool — it runs in your CI pipeline, reads a token source, and outputs formatted files. Created by Amazon, now the industry standard maintained by the open-source community. Uses the W3C DTCG format as input.

The machine-readable standard

What is designtoken.md?

A designtoken.md standardizes design context as structured markdown — the format coding agents read natively. But the generator also outputs DTCG-compliant JSON, CSS variables, Tailwind config, and other formats. It's a superset: full color scales, typography hierarchies, spacing systems, and component tokens in a machine-readable file that sits in your project root. The markdown is the standard. The outputs cover every format Style Dictionary consumes.

Feature breakdown

Token by token

A detailed comparison of what each tool covers.

Feature	Style Dictionary	designtoken.md
Format	JSON (DTCG spec)	Structured Markdown + DTCG JSON, CSS, Tailwind outputs
When it runs	Build time (CI/CD)	Generation time (agent reads it)
Output	CSS vars, iOS, Android, etc.	Agent-generated UI code + DTCG JSON, CSS vars, Tailwind
Requires	Node.js, build pipeline	Nothing — just a file
Audience	Engineers maintaining design systems	Anyone using coding agents
Token depth	Flat key-value pairs	Full scales, hierarchies, component states
Brand context	Token values only	Values + relationships + intent
Setup complexity	Config files, transforms, formats	Drop file in project root

Guidance

When to use each

Both tools have a place. Here's how to choose.

Use Style Dictionary when:

You maintain a multi-platform design system and need compiled token outputs for iOS, Android, and web.
Your tokens need to be distributed to multiple teams and tools as JSON.
You have a centralized token source and need many platform-specific formats.
Your design tools export DTCG JSON that you want to compile into different languages.

Use designtoken.md when:

You're using coding agents to build UI and want consistent, on-brand output without a build pipeline.
Your team uses Claude Code, Cursor, Copilot, or other markdown-reading agents daily.
You want agents to understand the full context of your design system — scales, relationships, and intent.
You want a file you can commit to your project repo that agents can read directly.

Or just use designtoken.md: The generator already outputs DTCG-compliant JSON, CSS variables, and Tailwind config — the same formats Style Dictionary produces. If you're starting fresh, designtoken.md gives you the machine-readable markdown standard for agents plus all the compiled outputs, without a separate build step.

FAQ

Common questions

Can I generate a designtoken.md from Style Dictionary tokens?

Yes. If you already have Style Dictionary JSON, you can use the designtoken.md generator to create a richer markdown version that includes scales, hierarchies, and component relationships your agents can read directly. This bridges the gap between build-time token compilation and agent-readable context.

Does designtoken.md replace Style Dictionary?

It can. The designtoken.md generator outputs DTCG-compliant JSON, CSS variables, and Tailwind config — the same formats Style Dictionary produces. If you already have Style Dictionary in your pipeline, designtoken.md adds the machine-readable markdown layer on top. If you're starting fresh, designtoken.md covers both: the agent-readable standard and the compiled outputs.

Which coding agents support designtoken.md?

Any agent that reads project context files: Claude Code, Cursor, Copilot, Codex, Gemini CLI, and Windsurf. No special integration needed — it's standard markdown. Any LLM that can parse your project files will understand it.