How to add a theme variant to a Flutter UI kit

Docs/Tutorials/ui_kit_theme

Enterprise Reference for ui_kit_theme: every variable, option and package it generates. Command: archipelago generate ui_kit_theme

Generate a theme variant that extends light or dark, choose which extensions to override, import a Theme Builder export, and use the generated factory.

What you'll learn

• Generating a theme variant that extends the light or dark theme
• Choosing which extensions to override
• Importing a Theme Builder export
• Using the generated factory

Prerequisites

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

The brick patches part directives into the existing theme files of the UI kit. Run it from the project root.

Step 1: Generate a Theme Variant

archipelago generate ui_kit_theme

The prompts are:

• themeName: for example high_contrast, sepia or corporate
• prefix: your UI kit prefix. It defaults to project.prefix in archipelago.yaml.
• appName: the default is project.name in archipelago.yaml
• baseTheme: light or dark
• hasColorOverrides: true by default
• hasShadowOverrides: false by default
• hasTypographyOverrides: false by default

Or use a config file:

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

archipelago generate ui_kit_theme --config high_contrast.json

baseTheme accepts only light or dark. You cannot extend an earlier variant.

Step 2: Understand the Generated Structure

The files land in the foundations folder of the UI kit:

packages/my_app_ui_kit/lib/src/foundations/themes/
├── app_theme_high_contrast.dart                        # Theme definition
└── extensions/
    ├── app_color_extension_high_contrast.dart          # If hasColorOverrides
    ├── app_shadow_extension_high_contrast.dart         # If hasShadowOverrides
    └── app_typography_extension_high_contrast.dart     # If hasTypographyOverrides

Each file is a part of 'app_theme.dart'. The hook adds the matching part lines to the existing theme and extension files. You edit no wiring.

Step 3: Edit the Overrides

Open the generated extension files. Change only the tokens that differ from the base. For colors, edit the action, background, foreground and outline groups in the color extension file. For typography, change the text styles in the typography extension file.

Step 4: Use the Factory

The brick generates a factory named after the theme:

final theme = AppThemeHighContrastFactory.highContrast();

The result is a ThemeData. It copies the base theme and swaps in the variant's extensions. Components read tokens through context.colors, context.typography and the other extensions, so they follow the variant.

Step 5: Switch Themes in Your App

The brick registers no switcher. Pass the factory result to MaterialApp yourself:

MaterialApp.router(
  theme: AppTheme.light(),
  darkTheme: AppTheme.dark(),
  // or: theme: AppThemeHighContrastFactory.highContrast(),
  routerConfig: router.config(),
);

For a runtime switcher, hold the selected ThemeData in your own state and rebuild MaterialApp.

Import a Theme Builder Export

Run the brick from the UI kit package with the exported JSON as the config:

cd packages/my_app_ui_kit
archipelago generate ui_kit_theme --config my_brand.json

The brick detects the export. It writes semantic colors into the color extension and shadow levels into the shadow extension. It writes the type scale and font family into the typography extension, and spacing and radius into the theme file. Font weights are not written. A non-default font is written by family name, so the kit must provide that font. An unknown color reference stops generation and names it. See the Theme Builder guide.

Common Customizations

Customization	Where to Change
Colors	The color extension file
Shadows	The shadow extension file. Needs hasShadowOverrides
Typography	The typography extension file. Needs hasTypographyOverrides
Which theme is active	Your MaterialApp setup

Next Steps

• Create a UI component that uses your theme
• Use the UI Kit Generator to export tokens as a Tailwind preset