Building a Scalable Design System - Chapter 2: Theming with Semantic Tokens

In the previous chapter of this series, we established the foundation of a scalable design system by focusing on core principles, structuring design tokens, and leveraging tools like Token Studio and Style Dictionary for automation. Now, we take the next step in building a robust design system: Theming with Semantic Tokens.

Why Theming Matters in a Design System#

As digital products evolve, they often need to support multiple themes to accommodate branding, accessibility, and user preferences. Theming ensures:

Brand Consistency: Different brands or product lines can share a unified design system while retaining unique identities.
Dark Mode & Accessibility: Offering light/dark modes and high-contrast themes improves usability.
Platform Adaptability: Different environments (web, mobile, desktop) may require specific design adjustments.
Customizability: Allowing products to have distinct themes without affecting the core system architecture.

Using semantic tokens is the key to achieving a scalable and maintainable theming structure.

Understanding Semantic Tokens#

Semantic tokens act as an abstraction layer between raw design decisions (primitives) and component-specific styles. Instead of defining colors as #1A73E8, we use a semantic name like color-primary, which can then be redefined based on the active theme.

Token Structure Example:#

Global Tokens (Primitives)

{
  "color-blue-500": "#1A73E8",
  "color-gray-900": "#202124"
}

Semantic Tokens

{
  "color-primary": "{color-blue-500}",
  "color-background": "{color-gray-900}"
}

Theme-Specific Tokens

{
  "light": {
    "color-primary": "{color-blue-500}",
    "color-background": "{color-gray-900}"
  },
  "dark": {
    "color-primary": "{color-gray-900}",
    "color-background": "{color-blue-500}"
  }
}

Cross-Platform Theming with Style Dictionary#

Semantic tokens serve as a strong foundation for applying theming across various platforms. For instance, at Flaconi, we generate an entire theme class and Typography widget from the same token definitions used for web, ensuring consistency across our applications. By automating the generation of theme files from Figma tokens, teams can streamline the rebranding process and reduce engineering overhead when updating core styles.

Example of Generated ThemeWidget in Flutter#

To extend the theming system to Flutter, we can generate a ThemeWidget that dynamically applies the theme based on the provided tokens.

import 'package:flutter/material.dart';

class ThemeWidget extends InheritedWidget {
  static final ThemeData lightTheme = ThemeData(
    primaryColor: Color(0xFF1A73E8),
    backgroundColor: Color(0xFF202124),
  );

  static final ThemeData darkTheme = ThemeData(
    primaryColor: Color(0xFF202124),
    backgroundColor: Color(0xFF1A73E8),
  );
  final ThemeData themeData;

  const ThemeWidget({
    Key? key,
    required this.themeData,
    required Widget child,
  }) : super(key: key, child: child);

  static ThemeWidget of(BuildContext context) {
    return context.dependOnInheritedWidgetOfExactType<ThemeWidget>()!;
  }

  @override
  bool updateShouldNotify(ThemeWidget oldWidget) {
    return themeData != oldWidget.themeData;
  }
}

This widget allows different parts of the application to access the currently active theme and switch dynamically based on user preferences or system settings.

Example of Generated CSS Output#

The following CSS example serves as a strong foundation for applying theming across various platforms. For instance, at Flaconi, we generate an entire theme class and Typography widget from the same token definitions used for web, ensuring consistency across our applications.

:root {
  --color-primary: #1A73E8;
  --color-background: #202124;
}

[data-theme="dark"] {
  --color-primary: #202124;
  --color-background: #1A73E8;
}

Style Dictionary transforms token data into platform-specific formats, making it easy to integrate design tokens into CSS variables, SCSS maps, and mobile frameworks like iOS and Android.

Style Dictionary Configuration Example

Flutter Style Dictionary Configuration

{
  "source": ["tokens/themes.json"],
  "platforms": {
    "flutter": {
      "transformGroup": "flutter",
      "buildPath": "lib/theme/",
      "files": [{
        "destination": "theme.dart",
        "format": "flutter/class"
      }]
    }
  }
}

This configuration allows Style Dictionary to generate a structured Dart class, ensuring dynamic theming can be easily managed within Flutter applications.

{
  "source": ["tokens/themes.json"],
  "platforms": {
    "web": {
      "transformGroup": "css",
      "buildPath": "dist/web/",
      "files": [{
        "destination": "themes.css",
        "format": "css/variables"
      }]
    }
  }
}

Inject CSS variables for web-based theming.
Use platform-specific theme tokens for mobile and desktop apps.
Support real-time theme switching based on user preferences or system-wide settings for a more personalized experience.

Benefits of Using Semantic Tokens for Theming#

By implementing theming via semantic tokens, design systems become:

✅ More Scalable – Changes to themes do not require modifying raw component styles.

✅ More Maintainable – A single source of truth governs all themes, making updates easier.

✅ More Flexible – Different brands, accessibility modes, and platforms can be managed seamlessly.

✅ More Developer-Friendly – Frontend engineers can consume well-structured theme files with minimal effort.

Conclusion#

Semantic tokens unlock the full potential of a scalable theming strategy. By leveraging Token Studio and Style Dictionary, teams can generate, manage, and implement themes efficiently across platforms, ensuring consistency and adaptability across different environments.

In the next chapter, we will walk through component libraries owned by the design system, how to contribute to them, and how to establish proper governance to ensure scalability while aligning with the design system’s objectives and mission. Stay tuned!