Theme Builder

The Archipelago Theme Builder is a visual design token editor for Flutter apps. It runs as a Flutter WASM application directly in your browser, letting you customize your entire Material theme — colors, typography, spacing, border radius, and shadows — with a real-time live preview. When you are satisfied with the result, export your tokens as JSON and generate production-ready Dart theme code with the Archipelago CLI.

How to Access

The Theme Builder is publicly available — no login required to start editing.

Location	URL
Public page	archipelago.banuacoder.com/theme-builder
Dashboard (logged in)	/dashboard/theme-builder

Because the app is compiled to WebAssembly, it loads quickly and runs at near-native speed in any modern browser.

Interface Overview

The builder uses a two-panel layout:

• Left panel — Token editors, organized into five tabs: Colors, Typography, Spacing, Radius, and Shadows.
• Right panel — Live preview that renders a Material widget showcase using your current tokens.
• Top bar — Theme name input, Light/Dark base theme toggle, import/export actions.

Feature Walkthrough

Color Palettes

The Colors tab is split into two sections: Color Palettes and Semantic Color Mappings.

Palettes. There are six palettes, each with 11 shades (50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950):

Palette	Default	Purpose
Primary	Indigo	Brand / accent color
Neutral	Gray	Backgrounds, borders, text
Success	Green	Positive feedback
Warning	Amber	Caution states
Error	Red	Destructive actions, validation
Info	Cyan	Informational callouts

Click any swatch to open a color picker. Each shade is stored as a hex string (e.g. #6366F1).

Semantic mappings. Below the palettes, you map semantic tokens to palette references using the <palette>.<shade> format (e.g. neutral.50). Semantic categories include:

• Background — main, subtle, strong, inverse, card, cardSecondary
• Foreground — text colors, muted, inverse, link, disabled
• Action — primary, primary foreground, secondary, destructive
• Outline — default, subtle, strong, focus ring

This separation means you can swap your entire primary palette and every component updates automatically through the semantic layer.

Typography

Configure the type system across two axes:

• Font families — Primary font (default: Plus Jakarta Sans) and monospace font (default: JetBrains Mono).

• Size scale — 14 named sizes from display1 (56px) down to overline (10px):

  display1: 56  display2: 48  display3: 40
  h1: 32  h2: 28  h3: 24  h4: 20  h5: 18  h6: 16
  bodyLarge: 18  body: 16  bodySmall: 14
  caption: 12  overline: 10

• Weight scale — Four named weights: regular (400), medium (500), semiBold (600), bold (700).

Adjust any value and the preview panel immediately re-renders all Material text styles so you can verify the type hierarchy at a glance.

Spacing

Spacing uses a 4px base unit with 12 named steps:

none: 0    xxs: 2    xs: 4     sm: 8
md: 12     lg: 16    xl: 24    xl2: 32
xl3: 48    xl4: 64   xl5: 80   xl6: 96

Every value is editable. The base unit is configurable if you prefer a different grid (e.g. 8px). The spacing scale is used for padding, margin, and gap throughout the generated theme.

Border Radius

Eight named radius levels from sharp to fully rounded:

none: 0    xs: 2    sm: 4    md: 8
lg: 12     xl: 16   xl2: 24  full: 9999

The full value (9999px) produces pill-shaped elements. Adjust the scale to match your design language — more rounded for friendly consumer apps, sharper for enterprise dashboards.

Shadows

Six elevation levels, each defined by blur radius, spread, and Y-offset:

Level	Blur	Spread	Y-Offset
xs	2	0	1
sm	4	0	2
md	8	0	4
lg	16	0	8
xl	24	0	12
xl2	32	0	16

A global shadow color is also configurable (default: rgba(0,0,0,0.1)). All values are in logical pixels.

Live Preview

The right panel renders a Material widget showcase that updates in real-time as you edit tokens. The showcase includes buttons, cards, text fields, switches, chips, dialogs, and 30+ component themes. Use it to verify that your color contrast, typography hierarchy, and spacing feel cohesive before exporting.

Dark / Light Mode Toggle

The top bar includes a Base Theme toggle (Light or Dark). Switching the base theme changes the starting point for semantic color resolution — for example, background.main defaults to neutral.50 in light mode but would map to a darker shade in dark mode. You can create separate JSON exports for each mode.

Import and Export

Importing a Theme

Two import methods are available from the top bar:

• Paste JSON — Click the upload icon to open a dialog where you can paste raw JSON.
• Upload file — Click the folder icon to select a .json file from disk.

Imported themes replace all current token values. This is useful for continuing work on a previously exported theme or sharing configurations across a team.

Exporting a Theme

1. Click the Export JSON button in the top bar.
2. The builder checks your subscription tier via the Archipelago API.
3. Pro and Enterprise users — The browser downloads a <theme_name>.json file containing the full token specification.
4. Free users — A dialog appears with upgrade options. Editing is always free; exporting requires a paid tier.

The exported JSON includes a _meta block with version compatibility info:

{
  "_meta": {
    "generator": "Archipelago Theme Builder",
    "version": "0.1.0",
    "compatible_cli": ">=1.4.0",
    "compatible_brick": "ui_kit_theme"
  },
  "themeName": "my_brand",
  "baseTheme": "light",
  "colors": { ... },
  "semantic": { ... },
  "typography": { ... },
  "spacing": { ... },
  "radius": { ... },
  "shadows": { ... }
}

Generate Theme Code

Once you have the exported theme.json, use the Archipelago CLI to generate Dart theme files:

archipelago generate ui_kit_theme --config theme.json

The ui_kit_theme brick will prompt for:

Variable	Description	Example
themeName	Theme variant name	high_contrast, sepia, corporate
prefix	UI Kit class prefix	App, My
appName	App name for imports	my_app
baseTheme	Theme to extend	light or dark
hasColorOverrides	Generate color overrides	true
hasShadowOverrides	Generate shadow overrides	false
hasTypographyOverrides	Generate typography overrides	false

Generated files include:

• app_colors.dart — Color palettes and semantic color tokens
• app_typography.dart — Font families, size scale, weight scale
• app_spacing.dart — Spacing scale constants
• app_theme.dart — Assembled ThemeData with all tokens applied

The generated code integrates with the existing UI Kit structure. If you already have a theme, the brick updates the relevant part directives so your new variant slots in alongside the default light and dark themes.

Access Tiers

Capability	Free	Pro	Enterprise
Edit tokens in browser	Yes	Yes	Yes
Live preview	Yes	Yes	Yes
Import JSON	Yes	Yes	Yes
Export JSON	--	Yes	Yes
Generate Dart code via CLI	--	Yes	Yes

Free users can experiment with the full editor and preview. Exporting and code generation require a Pro or Enterprise subscription.

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.
• Check contrast in the preview. The Material showcase renders real components. If text is hard to read on a card or button, adjust the semantic foreground mappings rather than individual palette shades.
• 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.