Creating a UI Kit Theme Variant

What you'll learn

• Generating a new theme variant (e.g., high contrast, sepia, corporate)
• Extending from an existing base theme (light or dark)
• Configuring color, shadow, and typography overrides
• Switching themes at runtime

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• UI Kit already generated (see UI Kit Setup)

Step 1: Generate a Theme Variant

archipelago generate ui_kit_theme

You will be prompted for:

• themeName — e.g., high_contrast, sepia, corporate
• prefix — e.g., App, My (your UI Kit prefix)
• appName — MyApp
• baseTheme — light or dark (which theme to extend)
• hasColorOverrides — true to generate color override placeholders
• hasShadowOverrides — true for shadow overrides
• hasTypographyOverrides — true for typography overrides

Or use a config file:

{
  "themeName": "high_contrast",
  "prefix": "App",
  "appName": "MyApp",
  "baseTheme": "light",
  "hasColorOverrides": true,
  "hasShadowOverrides": false,
  "hasTypographyOverrides": true
}

Step 2: Understand the Generated Structure

ui_kit/
└── lib/src/
    └── themes/
        ├── light/                         # Existing base theme
        ├── dark/                          # Existing base theme
        └── high_contrast/                 # New variant
            ├── high_contrast_theme.dart   # Theme data
            ├── high_contrast_colors.dart  # Color overrides
            └── high_contrast_typography.dart # Typography overrides

Step 3: Customize Colors

Edit the generated color overrides to match your variant's design:

// high_contrast_colors.dart
class HighContrastColors extends AppColors {
  @override
  Color get primary => const Color(0xFF000000);

  @override
  Color get onPrimary => const Color(0xFFFFFFFF);

  @override
  Color get background => const Color(0xFFFFFFFF);

  @override
  Color get onBackground => const Color(0xFF000000);

  // High contrast: stronger borders and outlines
  @override
  Color get outline => const Color(0xFF000000);
}

Step 4: Customize Typography (if enabled)

// high_contrast_typography.dart
class HighContrastTypography extends AppTypography {
  @override
  TextStyle get bodyLarge => super.bodyLarge.copyWith(
    fontWeight: FontWeight.w600,  // Bolder text for readability
    letterSpacing: 0.5,
  );
}

Step 5: Register and Switch Themes

The theme variant is automatically registered. Switch at runtime:

// Access available themes
final themes = AppThemeRegistry.availableThemes;
// ['light', 'dark', 'high_contrast']

// Switch theme
AppThemeRegistry.setTheme('high_contrast');

Common Customizations

Customization	Where to Change
Override specific colors	*_colors.dart — override individual getters
Override shadows	Enable hasShadowOverrides, edit *_shadows.dart
Override typography	Enable hasTypographyOverrides, edit *_typography.dart
Add component-specific styles	Extend component style resolvers
Set default theme	AppThemeRegistry initialization

Next Steps

• Create a UI component that uses your theme
• Use the UI Kit Generator to manage themes via CLI