What this is
A workshop collection for systematic token naming
This site gathers a written handbook and interactive HTML tools that teach the same idea: token names should encode where something lives, what it does, and how it relates to everything else.
Built for designers, engineers, and design-system leads who want naming decisions that scale — and stay legible to both humans and LLMs.
How to use it
Read first, practice in layer order
Work through the material as a path, not a grab-bag. Keep the reference card open while you exercise.
- Read the handbook Start with Systems Thinking and Token Naming — or download the PDF.
- Keep the reference card nearby Open the naming reference card for mental models, tiers, domains, and failure modes.
- Practice Layer 2 → 4 Use the anatomy mapper, then the three-tier chain builder, then the naming worksheet.
- Build your convention Define axes and export stubs with the token naming builder.
Six layers
The framework at a glance
Each layer builds on the one before it. Layers with a matching exercise link to their tool.
-
01
Systems thinking
Names as rules and coordinates — interconnectedness, hierarchy, and feedback.
-
02
Anatomy mapper →
Component anatomy and naming
Decompose parts, properties, and states into consistent name formulas.
-
03
Chain builder →
Three-tier token structure
Primitive → semantic → component chains that survive value change.
-
04
Worksheet →
Naming templates
Decision records and templates so every name answers the right questions.
-
05
Documentation workflows
Keep naming decisions findable and current as the system evolves.
-
06
LLM-assisted workflows
Use systematic naming so humans and models can locate and extend tokens.
Tools
Hands-on workshop exercises
Self-contained HTML tools — open any of them directly in the browser.
-
Design system naming reference card
Complete reference covering all six workshop layers — mental models, tiers, domains, anatomy, questions, and failure modes.
-
Component anatomy mapper
Map a component’s parts, properties, and states — then watch token names generate live from [component]-[part]-[property]-[state].
-
Three-tier token chain builder
Build a complete token chain from primitive → semantic → component, with live visualization and tier validation.
-
Token naming worksheet
Answer six questions for any token. The decision record assembles as you type — copy or download it into your docs.
-
Token naming builder
Define the axes that make up your token names, populate categories, and export a naming convention reference plus DTCG-shaped JSON and CSS stubs.
-
Token value builder
Import naming-builder tokens, fill typed DTCG and Terrazzo values, preserve aliases, and export completed JSON.
Handbook
Systems Thinking and Token Naming
The full curriculum for layers 1–6. Read it on GitHub, or download the printable PDF from this site.