Design Token Generator

Tokens are named decisions, not variables

The value of a token system is not that colours live in one place. It is that each value carries a name expressing intent, so changing what a decision means changes every use of it. A codebase full of --blue-500 has centralised its hex codes and nothing more; one built on --color-action-primary can be rethemed, because the name says what the value is for.

Three layers, and the middle one does the work

Primitive tokens are the raw palette: --blue-500: #3b82f6. Semantic tokens map meaning onto primitives: --color-action-primary: var(--blue-500). Component tokens map components onto semantics: --button-bg: var(--color-action-primary). Components reference only the semantic layer, never primitives. That indirection is what makes dark mode a redefinition of the semantic layer rather than an audit of every component.

Dark mode is where flat systems break

With a flat system, dark mode means finding every use of every colour. With semantic tokens, it means redefining what --color-surface and --color-text-primary resolve to and changing nothing else. This is the clearest practical argument for the layering, and it is usually discovered the hard way.

Naming is the hardest part

A workable convention is category, property, variant, state — color-text-primary, space-inset-sm, font-size-heading-lg. Avoid names describing appearance, because --color-light-grey in a dark theme is a lie the system has to carry forever. Names should survive a rebrand.

Scales, not arbitrary values

Spacing on a consistent scale — typically a 4 or 8 pixel base — removes a category of decision and produces visual rhythm. The same reasoning applies to type sizes, radii, shadows and durations. Five well-chosen steps that people use beat twenty that get bypassed, and any value not on the scale should be a deliberate exception rather than an accident.

One source, many outputs

Tokens defined once in a neutral format and transformed into CSS variables, iOS, Android and documentation keep platforms genuinely in sync. Maintaining separate lists per platform guarantees drift, and the drift is invisible until someone compares two screenshots side by side.