Design Tokens Generator

A powerful Flutter package for generating design tokens from design system files. This package converts design tokens (colors, typography, spacing) into Flutter-ready Dart code with advanced theme support and automatic seed color detection.

πŸš€ Features

  • ✨ Smart Color Generation: Automatically generates Flutter colors from JSON design tokens
  • 🎨 Intelligent Seed Color Detection: Automatically finds the best brand colors for Material 3 themes
  • 🎭 Multi-Theme Support: Supports Individual, Corporate, and Can themes with automatic theme detection
  • πŸ“± Material Design 3 Compatible: Generates themes compatible with Flutter's Material 3
  • πŸ”„ Token Resolution: Handles complex token references and nested structures
  • πŸ“ Typography Generation: Converts design typography tokens to Flutter TextStyles
  • πŸ“ Spacing Generation: Creates spacing constants from design tokens
  • πŸ› οΈ CLI & Programmatic API: Use via command line or integrate into your build process
  • 🎯 Brand-Aware: Prioritizes brand colors (primary, blue, green, purple) for theme generation

πŸ”§ Installation

Add this package to your pubspec.yaml:

dependencies:
  design_tokens_generator:
    path: ../design_tokens_generator

Or install from a git repository:

dependencies:
  design_tokens_generator:
    git:
      url: https://github.com/your-org/design_tokens_generator.git

πŸ“– Usage

Command Line Usage

Run the generator from your project root:

# Basic usage
dart run design_tokens_generator:generate_tokens --assets assets/design_tokens --output lib/app/core/design_system/generated

# Using the compiled binary (faster)
./bin/generate_tokens_compiled --assets assets/design_tokens --output lib/app/core/design_system/generated

Programmatic Usage

import 'package:design_tokens_generator/design_tokens_generator.dart';

void main() async {
  final generator = DesignTokenGenerator(
    assetsPath: 'assets/design_tokens',
    outputPath: 'lib/app/core/design_system/generated',
  );
  
  await generator.generate();
  print('βœ… Design tokens generated successfully!');
}

πŸ“‚ Generated Files

The package generates the following files in your output directory:

app_colors.dart

Contains all color constants organized by theme:

class AppColors {
  // Value Colors (base colors)
  static const Color value_value_colors_brand_600 = Color(0xFF1570ef);
  static const Color value_value_colors_brand_500 = Color(0xFF2e90fa);
  
  // Individual Theme Colors
  static const Color individual_individual_color_primary = Color(0xFF1570ef);
  
  // Corporate Theme Colors  
  static const Color corporate_corporate_color_primary = Color(0xFF2e90fa);
  
  // Can Theme Colors
  static const Color can_can_color_primary = Color(0xFF6938ef);
}

app_theme.dart

Complete Flutter themes with automatic seed color selection:

class AppTheme {
  static ThemeData get lightTheme {
    return ThemeData(
      useMaterial3: true,
      colorScheme: ColorScheme.fromSeed(
        seedColor: AppColors.value_value_colors_brand_600, // Auto-selected
        brightness: Brightness.light,
      ),
      // ... complete theme configuration
    );
  }
  
  static ThemeData get darkTheme {
    return ThemeData(
      useMaterial3: true,
      colorScheme: ColorScheme.fromSeed(
        seedColor: AppColors.value_value_colors_brand_700, // Auto-selected
        brightness: Brightness.dark,
      ),
      // ... complete theme configuration
    );
  }
}

app_typography.dart

Typography styles from design tokens:

class AppTypography {
  static const TextStyle displayLarge = TextStyle(
    fontSize: 32,
    fontWeight: FontWeight.w800,
    height: 1.25,
  );
  // ... more typography styles
}

app_spacing.dart

Spacing constants:

class AppSpacing {
  static const double xs = 4.0;
  static const double sm = 8.0;
  static const double md = 16.0;
  static const double lg = 24.0;
  // ... more spacing values
}

πŸ—οΈ Design Token Structure

Your design tokens should be organized as JSON files in the assets directory:

assets/design_tokens/
β”œβ”€β”€ $metadata.json          # Token metadata
β”œβ”€β”€ $themes.json            # Theme definitions
β”œβ”€β”€ Color/                  # Color tokens
β”‚   β”œβ”€β”€ base.json
β”‚   β”œβ”€β”€ individual.json
β”‚   β”œβ”€β”€ corporate.json
β”‚   └── can.json
β”œβ”€β”€ Typography/             # Typography tokens
β”œβ”€β”€ Spacing/               # Spacing tokens
β”œβ”€β”€ Primitives/            # Primitive tokens
β”œβ”€β”€ Containers/            # Container tokens
└── Radius/               # Border radius tokens

🎨 Smart Seed Color Detection

The generator automatically selects the best seed colors for Material 3 themes using intelligent prioritization:

Priority Order:

  1. Brand colors - brand, primary
  2. Blue variants - blue, bluelight, bluedark
  3. Other colors - green, purple, indigo, teal, cyan

Tone Selection:

  • Light theme: Prefers 500-600 tones
  • Dark theme: Prefers 700-800 tones

Example Output:

🎯 Searching for seed colors...
πŸ” Found 1300+ color tokens
🎯 Brand tokens found: 10
   Brand: value.value.colors.brand.600 -> #1570ef
🎯 Selected light token: value.value.colors.brand.600
🎯 Converted to: AppColors.value_value_colors_brand_600

πŸ”„ Token Resolution

The generator handles complex token references:

{
  "color": {
    "primary": {
      "value": "{color.brand.600}"
    },
    "brand": {
      "600": {
        "value": "#1570ef"
      }
    }
  }
}

Results in resolved tokens ready for Flutter:

static const Color color_primary = Color(0xFF1570ef);
static const Color color_brand_600 = Color(0xFF1570ef);

🎭 Multi-Theme Support

The generator automatically detects and organizes themes:

  • Individual Theme: Personal/consumer interface colors
  • Corporate Theme: Business/enterprise interface colors
  • Can Theme: Custom brand theme colors
  • Value Colors: Base color palette shared across themes

πŸ“± Integration Example

import 'package:flutter/material.dart';
import 'app/core/design_system/generated/app_theme.dart';
import 'app/core/design_system/generated/app_colors.dart';

void main() {
  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Design System Demo',
      theme: AppTheme.lightTheme,
      darkTheme: AppTheme.darkTheme,
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      backgroundColor: AppColors.individual_individual_color_background_primary,
      body: Center(
        child: Text(
          'Hello Design System!',
          style: Theme.of(context).textTheme.displayLarge?.copyWith(
            color: AppColors.individual_individual_color_text_primary,
          ),
        ),
      ),
    );
  }
}

πŸ› οΈ Development & Build

Build the CLI tool:

dart compile exe bin/generate_tokens.dart -o bin/generate_tokens_compiled

Run tests:

dart test

Analyze code:

dart analyze

πŸ” Troubleshooting

Common Issues:

Colors not generating:

  • Check that your JSON files contain valid color values (hex format)
  • Ensure color tokens are in the correct directory structure

Theme not applying:

  • Verify that AppTheme is imported correctly
  • Check that Material 3 is enabled: useMaterial3: true

Seed colors not found:

  • Ensure you have brand or primary colors in your tokens
  • Check that color tokens follow the expected naming convention

πŸ“Š Performance

  • Token Processing: ~1000+ tokens processed per second
  • File Generation: Generates 4 files in under 2 seconds
  • Memory Usage: Minimal memory footprint
  • Build Integration: Fast enough for watch mode builds

🀝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

πŸ™ Acknowledgments

  • Flutter team for the excellent Material 3 implementation
  • Design Token Community Group for the design tokens specification
  • All contributors who helped improve this package

Libraries

design_tokens_generator