Organising Outputs with Style Dictionary

1. Getting Started With Style Dictionary
2. Outputting to Different Formats with Style Dictionary
3. Beyond JSON: Exploring File Formats for Design Tokens
4. Converting Tokens with Style Dictionary
5. Organising Outputs with Style Dictionary – You are here
6. Layers, referencing tokens in Style Dictionary

As a design system grows, organising design token outputs can become increasingly important. Without a clear structure, managing tokens could become unwieldy, especially when generating outputs for different platforms or tailoring outputs for specific use cases.

Thoughtfully structuring your token outputs into folders and files creates a scalable foundation that simplifies maintenance and improves collaboration across teams.

In Part 2 of this series, we explored how to output design tokens in different formats for various platforms, such as CSS for front-end developers and XML for Android. That article also introduced the idea of grouping outputs into folders to make them easier to locate and use.

In Part 4, we discussed how to manipulate token key-value pairs on output to meet specific needs. This included creating custom outputs where necessary and organising them for clarity and usability.

Now, in Part 5, we’ll build on these concepts by focusing on strategies for organising token outputs in greater detail, including how to create file structures that align with your token file structure.

By effectively structuring your token outputs, you enhance usability for your team and future-proof your design system for growth. Let’s dive in!

Why Organise Outputs into Folders and Files?

Organising design token outputs into structured folders and files isn’t just a matter of preference—it’s a best practice that supports scalability, usability, and maintainability. Whether you’re managing a small or large system, a clear organisation strategy ensures that your design tokens remain manageable as the system evolves.

Benefits of Organising Outputs

1. Easier Maintenance A well-organised structure makes it simpler to locate and update specific tokens.
2. Separation of Concerns By splitting tokens into logical groups—such as colours, typography, spacing, and shadows—you ensure that each file focuses on a specific aspect of the design system.
3. Clarity for Teams The separation of design token outputs into logical groups (e.g., colours, typography, spacing) naturally enhances clarity for teams.

Challenges of a Monolithic Tokens File

Starting with a single tokens file (e.g., styles.tokens) may work for small systems, but it becomes problematic as the system scales:

• Difficulty in Navigation: Large files are harder to read and search, especially for new contributors.
• Unintended Changes: Centralising all tokens increases the risk of accidental updates affecting unrelated parts of the system.
• Reduced Flexibility: A single file limits the ability to generate tailored outputs for specific contexts, such as themes or platforms.

Organising tokens into smaller files and structuring outputs into folders solves these issues, enabling a scalable and efficient design system.

Implementing Organised Token Outputs with Style Dictionary

Now that we’ve covered the importance of organising token outputs, let’s look at how to implement these practices using Style Dictionary. With the configuration below, we can:

• Dynamically generate token outputs for specific platforms and formats.
• Align the output file structure with the input token structure.
• Use filters and transforms to tailor outputs for your design system’s needs.

Generating SCSS Files from Tokens

We’ll process .tokens files located in src/tokens/ to create corresponding .scss files in build/scss/. Each .tokens file generates its own .scss file, keeping outputs modular and easy to navigate.

You can find the complete code for this example in the GitHub repository, on the scss-output-example branch.

Example .tokens files

Below are some sample .tokens files that demonstrate how we are defining Design Tokens in the W3C .tokens formt

color.tokens

{
  "color": {
    "primary": {
      "$value": "#0052cc",
      "$type": "color"
    },
    "secondary": {
      "$value": "#ff4081",
      "$type": "color"
    },
    "background": {
      "$value": "#ffffff",
      "$type": "color"
    },
    "text": {
      "$value": "#333333",
      "$type": "color"
    }
  }
}

spacing.tokens

{
  "spacing": {
    "xs": {
      "$value": "4px",
      "$type": "dimension"
    },
    "sm": {
      "$value": "8px",
      "$type": "dimension"
    },
    "md": {
      "$value": "16px",
      "$type": "dimension"
    },
    "lg": {
      "$value": "32px",
      "$type": "dimension"
    },
    "xl": {
      "$value": "64px",
      "$type": "dimension"
    }
  }
}

Style Dictionary Config File

Here is the JavaScript for the configuration needed:

import fs from 'fs';
import StyleDictionary from 'style-dictionary';
// Read all .tokens files from the 'src/tokens' directory
const tokenFiles = fs.readdirSync('src/tokens').filter((file) => file.endsWith('.tokens'));
// Configure Style Dictionary
const myStyleDictionary = new StyleDictionary({
  source: tokenFiles.map((file) => `src/tokens/${file}`),
  platforms: {
    scss: {
      transformGroup: 'scss',
      buildPath: 'build/scss/',
      files: tokenFiles.map((file) => ({
        // Replace '.tokens' with '.scss' for the destination
        destination: `${file.replace('.tokens', '.scss')}`, 
        format: 'scss/variables',
        // Match tokens by filename
        filter: (token) => file === token.filePath.split('/').pop(), 
      })),
    },
  },
  hooks: {
    transformGroups: {
      scss: ['size/pxToRem'],
    },
  },
});
// Build all platforms
myStyleDictionary.buildAllPlatforms();
console.log('Build completed!');

Key Features of the Configuration

1. Dynamic File Handling Reads all .tokens files from src/tokens, ensuring flexibility as new tokens are added.
2. Tailored Output Structure Each .tokens file generates a corresponding .scss file.
3. Custom Filters and Transforms Filters match tokens to their output files, and transforms (e.g., pxToRem) adapt token values for specific use cases.
4. Scalable and Maintainable Aligning the output file structure with the input token structure simplifies navigation and future updates.

Example Outputs

The configuration generates SCSS files like these in the build/scss/ directory:

color.scss

// Do not edit directly, this file was auto-generated.
$color-primary: #0052cc;
$color-secondary: #ff4081;
$color-background: #ffffff;
$color-text: #333333;

spacing.scss

// Do not edit directly, this file was auto-generated.
$spacing-xs: 0.25rem;
$spacing-sm: 0.5rem;
$spacing-md: 1rem;
$spacing-lg: 2rem;
$spacing-xl: 4rem;

Organising design token outputs into folders and files is more than a best practice—it’s a cornerstone of an efficient, scalable design system. By following the workflow outlined here and leveraging tools like Style Dictionary, you can:

• Simplify token management across teams.
• Ensure outputs are tailored to platform-specific needs.
• Future-proof your design system for growth and collaboration.

This approach enhances clarity and usability for your team, laying the foundation for a design system that evolves seamlessly with your organisation’s needs.

• #Designsystems
• #Designtokens
• #Styledictionary