flutter_ui_kit Free

Docs/Bricks/flutter_ui_kit

Tier

Freeversion 1.3.3

Command

archipelago generate flutter_ui_kit

Generates

• apps/<app_name>_widgetbook
• packages/<app_name>_ui_kit

Optionally uses

flutter_asset

Tutorial

Step-by-step: add flutter_ui_kit to a project

A comprehensive Flutter UI kit brick that generates a customizable design system package with foundations (colors, typography, spacing, radius, shadows), theme extensions, atomic components, and a Widgetbook showcase app.

Variables

Variable	Type	Default	Description
appName	string	MyApp	Application name for package naming
prefix	string	App	Customizable UI kit prefix (e.g., App, Aloha, Acme)
prefixCasing	enum (upperCase, pascalCase)	pascalCase	Casing style for the prefix in component names
isForMonorepo	boolean	true	Whether this UI Kit will be part of a monorepo structure
includeGenerated	boolean	false	Whether to include generated files in version control

Usage

Interactive

archipelago generate flutter_ui_kit

Non-interactive (CI)

archipelago generate flutter_ui_kit --config my_config.json

Config Template

{
  "@appName": "Application name for package naming",
  "appName": "MyApp",
  "@prefix": "Customizable UI kit prefix (e.g., App, Aloha, Acme)",
  "prefix": "App",
  "@prefixCasing": "Casing style for the prefix in component names (upperCase | pascalCase)",
  "prefixCasing": "pascalCase",
  "@isForMonorepo": "Whether this UI Kit will be part of a monorepo structure",
  "isForMonorepo": true,
  "@includeGenerated": "Whether to include generated files in version control",
  "includeGenerated": false
}

Generated Structure

apps/
└── {app_name}_widgetbook/
    ├── lib/
    │   ├── main.dart                      # Entry point
    │   ├── widgetbook_app.dart            # Widgetbook registration (all categories)
    │   └── showcase/
    │       ├── foundations/               # Colors, Typography, Spacing, Radius, Shadows
    │       ├── atoms/                     # Button, IconButton, Card, Input, Avatar, Icon, etc.
    │       ├── molecules/                 # ProductCard, OtpInput, Sheet
    │       ├── organisms/                 # AppBar, SliverAppBar
    │       └── templates/                 # Page, Centered, Scaffold, Sliver, Empty, Error, Loading
    ├── web/                               # Web platform for WASM build
    └── pubspec.yaml
packages/
└── {app_name}_ui_kit/
    ├── lib/
    │   ├── {app_name}_ui_kit.dart
    │   └── src/
    │       ├── components/
    │       │   ├── components.dart
    │       │   ├── atoms/
    │       │   │   ├── atoms.dart
    │       │   │   ├── animations/
    │       │   │   ├── assets/
    │       │   │   ├── buttons/
    │       │   │   ├── cards/
    │       │   │   ├── display/
    │       │   │   ├── icons/
    │       │   │   └── inputs/
    │       │   ├── molecules/
    │       │   ├── organisms/
    │       │   ├── templates/
    │       │   └── utilities/
    │       ├── extensions/
    │       │   ├── extensions.dart
    │       │   └── build_context_extensions.dart
    │       ├── foundations/
    │       │   ├── foundations.dart
    │       │   ├── colors/
    │       │   │   ├── colors.dart
    │       │   │   ├── {prefix}_color_foundation.dart
    │       │   │   ├── {prefix}_color_token.dart
    │       │   │   └── nested/
    │       │   │       ├── nested.dart
    │       │   │       ├── {prefix}_action_colors.dart
    │       │   │       ├── {prefix}_background_colors.dart
    │       │   │       ├── {prefix}_foreground_colors.dart
    │       │   │       └── {prefix}_outline_colors.dart
    │       │   ├── typography/
    │       │   │   ├── typography.dart
    │       │   │   ├── {prefix}_font_family.dart
    │       │   │   ├── {prefix}_typography_foundation.dart
    │       │   │   └── {prefix}_typography_token.dart
    │       │   ├── spacing/
    │       │   │   ├── spacing.dart
    │       │   │   ├── {prefix}_spacing_foundation.dart
    │       │   │   └── {prefix}_spacing_token.dart
    │       │   ├── radius/
    │       │   │   ├── radius.dart
    │       │   │   └── {prefix}_radius_token.dart
    │       │   ├── shadows/
    │       │   │   ├── shadows.dart
    │       │   │   ├── {prefix}_shadow_foundation.dart
    │       │   │   └── {prefix}_shadow_token.dart
    │       │   └── themes/
    │       │       ├── themes.dart
    │       │       ├── {prefix}_theme.dart
    │       │       └── extensions/
    │       │           ├── extensions.dart
    │       │           ├── {prefix}_asset_extension.dart
    │       │           ├── {prefix}_color_extension.dart
    │       │           ├── {prefix}_radius_extension.dart
    │       │           ├── {prefix}_shadow_extension.dart
    │       │           ├── {prefix}_spacing_extension.dart
    │       │           └── {prefix}_typography_extension.dart
    │       ├── initializers/
    │       │   ├── initializers.dart
    │       │   ├── {prefix}_asset_preload_initializer.dart
    │       │   ├── {prefix}_font_initializer.dart
    │       │   └── {prefix}_ui_kit_initializer.dart
    │       └── utilities/
    │           ├── utilities.dart
    │           ├── asset_precacher.dart
    │           ├── debouncer.dart
    │           └── lottie_cache.dart
    ├── test/
    │   ├── flutter_test_config.dart
    │   ├── foundations/
    │   │   ├── colors/
    │   │   │   └── color_golden_test.dart
    │   │   ├── radius/
    │   │   │   └── radius_golden_test.dart
    │   │   ├── spacing/
    │   │   │   └── spacing_golden_test.dart
    │   │   └── typography/
    │   │       └── typography_golden_test.dart
    │   └── util/
    │       ├── app_test_wrapper.dart
    │       └── color_swatch_widget.dart
    ├── analysis_options.yaml
    └── pubspec.yaml

Design System Extensions

The UI kit generates typed BuildContext extensions for accessing design tokens. These are defined in build_context_extensions.dart and provide direct access to theme extensions without calling Theme.of(context).

Extension	Type	Description
context.colors	{prefix}ColorExtension	Color tokens (action, background, foreground, outline)
context.typography	{prefix}TypographyExtension	Typography tokens (font families, text styles)
context.spacing	{prefix}SpacingExtension	Spacing tokens (padding, margin values)
context.radius	{prefix}RadiusExtension	Border radius tokens
context.shadow	{prefix}ShadowExtension	Shadow/elevation tokens
context.assets	{prefix}AssetExtension	Asset references (images, icons, Lottie)

Each extension also has a nullable ?OrNull variant (e.g., context.colorsOrNull) that returns null instead of throwing when the extension is not found in the widget tree.

Overriding radius and the type scale

Components read radius through context.radius.border.* and context.radius.circular.*. Those presets are built from the extension's own values. To change the corners of every card, button and input, replace the radius extension:

final base = {prefix}Theme.light();
final radius = base.extension<{prefix}RadiusExtension>()!.copyWith(md: 20)
    as {prefix}RadiusExtension;
final theme = base.copyWith(extensions: [
  radius,
  ...base.extensions.values.where((e) => e is! {prefix}RadiusExtension),
]);

To change font sizes, build the typography extension from a size scale. The keys are display1-display3, h1-h6, bodyLarge, body, bodySmall, caption and overline. A key you leave out keeps its token size. Button styles follow body, bodySmall and caption. Code styles follow bodySmall and caption.

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

The light and dark themes also differ in their action colors ({prefix}ActionColors.dark()). In dark mode, the secondary, destructive and success colors are one shade darker, so white text on them has more contrast.

Convention: Always use these typed extensions instead of Theme.of(context). They provide compile-time safety, better autocomplete, and consistent access to the design system across all feature pages.

Widgetbook Showcase

The UI kit comes with 31 pre-built components ready to use out of the box. You can preview them live at the Component Showcase.

The Widgetbook app is included in your generated project, so you can showcase your own design system as you customize it. Run it on desktop (macOS, Linux, Windows), web (Chrome), or even mobile (iOS, Android) — your team can explore every component, toggle between light and dark themes, and tweak knobs interactively.

Open a component to see it rendered with its knobs. Foundations show the token values:

Atoms such as buttons expose style, color, size, label, disabled, loading and expanded knobs:

Categories (31 components)

Category	Components
Foundations (5)	Colors, Typography, Spacing, Radius, Shadows
Atoms (15)	Button, IconButton, Card, GradientBorderContainer, TextField, Checkbox, PasswordField, PinInput, MaskedInput, Avatar, Icon, AssetWidget, AnimatedEntrance, CountdownTimer, RotatingText, SlidingText
Molecules (3)	ProductCard, OtpInput, Sheet
Organisms (1)	AppBar (standard + sliver variants)
Templates (7)	PageTemplate, CenteredPageTemplate, ScaffoldTemplate, SliverScaffoldTemplate, EmptyStateTemplate, ErrorPageTemplate, LoadingPageTemplate

Addons

• MaterialThemeAddon — Switch between light and dark themes
• TextScaleAddon — Test text scaling (min 0.8x)
• ViewportAddon — Simulate different screen sizes (phone, tablet, desktop)

Running Locally

# Desktop (fastest for development)
flutter run -d macos    # or linux, windows

# Web (for sharing / WASM preview)
flutter run -d chrome

Building WASM for Deployment

cd apps/{app_name}_widgetbook
flutter build web --wasm --release --base-href=/showcase/

Live Demo

The Archipelago showcase is deployed at archipelago.banuacoder.com/showcase and automatically updated when UI kit changes are pushed to main.

Adding New Component Showcases

Use the ui_kit_component brick to generate a component with its widgetbook showcase:

archipelago generate ui_kit_component

This creates the component file, test file, and a showcase file at apps/{app_name}_widgetbook/lib/showcase/{atomicType}/{component_name}_showcase.dart. Register it in widgetbook_app.dart under the appropriate category.

DI and wiring notes

There is no GetIt/archipelago: DI manifest here — the UI kit is a design-system package consumed via a path: dependency, not a registered service. The one thing that needs explicit wiring at app startup is {prefix}UiKitInitializer:

await AppUiKitInitializer.initialize(
  context,
  additionalAssets: [AppLogos.wordmark], // preload extra assets beyond the defaults
  parallelAssetLoading: true,
);

initialize() runs initializeFonts() (Google Fonts) and initializeAssets() (SVG/Lottie precache via AssetPreloadInitializer) concurrently via Future.wait. Call it once during pre-launch init, before the first frame that uses the design system.

isUiKitInteractive(Element) reports the kit's interactive controls ({prefix}Button, {prefix}IconButton, {prefix}TextField, {prefix}PasswordField, {prefix}MaskedInput, {prefix}PinInput, {prefix}OtpInput, {prefix}Checkbox). The host's bootstrap.dart passes it to ensureAppBinding, so the debug-only Marionette MCP driver lists these controls under their kit names. Add a new interactive control to it.

Dependencies

• {app_name}_asset and asset_core — hard, unconditional path: dependencies (the UI kit's {prefix}AssetExtension/AssetWidget render {prefix}Asset values from flutter_asset). Not self-generated — flutter_modular_monorepo's own post-gen hook generates flutter_asset and flutter_ui_kit together as part of initial project scaffolding, which is why this dependency is never missing in the normal flow. Generating flutter_ui_kit standalone into a workspace that never had flutter_asset will fail to resolve.
• flutter_svg, lottie, google_fonts, skeletonizer, haptic_feedback, equatable, cupertino_icons — vendor packages backing individual components/foundations.
• dependencies (shared workspace package) — DI/state-management/routing re-exports.

Known Limitations

• No standalone-generation guard for the flutter_asset hard dependency (see Dependencies above) — generating this brick outside the flutter_modular_monorepo flow requires flutter_asset to already exist.
• prefixCasing only affects component/class names; it does not rename the generated package itself (always {app_name}_ui_kit).
• Widgetbook is bundled as a full separate app (apps/{app_name}_widgetbook) rather than an optional dev-only target — it always adds an extra app to the workspace.

Changelog

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