Theme Builder

The Archipelago Theme Builder edits the design tokens of a Flutter app in your browser: colour palettes, semantic colours, typography, spacing, border radius and shadows. It previews them on the real app_ui_kit Flutter widgets and on a web page, then exports a theme file for the ui_kit_theme brick or a Tailwind CSS preset.

How to access

Open archipelago.banuacoder.com/theme-builder. It is public: you do not need an account to edit, preview, import or copy the JSON. The dashboard's Theme Builder link opens the same page. Old links (/dashboard/theme-builder, /theme-builder/index.html) redirect to it, and a theme saved by the old builder in your browser is restored the first time you open the new one.

The page works on a phone. Below 1024 px wide, an Edit | Preview switch replaces the side by side layout and the token groups become an accordion.

Layout

• Top bar: the theme name (used as the file name), "Saved in this browser", the Light | Dark base theme, undo and redo, Import and Export.
• Left: the token groups: Colors, Typography, Spacing, Radius and Shadows. Drag the divider (or focus it and use the arrow keys) to make the editor wider.
• Right: the preview, with a Web | Flutter switch and a Components | Screens switch.

Undo and redo keep the last 50 changes. Use the buttons, or Ctrl or ⌘ Z and Ctrl or ⌘ Shift Z. Your theme is saved in this browser half a second after each change.

Colors

The Colors group has two parts, Palettes and Semantic.

Palettes. Eight palettes (primary, neutral, secondary, tertiary, success, warning, error and info), each with 11 shades from 50 to 950. Each palette is a strip of swatches: click a shade to edit it with the colour picker or a hex field (#RRGGBB or #RRGGBBAA). The editor tells you how many semantic colours use that shade. Paste 11 replaces a whole palette with 11 hex values, for example from another design tool.

Semantic colours

Semantic colours are the roles your app asks for: background, text, actions and borders. Point each role at a palette shade (primary.600), white, black or a custom hex. When you change a palette, every role that uses it follows. Action roles also have hover and disabled values.

Each row shows its contrast, calculated by the same engine that writes the export:

Rows	Checked against	Minimum
Text, Text subtle, Text muted, Text disabled	Background	4.5:1
Text on actions	Primary action	4.5:1
Actions	Text on actions	4.5:1
Borders (not the subtle one)	Background	3:1 (non-text)

When a pair fails, the row suggests the next shade of the same palette that passes. Click it to apply it.

Typography

• Fonts: the text font (default Plus Jakarta Sans) and the code font (default JetBrains Mono). The list holds the families the Flutter preview can load from Google Fonts.
• Scale: 14 sizes in pixels, from display1 (56) to overline (10). Sizes from 1 to 200 are accepted. A size you add yourself in an imported file is kept.
• Weights: regular, medium, semiBold and bold, from 100 to 900 in steps of 100.

Spacing

Twelve steps from none (0) to xl6 (96 px). The editor shows Tailwind-style names (2xl) and the key the file stores (xl2) next to it.

Radius

Eight steps from none (0) to full. full is 9999, which renders as a pill.

Shadows

A shadow colour (hex or rgba(), default rgba(0,0,0,0.1)) and six levels from xs to xl2, each with blur, spread and Y offset in pixels. The Preview row and the card at the end of each level show the shadow on your theme's own page and card colours. Both previews also start their Components view with a Shadows / Elevation row: every level as a card, updated as you edit.

Previews

The preview shows your theme as you edit. Pick the content with Components | Screens:

• Web (the default) is a web page styled only with the CSS variables of the Tailwind export, so it shows exactly what the exported file gives a web or mini-app developer. Screens is a mini-app wallet; Components is the ui_kit set as HTML with the preset's utility classes (bg-action-primary, text-fg-inverse, rounded-md, px-lg).
• Flutter renders the real app_ui_kit widgets. It downloads once, about 1.1 MB, when you first open the tab; the Web tab keeps working while it loads. Components shows every widget in its states (AppButton, AppTextField, AppCard, AppOtpInput, AppSheet and more), then a Material group: the standard Flutter widgets (buttons, FAB, card, chips, switch, checkbox, radio, slider, text fields, progress indicators, app bar, navigation bar, dialog and snackbar) under the same ThemeData. Screens shows a login, a list with a detail page, and a checkout built from ui_kit templates. Material widgets are Flutter only, so the Web tab has a note there instead.

The Flutter preview maps your theme onto the kit the way a ui_kit_theme variant does: AppTheme.light() or AppTheme.dark() with the colour, spacing, shadow, radius and typography extensions replaced by your values. Semantic slots the theme does not have (for example foreground.success) keep the kit's values.

If a preview does not load (5 seconds for Web, 20 for Flutter), it shows Reload preview. Your theme is never affected.

Base theme (light or dark)

Light | Dark in the top bar picks the base theme. A base switch resets the semantic colours to that base's defaults; palettes, type, spacing, radius and shadows stay. If you had changed semantic colours, the builder asks first. You can undo a switch. For an app with both modes, export one file per base.

Import

Import opens a file (.json) or takes pasted JSON. You can also drop a file anywhere on the page. Every file the old and new builder exported opens. If a file has a problem, nothing changes and the builder lists each value with its path, for example colors.primary.500: not a hex colour.

Export

The Export menu shows every option, with a Pro or Enterprise chip on the ones your plan does not include:

Item	File	Plan
JSON theme file	<theme_name>.json	Pro or Enterprise
Tailwind v4 CSS	<theme_name>.tailwind.css	Pro or Enterprise
Tailwind v3 config	<theme_name>.tailwind.config.js	Pro or Enterprise
Copy JSON	clipboard	everyone
Generate in your app	the ui_kit_theme command	Enterprise

Each download checks your plan first. If your plan does not include it, a dialog explains why, with Copy JSON instead. If the check cannot reach the server, the builder says so and offers Copy JSON and Try again; it never asks you to upgrade because of a network problem.

The JSON file is the theme document (schemaVersion 1). It has a _meta block, then themeName, baseTheme, colors, semantic, typography, spacing, radius and shadows:

{
  "_meta": {
    "generator": "Archipelago Theme Builder",
    "version": "1.0.0",
    "schemaVersion": 1,
    "compatible_cli": ">=1.4.0",
    "compatible_brick": "ui_kit_theme"
  },
  "themeName": "my_brand",
  "name": "my_brand",
  "baseTheme": "light",
  "colors": { "...": "..." }
}

Tailwind export

A Tailwind preset is a CSS file of design tokens. After you load it, utilities such as bg-primary-500, bg-action-primary, text-fg and rounded-md use your theme.

• v4: <theme_name>.tailwind.css with an @theme block. Import it after @import "tailwindcss";.
• v3: <theme_name>.tailwind.config.js, a preset for presets: [...], whose values are var(--name, <value>).

The variable names are the same as the ui-kit export-tailwind devtools command and the mini-app theme capability, so a web page or a mini-app can follow your app theme with one set of names.

Changed from the old builder

The old builder's Tailwind file also had .btn-primary, .card and .input component classes and a commented v3 block. The new export has neither: v3 is its own file, and you build components from the utilities. The variable names and values are unchanged.

Generate Theme Code

Once you have the exported JSON file, use the Archipelago CLI to add a theme variant to your UI kit with the ui_kit_theme brick Enterprise. Run it from the UI kit package:

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

theme builderAn exported theme becomes a theme variant in your UI kit

Step 1 of 5, builder: You edit palettes, semantic slots, type scale, spacing, radius and shadows in the Theme Builder. Nothing is in your project yet, so there is no file on disk.

packages/app_ui_kit

$ 

theme.json

The brick writes the exported values into the variant:

• Semantic colors (background, foreground, action, outline) into the color extension. Slots the export does not have, such as foreground.success, keep the base theme's values.
• Shadow levels and the shadow color into the shadow extension.
• The type scale and font family into the typography extension (standard(fontFamily:, sizes:)).
• Spacing and radius into the theme file, which also sets colorScheme and scaffoldBackgroundColor from the colors.

These are the same slots the builder's ui_kit preview uses. Font weights are not written, because the kit has no weight slot. A font other than the kit defaults is written as its family name, so add that font to the kit (as an asset font, or load it with google_fonts).

The export has no prefix or appName. The brick reads them from project.prefix and project.name in the project's archipelago.yaml. Add them to the JSON only to override those values.

The ui_kit_theme brick takes these variables:

Variable	Description	Example
themeName	Theme variant name	high_contrast, sepia, corporate
prefix	UI Kit class prefix. Defaults to project.prefix in archipelago.yaml	App, My
appName	App name. Defaults to project.name in archipelago.yaml	my_app
baseTheme	Theme to extend	light or dark
hasColorOverrides	Generate color overrides	true
hasShadowOverrides	Generate shadow overrides (always on for an export)	false
hasTypographyOverrides	Generate typography overrides (always on for an export)	false

Generated files, under lib/src/foundations/themes/ of the UI kit:

• <prefix>_theme_<theme_name>.dart — The theme variant
• extensions/<prefix>_color_extension_<theme_name>.dart — Color overrides (with hasColorOverrides)
• extensions/<prefix>_shadow_extension_<theme_name>.dart — Shadow overrides (with hasShadowOverrides)
• extensions/<prefix>_typography_extension_<theme_name>.dart — Typography overrides (with hasTypographyOverrides)

The new variant slots in alongside the default light and dark themes.

Access Tiers

Capability	Guest	Free	Pro	Enterprise
Edit, preview, import, saved in the browser	Yes	Yes	Yes	Yes
Copy JSON to the clipboard	Yes	Yes	Yes	Yes
Download JSON and Tailwind v4 and v3	--	--	Yes	Yes
The ui_kit_theme command	--	--	--	Yes

An active promo trial counts as its trial tier.

Tips

• Start with your primary color. Pick your brand color in the Primary palette first — the semantic mappings and preview will immediately show how it flows through the entire UI.
• Fix contrast in the semantic layer. When a contrast badge fails, take the suggested shade or change the mapping, rather than editing the palette shade itself.
• Use the semantic layer. Avoid hard-coding hex values in semantic mappings. Use palette references (primary.500, neutral.100) so that changing a palette shade propagates everywhere.
• Export both modes. If your app supports dark mode, create two separate JSON files — one with baseTheme: light and one with baseTheme: dark — and generate both variants.
• Version your theme JSON. Commit the exported JSON to your repository so team members can re-import it into the Theme Builder for future adjustments.
• Compatible CLI version. The Theme Builder requires Archipelago CLI >=1.4.0. Run archipelago --version to verify before generating.