How to manage UI kit components and theme variants from the CLI

Docs/Tutorials/ui_kit_generator

Free Reference for ui_kit_generator: every variable, option and package it generates. Command: archipelago generate ui_kit_generator

Add the ui-kit and theme-variant commands, list, add and remove catalogue components, and export UI kit tokens as a Tailwind preset.

What you'll learn

• Adding the ui-kit and theme-variant commands to your monorepo toolkit
• Listing, adding and removing catalogue components
• Exporting your UI kit tokens as a Tailwind preset
• Knowing which commands write only stubs

Prerequisites

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

Step 1: Generate the UI Kit Generator

The brick is free. New projects already include it. On an older project, run:

archipelago generate ui_kit_generator

The prompts are:

• appName: your app name
• isForMonorepo: leave this as true

Or use a config file:

{
  "appName": "MyApp",
  "isForMonorepo": true
}

archipelago generate ui_kit_generator --config uikit_gen_config.json

Step 2: Understand the Generated Structure

devtools/scripts/ui_kit_generator/
└── lib/src/
    ├── commands/        # ui-kit (list, add, remove, status, create, export-tailwind), theme-variant
    ├── tailwind/        # Token reader and preset renderers
    ├── models/          # ui_kit_components.json reader and writer
    └── registry/        # Built-in component catalogue

The hook adds the package to the toolkit and registers UiKitCommand and ThemeVariantCommand in command_runner.dart.

Step 3: Track Components

The commands default to --ui-kit-path packages/<app>_ui_kit. They read the package name from archipelago.yaml.

dart run monorepo_toolkit ui-kit list
dart run monorepo_toolkit ui-kit list --layer atom
dart run monorepo_toolkit ui-kit add button
dart run monorepo_toolkit ui-kit remove button
dart run monorepo_toolkit ui-kit status

add installs the component and its declared dependencies into ui_kit_components.json. status shows installed built-in and custom components against the full catalogue.

Step 4: Create a Custom Component Stub

dart run monorepo_toolkit ui-kit create --name my-widget --layer atom

This writes a StatelessWidget stub with a TODO comment and registers it as a custom component. It is a placeholder. You write the widget. For a full component with tests and a showcase, use ui_kit_component.

Step 5: Generate Theme Variant Stubs

Write a YAML file:

variants:
  - name: ocean
  - name: sunset

dart run monorepo_toolkit theme-variant --config variants.yaml --prefix App

The command writes one class per entry under lib/src/theme/variants/. Each class has light and dark methods with TODO stubs. You add the color overrides. For real variants with overrides, use ui_kit_theme.

Step 6: Export a Tailwind Preset

The export reads your real UI kit foundations. It runs in plain Dart, so it works in CI with no Flutter and no login.

dart run monorepo_toolkit ui-kit export-tailwind \
  --output build/theme/tailwind-theme.css \
  --v3-config tailwind.theme.cjs

The output is a Tailwind v4 @theme block with colors, type sizes, spacing, radius and shadows. Dark values override the same variables when <html data-theme="dark"> is set, or by system preference. --v3-config also writes a Tailwind v3 module. The output has no timestamp, so you can commit it and review diffs. An unresolved token stops the command and names it.

Mini-apps can load the file to follow the host theme. See the mini-app bridge guide.

Common Customizations

Customization	Where to Change
Component catalogue	lib/src/registry/component_registry.dart
Tailwind variable names	lib/src/tailwind/tailwind_preset.dart
UI kit location	The --ui-kit-path flag

Next Steps

• Create a UI component to understand the generated output
• Add theme variants with real overrides