ui_kit_theme Enterprise

Docs/Bricks/ui_kit_theme

Tier

Enterpriseversion 2.1.7

Command

archipelago generate ui_kit_theme

Generates

one theme file plus its color, shadow and typography extensions for a UI kit

Tutorial

Step-by-step: add ui_kit_theme to a project

Generates a new theme variant for an existing UI Kit (from flutter_ui_kit) — e.g. high_contrast, sepia, corporate — extending an existing light/dark theme with optional color/shadow/typography overrides. Requires flutter_ui_kit already generated: it patches part directives into that package's existing theme files.

Variables

Variable	Type	Default	Description
themeName	string	—	The name of the new theme variant (e.g., high_contrast, sepia)
prefix	string	project.prefix from archipelago.yaml	The prefix for the UI Kit (e.g., App, My)
appName	string	project.name from archipelago.yaml	The app name for package imports
baseTheme	enum (light, dark)	light	Which existing theme to extend from
hasColorOverrides	boolean	true	Whether to generate color override placeholders
hasShadowOverrides	boolean	false	Whether to generate shadow override placeholders
hasTypographyOverrides	boolean	false	Whether to generate typography override placeholders

Install

Interactive

archipelago generate ui_kit_theme

Non-interactive (CI)

archipelago generate ui_kit_theme --config my_config.json

Config Template

{
  "@themeName": "The name of the new theme variant (e.g., high_contrast, sepia)",
  "themeName": "high_contrast",
  "@prefix": "The prefix for the UI Kit (e.g., App, My)",
  "prefix": "App",
  "@appName": "The app name for package imports",
  "appName": "MyApp",
  "@baseTheme": "Which existing theme to extend from (light | dark)",
  "baseTheme": "light",
  "@hasColorOverrides": "Whether to generate color override placeholders",
  "hasColorOverrides": true,
  "@hasShadowOverrides": "Whether to generate shadow override placeholders",
  "hasShadowOverrides": false,
  "@hasTypographyOverrides": "Whether to generate typography override placeholders",
  "hasTypographyOverrides": false
}

From a Theme Builder export

Pass the JSON the Theme Builder exports as the config, from the UI kit package:

cd packages/<app>_ui_kit
archipelago generate ui_kit_theme --config my_brand.json

pre_gen detects the export (its colors and semantic maps) and writes the values into the variant: semantic colors into the color extension, shadow levels into the shadow extension, the type scale and font family into the typography extension, and spacing and radius into the theme file. The shadow and typography files are always generated for an export. prefix and appName come from archipelago.yaml. An unknown color reference (for example brand.500 with no brand palette) stops generation with its name.

Generated Structure

lib/src/foundations/themes/
├── {prefix}_theme_{theme_name}.dart                    # Theme definition extending base
└── extensions/
    ├── {prefix}_color_extension_{theme_name}.dart      # Color overrides (if hasColorOverrides)
    ├── {prefix}_shadow_extension_{theme_name}.dart     # Shadow overrides (if hasShadowOverrides)
    └── {prefix}_typography_extension_{theme_name}.dart  # Typography overrides (if hasTypographyOverrides)

Each generated file is a part of '{prefix}_theme.dart' — post_gen automatically inserts the matching part '...' directive into the existing theme file (and extension aggregator files) via PartDirectiveUpdater; no manual wiring needed.

Public API

// Generated factory extension — call the theme name as a static method:
final theme = AppThemeHighContrastFactory.highContrast();
// theme is a ThemeData that copies the base (light/dark) theme's ThemeData
// and swaps in the new variant's ColorExtension/ShadowExtension/TypographyExtension
// (plus SpacingExtension/RadiusExtension when generated from an export).

DI & Wiring

None — this brick only adds Dart source files under lib/src/foundations/themes/; it does not register anything in GetIt or touch bootstrap.dart. Selecting the new theme at runtime (e.g. wiring it into a theme switcher) is left to the app.

Dependencies

None beyond what flutter_ui_kit already requires — this brick adds no new pub.dev packages.

Platform Setup

None required.

Limitations

• Requires flutter_ui_kit already generated. themeName has no default. prefix/appName fall back to archipelago.yaml only through archipelago generate; raw mason make prompts for them first.
• From an export, font weights are not written (the kit has no weight slot), and a non-default font is written as its family name, so the kit must provide that font.
• baseTheme only accepts light or dark — you cannot extend a previously-generated custom variant.
• pre_gen's ThemeValidator had a real hook-compile bug until 2.1.1 (HookException, a class that doesn't exist in package:mason) — fixed by switching to a plain Exception. Anything below 2.1.1 fails generation outright regardless of input validity.

Changelog

Run archipelago brick info ui_kit_theme to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.