Design Token Examples That Actually Scale [With Code]

A design token file with 200 color variables isn’t a system. It’s a spreadsheet with syntax highlighting.

The difference between tokens that accelerate your team and tokens that slow them down comes down to structure—and most design token examples online skip that part entirely. They show you –color-primary: blue and move on, leaving you to figure out how that scales across platforms, themes, and a growing component library.

This guide delivers production-ready design token examples with the naming conventions, tier structures, and platform-specific formats that teams actually ship. You’ll see what separates tokens that work from tokens that become technical debt.

What Do Design Tokens Actually Look Like?

Design tokens are named values that store visual design decisions—colors, spacing, typography, shadows—in a platform-agnostic format. Instead of hardcoding #0066CC throughout your codebase, you define it once as a token like color.brand.primary and reference that token everywhere. When the brand color changes, you update one value. Every component using that token updates automatically.

Here’s a basic token definition in JSON:

{

  “color”: {

    “brand”: {

      “primary”: { “value”: “#0066CC” },

      “secondary”: { “value”: “#004488” }

    },

    “neutral”: {

      “100”: { “value”: “#FFFFFF” },

      “900”: { “value”: “#1A1A1A” }

    }

  }

}

That same structure outputs to CSS custom properties:

:root {

  –color-brand-primary: #0066CC;

  –color-brand-secondary: #004488;

  –color-neutral-100: #FFFFFF;

  –color-neutral-900: #1A1A1A;

}

This is where most tutorials stop. But a flat list of variables isn’t a design system. It’s a step toward one. The structure that makes tokens actually useful comes from how you layer them.

The Three Token Tiers Your System Needs

The teams we work with who struggle most with design tokens made the same mistake: they built a single tier of variables and called it done. Six months later, they’re renaming tokens across 40 files because –color-blue-500 is now the error color, not the primary brand.

Scalable token systems use three tiers:

Tier 1: Primitive Tokens (Raw Values)

These are your base palette. They describe what the value is, not how it’s used.

{

  “primitive”: {

    “blue”: {

      “500”: { “value”: “#0066CC” },

      “600”: { “value”: “#0052A3” }

    },

    “red”: {

      “500”: { “value”: “#CC0000” }

    },

    “spacing”: {

      “4”: { “value”: “4px” },

      “8”: { “value”: “8px” },

      “16”: { “value”: “16px” }

    }

  }

}

Primitive tokens never appear in your components. They’re the source—referenced by the next tier.

Tier 2: Semantic Tokens (Intent-Based)

Semantic tokens describe why a value is used. They reference primitives and give meaning to your design decisions.

{

  “semantic”: {

    “color”: {

      “brand”: {

        “primary”: { “value”: “{primitive.blue.500}” }

      },

      “feedback”: {

        “error”: { “value”: “{primitive.red.500}” }

      },

      “text”: {

        “default”: { “value”: “{primitive.neutral.900}” },

        “muted”: { “value”: “{primitive.neutral.500}” }

      }

    },

    “spacing”: {

      “component-gap”: { “value”: “{primitive.spacing.8}” }

    }

  }

}

When your brand color changes from blue to purple, you update one primitive. The semantic token color.brand.primary still works—it just points somewhere new.

Tier 3: Component Tokens (Scoped)

Component tokens bind semantic decisions to specific UI elements. This tier is optional but powerful for large systems.

{

  “component”: {

    “button”: {

      “primary”: {

        “background”: { “value”: “{semantic.color.brand.primary}” },

        “text”: { “value”: “{primitive.white}” }

      }

    },

    “input”: {

      “border-error”: { “value”: “{semantic.color.feedback.error}” }

    }

  }

}

Here’s what this structure gives you: When someone asks “what color is the primary button background?”—the answer is in the token name, not buried in a CSS file. And when that color needs to change, you know exactly where to look.

Design Token Naming Conventions That Scale

Naming is where token systems succeed or fail. The issue we keep running into with client codebases: inconsistent naming that makes tokens impossible to discover and risky to change.

Use this pattern: category.type.item.variant.state

Not every token needs every segment. But the order stays consistent.

Color Token Naming

color.brand.primary

color.brand.secondary

color.text.default

color.text.muted

color.text.inverse

color.background.surface

color.background.elevated

color.border.default

color.border.focus

color.feedback.error

color.feedback.success

color.feedback.warning

Spacing Token Naming

spacing.xs     (4px)

spacing.sm     (8px)

spacing.md     (16px)

spacing.lg     (24px)

spacing.xl     (32px)

spacing.2xl    (48px)

Avoid numbered spacing like spacing.4 in semantic tokens. spacing.md communicates intent; spacing.16 just restates the value.

Typography Token Naming

typography.heading.xl.fontSize

typography.heading.xl.lineHeight

typography.heading.xl.fontWeight

typography.body.md.fontSize

typography.body.sm.fontSize

The test: Can a developer unfamiliar with your system find the right token by guessing? If color.text.error doesn’t exist but color.feedback.error.text does, you’ve got a discoverability problem.

Platform-Specific Token Examples

Design tokens only matter if they work where your team builds. A JSON file sitting in a repo helps no one. Here’s how the same tokens output across platforms using tools like Style Dictionary—the kind of cross-platform engineering that separates proof-of-concepts from production systems:

CSS Custom Properties

:root {

  –color-brand-primary: #0066CC;

  –color-text-default: #1A1A1A;

  –spacing-md: 16px;

  –typography-body-md-font-size: 16px;

}

 

/* Dark theme override */

[data-theme=”dark”] {

  –color-brand-primary: #66B3FF;

  –color-text-default: #F5F5F5;

}

iOS (Swift)

extension UIColor {

  static let brandPrimary = UIColor(hex: “#0066CC”)

  static let textDefault = UIColor(hex: “#1A1A1A”)

}

 

extension CGFloat {

  static let spacingMd: CGFloat = 16

}

Android (XML)

<?xml version=”1.0″ encoding=”utf-8″?>

<resources>

  <color name=”color_brand_primary”>#0066CC</color>

  <color name=”color_text_default”>#1A1A1A</color>

  <dimen name=”spacing_md”>16dp</dimen>

</resources>

JSON (For JavaScript/React)

export const tokens = {

  color: {

    brand: {

      primary: ‘#0066CC’

    },

    text: {

      default: ‘#1A1A1A’

    }

  },

  spacing: {

    md: ’16px’

  }

};

 

The tooling handles the transformation. Your job is getting the source tokens right.

5 Token Structure Mistakes That Break Systems

After working on 40+ enterprise design systems, these are the patterns that consistently cause problems:

1. Naming Tokens After Visual Properties Instead of Intent

–blue-500 becomes meaningless when blue is no longer your brand color. –color-brand-primary survives a rebrand. Primitive tokens can use visual names. Semantic tokens should not.

2. Skipping the Semantic Layer

Teams that jump straight from primitives to components end up with tokens like –button-background: #0066CC. When someone needs that same blue for a link, they either duplicate the value or reference a button token for a non-button element. Both are wrong.

3. Over-Engineering Component Tokens

Not every component needs its own token tier. If your button just uses color.brand.primary directly, that’s fine. Create component tokens when you need to decouple a component’s appearance from the global semantic meaning—like when primary buttons should be blue even if the brand accent shifts to green.

4. Inconsistent Naming Depth

When color.text.primary lives alongside color.feedback.error.text.muted, developers spend more time searching for tokens than using them. Pick a structure. Stick with it.

5. No Theme Architecture From the Start

Retrofitting dark mode into a token system built without it is painful. Even if you’re shipping light-only today, structure your tokens so semantic values can swap primitives based on theme context.

Building Tokens Your Team Can Extend

Design tokens aren’t a deliverable you hand off and walk away from. They’re infrastructure your team will live in for years. The goal isn’t just a working token system—it’s a system your designers and developers can extend without breaking what’s already there.

That means documentation that explains why tokens are structured the way they are. It means naming conventions your team helped define, so they’ll actually follow them. And it means a contribution process, so new tokens don’t spawn in random files across your codebase.

The token structure in this article isn’t the only way to do it. But it’s a pattern that scales—one that’s held up across the digital products we’ve built with product teams.

Your tokens should make the right choice the easy choice. If developers are still hardcoding hex values six months after you ship, the token system didn’t fail. The system’s discoverability and documentation did.

Start with the three tiers. Get naming consistent. Build for the themes you’ll need, not just the one you have today. The rest is iteration—and that’s work your team can own.

Need help building a design system your team can extend? Let’s talk.