Getting Started

Why Design Tokens?

The case for a single source of truth for every visual value in your design system — and what breaks without one.

💡

In one sentence: Design tokens are named variables that store your design decisions (colors, spacing, typography) so they can be shared identically between Figma and code — and changed in one place.

The Problem Without Tokens

Imagine a primary brand color, purple #9333EA. Without tokens, this value lives in:

Figma fill swatches (hardcoded hex)
CSS files (background-color: #9333EA)
SCSS variables ($brand: #9333EA)
Mobile apps (UIColor, Color resources)
Documentation screenshots

When the brand color changes, every one of those locations must be found and updated manually. Some get missed. Inconsistency creeps in. The design system drifts.

⚠️

The Drift Problem Without tokens, Figma and code inevitably drift apart. A designer changes a color in Figma; a developer updates CSS independently. Six months later, no one knows which is "correct."

The Solution: Named Variables

A design token replaces the raw value with a name that carries intent:

Before vs After

/* Before — raw values everywhere */
background-color: #9333EA;
color: #FFFFFF;
border-radius: 8px;
font-size: 14px;

/* After — tokens with meaning */
background-color: var(--brand-color);
color: var(--brand-on-color);
border-radius: var(--radius-md);
font-size: var(--font-size-sm);

Three Core Benefits

🔄 Single Source of Truth

Change one token definition and every component in every platform updates. No hunting, no drift.

🌓 Theming Made Easy

Dark mode, multiple brands, seasonal themes — all handled by switching which values the tokens resolve to. Zero component changes.

🤝 Designer–Developer Sync

Figma variables and CSS custom properties use the same token names. When Figma changes, code follows the same spec automatically.

Tokens Carry Intent, Not Just Values

The real power is semantic naming. Compare these two approaches to the same color:

Approach	Variable name	What it tells you
Raw value	`#9333EA`	Nothing — just a hex. Where is it used? Can it be changed?
Descriptive name	`purple-600`	It's purple, medium shade. Still says nothing about where to use it.
Semantic token	`brand-color`	It's the brand's primary accent. Use it for filled backgrounds, active states, CTAs.
Component token	`button-bg`	It's the background of a button. Resolves to whatever the brand's primary color is.

✅

The Golden Principle A token's name should describe where it is used, not what it looks like. brand-color is good. purple is bad.

How CocoKits Uses Tokens

CocoKits uses a three-tier token architecture:

Primitives

Raw values — colors, spacing, sizes

↓

Semantic

Brand palette + meaningful roles

↓

Component

Size, structure, color per component

Each tier only references the tier directly above it. Primitives hold raw values. Semantic tokens alias primitives with meaning. Component tokens alias semantic tokens with context. This creates a stable, predictable chain where changes flow naturally downward.

← Previous Home Next → Glossary