Design Foundational Reusable Components with Style Dictionary

Why Style Dictionary?

Style Dictionary is a build system that transforms design tokens into platform-specific code, enabling teams to define design decisions once and deploy them everywhere. The key benefit lies in its platform-agnostic approach--design tokens are authored in a single format, and Style Dictionary handles the transformation to CSS custom properties, SCSS variables, JavaScript modules, iOS Swift classes, Android resources, and more. This unified workflow eliminates the need for separate design value management for each platform.

For teams building AI-powered applications, Style Dictionary provides a consistent design foundation that scales across all interfaces, ensuring brand consistency even as automated systems generate UI components dynamically.

How Style Dictionary Works

The Style Dictionary transformation pipeline follows a clear three-stage process. First, it parses input files--typically JSON or JSON5 files containing design token definitions. Second, it processes these tokens through transforms that modify names, values, and attributes to match the target platform requirements. Third, it formats the transformed tokens into the appropriate output code for each platform. This architecture allows developers to maintain a single source of truth while automatically generating all the code their platforms need. As demonstrated in the LogRocket tutorial, this approach significantly reduces maintenance overhead and ensures consistency across all touchpoints.

Setting Up Style Dictionary

Getting started with Style Dictionary requires minimal setup. The tool is distributed as an npm package and can be installed in any Node.js project. Once installed, you configure Style Dictionary with a JavaScript or JSON configuration file that specifies your token sources, desired output platforms, and any custom transforms or formats.

Our web development services team regularly implements Style Dictionary for clients building design systems that need to scale across multiple products and platforms.

Installation

Install Style Dictionary using npm or yarn in your project directory:

npm install style-dictionary

You can use Style Dictionary either as a command-line tool or programmatically within your build scripts. The CLI approach works well for simple setups, while programmatic usage offers more flexibility for complex build pipelines.

Project Structure

A well-organized Style Dictionary project typically follows this structure:

tokens/
├── colors/
│ ├── base.json
│ └── semantic.json
├── typography/
│ ├── font-family.json
│ └── font-size.json
└── spacing.json
build/
├── css/
├── scss/
├── js/
├── ios/
└── android/
config.js

The tokens/ directory contains your source JSON files organized by category. The build/ directory is where Style Dictionary outputs the generated platform-specific code. This separation keeps your source of truth distinct from generated artifacts.

Basic Configuration

The configuration file defines what tokens to process and how to transform them for each platform. Here's a configuration that outputs to CSS and JavaScript:

Defining Design Tokens

Design tokens are structured in JSON files using nested objects that follow the Category/Type/Item (CTI) naming pattern. This hierarchical structure groups related tokens together and creates meaningful, searchable paths like color.background.primary or spacing.md. The CTI pattern provides organization while keeping tokens discoverable and manageable at scale.

Token Naming Conventions

Consistent naming is crucial for maintainable design token systems. Style Dictionary recommends kebab-case for token names--lowercase with hyphens separating words. Each token path should reflect its purpose rather than its platform implementation. For example, color.background.button is better than button-bg-color because it groups all button-related tokens under the color hierarchy. Avoid reserved characters like {, }, ., and $ in token names as these have special meaning in token resolution.

Token Types

Different design attributes require different token types to properly describe their values:

• color: Hexadecimal, RGB, or HSL values for visual design elements
• dimension: Pixel, rem, or em units for spacing and sizing
• fontFamily: Font stack strings for typography
• fontWeight: Numeric values (100-900) or named weights (regular, bold)
• duration: Time values in seconds or milliseconds for animations
• cubicBezier: Easing function arrays for smooth animations

The Style Dictionary documentation provides comprehensive guidance on the CTI pattern and recommended token structures for different design attributes.

Referencing and Aliasing Tokens

Token aliasing is one of Style Dictionary's most powerful features, allowing tokens to reference other tokens using curly brace syntax. This enables the creation of semantic token layers--tokens that derive their values from more primitive base tokens. When a base token value changes, all tokens referencing it automatically update, making global theme changes trivial.

Building Token Hierarchies

A well-structured token system typically has two or three layers:

1. Primitive tokens contain raw design values like specific color hex codes or pixel measurements. These are often organized in files like colors/primitives.json.

2. Semantic tokens reference primitives and give them contextual meaning. For example, {color.text.primary} might resolve to the same blue as {color.blue.500} but signals its intended use.

3. Component tokens reference semantic tokens for specific component contexts, like {color.button.primary.background}.

This layered approach allows you to create multiple themes by swapping out primitive values while keeping semantic and component tokens unchanged. The Style Dictionary documentation covers aliasing patterns in detail.

Transforms and Transform Groups

Transforms are functions that modify token properties during the build process. They handle the platform-specific adjustments that turn generic token values into appropriate code for each target. Style Dictionary supports three types of transforms: name transforms that modify token names, value transforms that change token values, and attribute transforms that add or modify token metadata.

Built-in Transform Groups

Rather than configuring individual transforms, Style Dictionary provides pre-configured groups that include all necessary transforms for specific platforms:

Creating Custom Transforms

For specialized requirements, you can register custom transforms. A custom transform is a function that receives a token object and returns a modified version. Common use cases include unit conversions, color format transformations, or naming convention adjustments specific to your organization's standards.

Output Formats

Style Dictionary supports a wide range of output formats, each designed for specific platform requirements. Understanding these formats helps you choose the right output strategy for your project architecture.

CSS Custom Properties

CSS custom properties (CSS variables) are the most common output for web projects. Style Dictionary generates these with proper namespacing and can include them in a :root block for global availability:

:root {
 --color-primary: #0066cc;
 --spacing-md: 16px;
 --font-size-base: 16px;
}

JavaScript Modules

JavaScript and TypeScript output formats provide token objects that work well with component frameworks and enable programmatic access to design values:

export const color = {
 primary: '#0066cc'
};

export const spacing = {
 md: '16px'
};

These modules can be imported directly into components, enabling type-safe access to design tokens in TypeScript projects.

DTCG Format Compatibility

The Design Tokens Community Group (DTCG) specification, working within the W3C, has established a standardized format for design tokens to improve interoperability between tools and platforms. Style Dictionary v4 and later versions support this emerging standard, offering forward compatibility for teams adopting the specification.

DTCG vs Original Format

The primary difference between the original Style Dictionary format and DTCG format lies in property naming:

The DTCG format also supports type inheritance, where $type can be defined at a group level and inherited by all child tokens. This reduces repetition in large token systems.

Important: Do not mix formats within a single project. Choose either the original format or DTCG format and maintain consistency throughout your token files. The DTCG specification provides detailed guidance on the standard format.

Best Practices for Design Token Systems

Building a successful design token system requires thoughtful organization and consistent practices. These recommendations help teams create maintainable, scalable token architectures that stand the test of time.

Scaling Your Design System

As design systems grow, token management becomes more complex. Successful scaling strategies include:

Multi-brand token sets use a base design system with brand-specific token files that override or extend base tokens. This approach enables multiple products or brands to share a core infrastructure while maintaining unique identities.

Theming strategies for light/dark mode or other runtime themes use CSS custom properties combined with semantic tokens. Semantic tokens reference primitives that can be swapped based on theme context.

Token file splitting organizes tokens across multiple files organized by category, component, or brand. This prevents large, unwieldy files while maintaining clear organization.

CI/CD integration automates Style Dictionary builds as part of your deployment pipeline. This ensures generated files are always up-to-date and reduces manual build steps.

Integration with Design Tools

Modern design workflows connect tokens between design files and codebases. The Tokens Studio plugin for Figma enables designers to create and manage design tokens directly in Figma, with export capabilities to Style Dictionary format. This bidirectional workflow allows:

• Extracting tokens from Figma variables into Style Dictionary JSON files
• Syncing code-generated tokens back to Figma for design consistency
• Managing multi-dimensional tokens with modes for themes and states

For teams using Radix UI or similar component libraries, design tokens integrate seamlessly to provide consistent styling across all components while maintaining accessibility standards.

If you're building a comprehensive UI style guide, design tokens serve as the foundation that connects your documentation, code, and design specifications.

Sources

1. Style Dictionary Official Documentation - Comprehensive reference on design tokens, token attributes, aliasing, and platform-agnostic styling
2. LogRocket: Design foundational, reusable components with Style Dictionary - Practical tutorial covering setup, configuration, and multi-platform output
3. Design Tokens Community Group Specification - W3C-in-progress specification on design token format standards and interoperability