A Design Tokens Workflow (part 10)

Creating Multiple Themes with Style Dictionary

2nd of April 2025

On This Page:

In this series on design tokens and Style Dictionary, we have recently looked at power of multi-brand theming. Now, let's delve into creating multiple themes for a single brand.

Imagine having a personal website or brand that shines differently with each season, featuring special editions, or festive themes. The ability to seamlessly switch between these adds a layer of personalisation and fun engagement that can resonate with your readers.

Setting Up Token Layers for Themes

Like in the last article, we will create distinct design tokens for each theme in the base layer and a single set of tokens in the semantic layer that reference the base layer.

Theme-Specific Base Tokens

For each theme, we define respective colour, typography, and spacing tokens to create visually distinct presentations. I’ll only provide the colour tokens in the article as a demonstration. You can can find all of the code in the github repo.

tokens/base/theme1/colors.tokens

json

{
  "color": {
    "base": {
      "primary": {
        "$value": "#0D6EFD",
        "$type": "color"
      },
      "secondary": {
        "$value": "#6C757D",
        "$type": "color"
      },
      "background": {
        "$value": "#FFFFFF",
        "$type": "color"
      },
      "text": {
        "$value": "#212529",
        "$type": "color"
      },
      "accent": {
        "$value": "#FFC107",
        "$type": "color"
      }
    }
  }
}

tokens/base/theme2/colors.tokens

json

{
  "color": {
    "base": {
      "primary": {
        "$value": "#212529",
        "$type": "color"
      },
      "secondary": {
        "$value": "#343A40",
        "$type": "color"
      },
      "background": {
        "$value": "#121212",
        "$type": "color"
      },
      "text": {
        "$value": "#E9ECEF",
        "$type": "color"
      },
      "accent": {
        "$value": "#17A2B8",
        "$type": "color"
      }
    }
  }
}

tokens/base/theme3/colors.tokens

json

{
  "color": {
    "base": {
      "primary": {
        "$value": "#FFC107",
        "$type": "color"
      },
      "secondary": {
        "$value": "#F44336",
        "$type": "color"
      },
      "background": {
        "$value": "#FFF4E0",
        "$type": "color"
      },
      "text": {
        "$value": "#333333",
        "$type": "color"
      },
      "accent": {
        "$value": "#4CAF50",
        "$type": "color"
      }
    }
  }
}

Shared Semantic Tokens

The semantic tokens maintain consistency across all themes by referencing the appropriate theme base tokens, again I’ll only show the design tokens for the colours in the semantic layer also.

tokens/semantic/colors.tokens

json

{
  "color": {
    "background": {
      "default": {
        "$value": "{color.base.background}",
        "$type": "color"
      }
    },
    "text": {
      "default": {
        "$value": "{color.base.text}",
        "$type": "color"
      }
    },
    "action": {
      "primary": {
        "$value": "{color.base.primary}",
        "$type": "color"
      },
      "secondary": {
        "$value": "{color.base.secondary}",
        "$type": "color"
      },
      "highlight": {
        "$value": "{color.base.accent}",
        "$type": "color"
      }
    }
  }
}

Configuring Style Dictionary

This file organises how the tokens are processed and how the resulting CSS files are generated. Let's explore the setup:

javascript

import { globSync } from 'glob';
import StyleDictionary from 'style-dictionary';
// The themes we want to generate
const themes = ['theme1', 'theme2', 'theme3'];
// The output formats we want to generate
const formats = ['css'];
// Function to get config for a specific theme and format (theme tokens)
function getStyleDictionaryConfig(theme, format) {
  const platformConfig = {};
  // Add theme CSS files
  platformConfig[`${format}_theme`] = {
    transformGroup: format,
    buildPath: `build/${format}/themes/`,
    files: [
      {
        destination: `${theme}.${format}`,
        format: `${format}/theme-wrapper`,
        filter: (token) => token.filePath.includes(`src/tokens/base/${theme}/`),
        options: {
          themeName: theme
        }
      }
    ]
  };
  return {
    source: [
      `src/tokens/base/${theme}/**/*.tokens`,
      'src/tokens/semantic/**/*.tokens'
    ],
    platforms: platformConfig
  };
}
// Only generate semantic once, not per theme
function getSemanticConfig(format) {
  return {
    source: [
      'src/tokens/base/theme1/**/*.tokens', // Need the base tokens for reference
      'src/tokens/semantic/**/*.tokens'
    ],
    platforms: {
      [`${format}_semantic`]: {
        transformGroup: format,
        buildPath: `build/${format}/semantic/`,
        files: [
          {
            destination: `tokens.${format}`,
            format: `${format}/variables-semantic`,
            filter: (token) => token.filePath.includes('src/tokens/semantic/'),
            options: {
              outputReferences: true
            }
          }
        ]
      }
    }
  };
}
// Helper function to safely get token value
function getTokenValue(token) {
  if (token && token.original && token.original.$value) {
    return token.original.$value;
  }
  if (token && token.value) {
    return token.value;
  }
  return token.value;
}
// Register custom format for CSS theme wrapper with class selector
StyleDictionary.hooks.formats['css/theme-wrapper'] = function({ dictionary, options }) {
  const themeName = options.themeName || 'default';
  
  const tokens = dictionary.allTokens.filter(token => 
    token.filePath.includes(`src/tokens/base/${themeName}/`)
  );
  console.log(`Theme ${themeName} has ${tokens.length} tokens for theme wrapper`);
  
  const variables = tokens.map((token) => {
    const name = token.path.join('-');
    const value = getTokenValue(token);
    
    return `  --${name}: ${value};`;
  }).join('\n');
  return `.${themeName} {\n${variables}\n}`;
};
// Register custom format for CSS semantic variables with ds- prefix
StyleDictionary.hooks.formats['css/variables-semantic'] = function({ dictionary, options }) {
  const semanticTokens = dictionary.allTokens.filter(token => 
    token.filePath.includes('src/tokens/semantic/')
  );
  const variables = semanticTokens.map((token) => {
    const name = token.path.join('-');
    const description = token.original.$description || '';
    
    const referenceValue = getTokenValue(token);
    if (typeof referenceValue === 'string' && referenceValue.startsWith('{')) {
      const refPath = referenceValue.replace(/^\{|\}$/g, '');
      const cssVarName = `var(--${refPath.replace(/\./g, '-')})`;
      
      return `  --ds-${name}: ${cssVarName};${description ? ` /* ${description} */` : ''}`;
    } else {
      return `  --ds-${name}: ${referenceValue};${description ? ` /* ${description} */` : ''}`;
    }
  }).join('\n');
  return `:root {\n${variables}\n}`;
};
// Loop through each theme and format and build theme tokens
themes.forEach(theme => {
  formats.forEach(format => {
    console.log(`Building ${format} tokens for ${theme}...`);
    const sd = new StyleDictionary(getStyleDictionaryConfig(theme, format));
    
    // For each platform in the config
    Object.keys(sd.config.platforms).forEach(platform => {
      sd.buildPlatform(platform);
    });
  });
});
// Build semantic tokens once for each format
formats.forEach(format => {
  console.log(`Building ${format} semantic tokens...`);
  const sd = new StyleDictionary(getSemanticConfig(format));
  
  // For each platform in the config
  Object.keys(sd.config.platforms).forEach(platform => {
    sd.buildPlatform(platform);
  });
});
console.log('Build completed!');

Key Components of this configuration

Creating the Style Dictionary Instance

This configuration manages both theme-specific styles and a unified semantic layer. For each theme, a distinct set of base tokens is compiled. This setup allows themes to be visually unique while maintaining global consistency through central semantic tokens.

Highlights:

Theme-Specific Configurations: Each theme (e.g., ⁠theme1, ⁠theme2, ⁠theme3) is processed to generate a ⁠.css file wrapped in class selectors (e.g., ⁠.theme1 { ... }).
Single Semantic Output: Generates a single semantic token file, ensuring consistent semantic definitions across themes.

Custom Format Registration

The configuration includes custom formats such as ⁠css/theme-wrapper for creating class-based CSS files and ⁠css/variables-semantic for generating semantically consistent variables with a ⁠ds- prefix.

Highlights:

Theme Wrappers: Theme-specific files are wrapped in class selectors, allowing easy theme switching via class manipulation.
Consistent Semantics: Shared semantic tokens are marked with a ⁠ds- prefix, maintaining a clear separation between base and semantic layers.

Building All Platforms

The script loops through each theme and format, compiling the necessary CSS outputs. Maintaining structured processes ensures efficient builds and organised outputs, ready for immediate integration into modern web projects

Example Outputs

The Style Dictionary script creates theme-specific CSS files and a set of semantic CSS tokens that ensure stylistic consistency across themes. Here’s an example at what these outputs look like:

Generated Base Layer CSS

The theme-specific CSS classes are wrapped in class selectors, allowing easy switching between themes on your website by altering the class of an element (like the body or html itself):

css

.theme1 {
  --color-base-primary: #0D6EFD;
  --color-base-secondary: #6C757D;
  --color-base-background: #FFFFFF;
  --color-base-text: #212529;
  --color-base-accent: #FFC107;
  --spacing-base-xs: 4px;
  --spacing-base-sm: 8px;
  --spacing-base-md: 16px;
  --spacing-base-lg: 24px;
  --spacing-base-xl: 32px;
  --font-family-primary: 'Roboto', sans-serif;
  --font-family-secondary: 'Open Sans', sans-serif;
  --font-weight-regular: 400;
  --font-weight-bold: 700;
  --font-size-small: 14px;
  --font-size-medium: 16px;
  --font-size-large: 24px;
}

Generated Semantic Layer CSS

This output establishes the shared semantics with a ds- prefix, simplifying theme maintenance. The :root here acts as a global baseline for semantic values:

css

:root {
  --ds-color-background-default: var(--color-base-background);
  --ds-color-text-default: var(--color-base-text);
  --ds-color-action-primary: var(--color-base-primary);
  --ds-color-action-secondary: var(--color-base-secondary);
  --ds-color-action-highlight: var(--color-base-accent);
  --ds-spacing-element-xsmall: var(--spacing-base-xs);
  --ds-spacing-element-small: var(--spacing-base-sm);
  --ds-spacing-element-medium: var(--spacing-base-md);
  --ds-spacing-element-large: var(--spacing-base-lg);
  --ds-spacing-element-xlarge: var(--spacing-base-xl);
  --ds-spacing-layout-small: var(--spacing-base-md);
  --ds-spacing-layout-medium: var(--spacing-base-lg);
  --ds-spacing-layout-large: var(--spacing-base-xl);
  --ds-typography-heading-fontFamily: var(--font-family-primary);
  --ds-typography-heading-fontWeight: var(--font-weight-bold);
  --ds-typography-heading-fontSize: var(--font-size-large);
  --ds-typography-body-fontFamily: var(--font-family-secondary);
  --ds-typography-body-fontWeight: var(--font-weight-regular);
  --ds-typography-body-fontSize: var(--font-size-medium);
  --ds-typography-caption-fontFamily: var(--font-family-secondary);
  --ds-typography-caption-fontWeight: var(--font-weight-regular);
  --ds-typography-caption-fontSize: var(--font-size-small);
}

By employing this approach, Style Dictionary can facilitate a unified and cohesive theming experience. Your themes can uniquely shine while maintaining a consistent design language across your website. With the thematic CSS structure in place, you can integrate a theme switcher using JavaScript allowing your visitors to choose how they want to have your site look.

In the previous article we addressed multi-brand theming and with a few small changes this configuration has focused on tailoring multiple themes within a single brand or personal website. This approach allows you to adapt your design system to evolving needs while ensuring visual harmony.

Embracing these strategies provides flexible theming options to meet various needs, whether for personal projects or larger brand applications. These methods help reinforce the strength of your design system.