Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

UI, Assets & L10N

ui_kit_generator Free ​

Tier
Freeversion 1.1.7
Command
archipelago generate ui_kit_generator
Generates
  • devtools/scripts/ui_kit_generator
Depends on
monorepo_toolkitgenerate these first

UI Kit component and theme-variant management. Adds the ui-kit and theme-variant commands to the base monorepo_toolkit — track which design-system components are installed, scaffold new custom components, and generate light/dark theme variant files from a YAML config.

Requires the base monorepo_toolkit brick to already be generated.

Variables ​

VariableTypeDefaultDescription
appNamestringMyAppThe name of your application
isForMonorepobooleantrueWhether this is being generated as part of a monorepo

Usage ​

Interactive ​

bash
archipelago generate ui_kit_generator

Non-interactive (CI) ​

bash
archipelago generate ui_kit_generator --config my_config.json

Generated Structure ​

text
devtools/
└── scripts/
    └── ui_kit_generator/
        ├── lib/
        │   ├── ui_kit_generator.dart                 # Barrel file
        │   └── src/
        │       ├── commands/
        │       │   ├── ui_kit_command.dart           # parent `ui-kit` command
        │       │   ├── theme_variant_command.dart    # `theme-variant` command
        │       │   ├── list_command.dart             # `ui-kit list`
        │       │   ├── add_command.dart              # `ui-kit add`
        │       │   ├── remove_command.dart           # `ui-kit remove`
        │       │   ├── status_command.dart           # `ui-kit status`
        │       │   ├── create_command.dart           # `ui-kit create`
        │       │   └── export_tailwind_command.dart  # `ui-kit export-tailwind`
        │       ├── tailwind/
        │       │   ├── ui_kit_tokens.dart            # reads the ui_kit foundations
        │       │   └── tailwind_preset.dart          # v4 CSS / v3 config renderers
        │       ├── models/
        │       │   └── ui_kit_registry.dart          # ui_kit_components.json reader/writer
        │       └── registry/
        │           ├── component_meta.dart
        │           ├── component_registry.dart       # built-in component catalogue
        │           └── layer.dart                    # atom/molecule/organism/template/page
        └── pubspec.yaml

CLI ​

--ui-kit-path defaults to packages/<app>_ui_kit: pre_gen reads project.ui_kit_package_name from archipelago.yaml. Without it, or without a single packages/*_ui_kit package, the default is packages/app_ui_kit (1.1.1 and later).

bash
# List every available component (optionally filtered by atomic layer)
dart run monorepo_toolkit ui-kit list [--layer atom|molecule|organism|template|page]

# Install a component (and its declared dependencies) into ui_kit_components.json
dart run monorepo_toolkit ui-kit add <component-name> [--ui-kit-path packages/<app>_ui_kit]

# Remove a previously-added component
dart run monorepo_toolkit ui-kit remove <component-name> [--ui-kit-path packages/<app>_ui_kit]

# Show installed built-in + custom components vs. the total catalogue
dart run monorepo_toolkit ui-kit status [--ui-kit-path packages/<app>_ui_kit]

# Scaffold a new custom component and register it
dart run monorepo_toolkit ui-kit create --name my-widget [--layer atom] [--dependency other-component] [--ui-kit-path packages/<app>_ui_kit]

# Export the app's ui_kit tokens as a Tailwind v4 preset (optional v3 config)
dart run monorepo_toolkit ui-kit export-tailwind [--output build/theme/tailwind-theme.css] [--v3-config tailwind.theme.cjs] [--ui-kit-path packages/<app>_ui_kit]

# Generate light/dark theme variant files from a YAML config
dart run monorepo_toolkit theme-variant --config path/to/variants.yaml [--prefix App] [--ui-kit-path packages/<app>_ui_kit]

ui-kit add also resolves component_registry's declared dependencies for the component being added, installing any that aren't already present. ui-kit create writes a real placeholder widget file under packages/app_ui_kit/lib/src/components/<layer>/<name>/ and registers it as a custom component in ui_kit_components.json (distinct from the built-in catalogue) — the generated file is a StatelessWidget stub with a TODO: Implement this component. comment, not a working component.

theme-variant reads a variants: list from the given YAML file and writes one <prefix><Variant>Theme class per entry under <ui-kit-path>/lib/src/theme/variants/ — each generated class is a light(ThemeData base)/dark(ThemeData base) pair of TODO stubs (base.copyWith(// Add color overrides here.)), not real color overrides.

Tailwind export (ui-kit export-tailwind) ​

Mini-apps and other web content can follow the app theme without a hand-made export from the Theme Builder. The command reads the real ui_kit foundation source (colors with semantic and dark values, typography, spacing, radius, shadows), so the preset cannot drift from the app. It runs in plain Dart: no Flutter, no archipelago CLI, no auth, so it works in CI.

bash
dart run monorepo_toolkit ui-kit export-tailwind --output build/theme/tailwind-theme.css

The output is a Tailwind v4 file:

css
@theme {
  --color-primary-500: #6366F1;
  --color-bg: #EEF2FF;
  --text-body-large: 1.125rem;
  --spacing-xl2: 2.0rem;
  --radius-md: 8px;
  --shadow-sm: 0 2px 4px #1E293B14;
}

:root[data-theme="dark"] { --color-bg: #0F172A; /* ... */ }
@media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { /* same overrides */ } }
  • Light values are in @theme. Dark values override the same variables when <html data-theme="dark"> is set, or by system preference unless data-theme="light" is set.
  • Variable names match the Theme Builder's Tailwind export. The slate palette is named neutral. The theme bridge capability of webview_sdk_advanced uses the same names, so a mini-app that loads this file can follow the host theme live.
  • --v3-config <path> also writes a Tailwind v3 theme.extend module. Each value is var(--name, <light value>). For dark mode in v3, copy the two dark blocks from the v4 file into your CSS.
  • The output has no timestamp, so you can commit it and review diffs.
  • If a token reference cannot be resolved, the command fails and names it. It does not guess.
  • The renderer (lib/src/tailwind/tailwind_preset.dart) has no imports. The Theme Builder engine keeps a byte-identical copy, so both tools write the same format. CI fails on any drift (scripts/check_tailwind_renderer_sync.sh). Edit the template_base file, then copy it.

Config format (theme-variant) ​

yaml
variants:
  - name: ocean
  - name: sunset

Dependency injection ​

Not applicable — this is a CLI devtool command, not app-runtime code. No archipelago: di_modules block.

post_gen.dart (when isForMonorepo: true) adds devtools/scripts/ui_kit_generator to the workspace, adds a path dependency to devtools/monorepo_toolkit/pubspec.yaml, and injects addCommand(ThemeVariantCommand()) + addCommand(UiKitCommand()) into command_runner.dart at the // --- Installed Free Commands --- marker (needs monorepo_toolkit >= 1.0.10). For older projects without that marker it inserts after the last existing addCommand(...) call, and warns with manual instructions if neither anchor is found.

Dependencies ​

  • Hard prerequisite: base monorepo_toolkit brick must already be generated. No self-generation.
  • When isForMonorepo: false, post_gen.dart skips workspace/command-runner wiring and scaffolds the package standalone.

Known Limitations ​

  • ui-kit create and theme-variant both generate TODO-stub placeholder code, not working components/themes — you still implement the actual widget/color logic yourself.
  • No CI wiring is generated — these are local developer commands.

Changelog ​

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