How to generate a Flutter UI kit with a Widgetbook

Docs/Tutorials/flutter_ui_kit

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

Generate the design system package and Widgetbook app, pick a brand prefix, read tokens through typed BuildContext extensions, and override radius and sizes.

What you'll learn

• Generating the design system package and the Widgetbook app
• Choosing a prefix for your brand
• Reading design tokens through the typed BuildContext extensions
• Overriding radius and type sizes
• Running the Widgetbook and adding components

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• The asset packages from flutter_asset

The UI kit depends on {app}_asset and asset_core. The brick does not generate them for you. flutter_modular_monorepo generates both together. Generating the UI kit alone into a workspace without flutter_asset fails to resolve.

Step 1: Generate the UI Kit

New projects already include the UI kit. To generate it yourself, run:

archipelago generate flutter_ui_kit

The prompts are:

• appName: your app name, for example Acme
• prefix: the prefix for class names, for example Ac
• prefixCasing: pascalCase (AcButton) or upperCase (ACButton)
• isForMonorepo: leave this as true
• includeGenerated: false keeps generated files out of git

Or use a config file:

{
  "appName": "Acme",
  "prefix": "Ac",
  "prefixCasing": "pascalCase",
  "isForMonorepo": true,
  "includeGenerated": false
}

archipelago generate flutter_ui_kit --config ui_config.json

The prefix only changes class names. The package is always named {app_name}_ui_kit.

Step 2: Explore the Generated Structure

packages/acme_ui_kit/lib/src/
├── components/            # atoms, molecules, organisms, templates, utilities
├── extensions/            # build_context_extensions.dart
├── foundations/
│   ├── colors/            # Color foundation, tokens and nested groups
│   ├── typography/
│   ├── spacing/
│   ├── radius/
│   ├── shadows/
│   └── themes/            # AcTheme and the theme extensions
├── initializers/          # Font, asset preload and AcUiKitInitializer
└── utilities/

apps/acme_widgetbook/      # Widgetbook showcase app

Step 3: Customize the Foundations

Edit the foundation files in foundations/ to match your brand. Colors are grouped into action, background, foreground and outline. Typography holds font families and text styles. Spacing, radius and shadows are token files.

Step 4: Read Tokens from BuildContext

The kit generates typed extensions. Use them instead of Theme.of(context):

final colors = context.colors;
final typography = context.typography;
final spacing = context.spacing;

The full list is colors, typography, spacing, radius, shadow and assets. Each has an OrNull form, such as context.colorsOrNull, which returns null when the extension is missing.

Step 5: Override Radius and Type Sizes

Replace the radius extension to change every card, button and input:

final base = AcTheme.light();
final radius = base.extension<AcRadiusExtension>()!.copyWith(md: 20)
    as AcRadiusExtension;
final theme = base.copyWith(extensions: [
  radius,
  ...base.extensions.values.where((e) => e is! AcRadiusExtension),
]);

Change font sizes with a size map. Keys are display1 to display3, h1 to h6, bodyLarge, body, bodySmall, caption and overline. A missing key keeps its token size.

AcTypographyExtension.standard(sizes: {'h1': 36, 'body': 15});

Step 6: Start the Kit at Launch

AcUiKitInitializer loads fonts and preloads SVG and Lottie assets. Call it once during pre-launch, before the first frame that uses the design system:

await AcUiKitInitializer.initialize(
  context,
  additionalAssets: [AcLogos.wordmark],
  parallelAssetLoading: true,
);

Step 7: Run the Widgetbook

cd apps/acme_widgetbook
flutter run -d chrome

The Widgetbook lists foundations, atoms, molecules, organisms and templates. It has addons for light and dark themes, text scale and screen size.

Step 8: Add New Components

Use the ui_kit_component brick:

archipelago generate ui_kit_component

See Creating a UI Kit Component.

Prefix Naming

Company	Prefix	Result
Acme	Ac	AcButton, AcCard
Globex	Gx	GxButton, GxCard
Generic	App	AppButton, AppCard

Next Steps

• Set up networking to connect your UI to APIs
• Add authentication with themed login pages