How to add a component to a Flutter UI kit

Docs/Tutorials/ui_kit_component

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

Scaffold a UI kit component with tests and a Widgetbook showcase, choose its atomic level, widget type and variants, and use the optional headless base class.

What you'll learn

• Scaffolding a component with its tests and Widgetbook showcase
• Choosing the atomic level, widget type and variants
• Using the optional headless base class
• Knowing what the hook wires for you

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• UI kit already generated (see UI Kit Setup)

The brick does not check that the UI kit exists. Run it in a project that has one.

Step 1: Generate a UI Component

archipelago generate ui_kit_component

The prompts are:

• componentName: for example Button, Card or Dialog. It is required.
• prefix: your UI kit prefix. It is required.
• atomicType: atoms, molecules, organisms, templates or pages
• widgetType: stateless or stateful
• useHeadless: true adds a behavior-only base class (default false)
• hasVariants: style variants such as primary and secondary (default true)
• hasSizes: size variants such as sm, md and lg (default true)
• hasTypes: type variants such as filled and outline (default false)
• appName: your app name

Or use a config file:

{
  "componentName": "Banner",
  "atomicType": "molecules",
  "widgetType": "stateless",
  "prefix": "App",
  "appName": "MyApp",
  "useHeadless": false,
  "hasVariants": true,
  "hasSizes": true,
  "hasTypes": false
}

archipelago generate ui_kit_component --config banner.json

Step 2: Understand the Generated Structure

packages/my_app_ui_kit/
├── lib/src/components/molecules/banner/
│   ├── banner.dart                    # Barrel
│   ├── app_banner.dart                # The styled widget
│   ├── data/                          # Size, style and variant data classes
│   └── enums/                         # Variant, size and type enums
└── test/components/molecules/banner/
    └── banner_test.dart

apps/my_app_widgetbook/
└── lib/showcase/molecules/banner_showcase.dart

With useHeadless: true, the folder also holds headless_banner.dart. The styled widget then extends HeadlessBanner.

Step 3: Check What the Hook Wired

The post-generation hook:

• adds an export to the barrel of the atomic level, such as molecules.dart
• adds the showcase import and call inside the archipelago:widgetbook_* markers of widgetbook_app.dart
• runs dart format on the output

Running it again changes nothing. A UI kit older than flutter_ui_kit 1.2.5 has no markers. The hook warns, and you add the showcase to widgetbook_app.dart by hand.

Step 4: The Headless Pattern

With useHeadless: true, the base class handles behavior such as tap, focus and state. The styled widget adds the visuals from the theme extensions. Use it for components with several variants and sizes. Leave it off for simple components.

Step 5: Use the Component

import 'package:my_app_ui_kit/my_app_ui_kit.dart';

AppBanner(
  variant: AppBannerVariant.primary,
  size: AppBannerSize.md,
  child: Text('Welcome'),
)

Read colors, spacing and typography with context.colors, context.spacing and context.typography. Do not call Theme.of(context).

Step 6: Add a Variant

Add a value to the variant enum, then handle it where the widget resolves its style:

enum AppBannerVariant { primary, secondary, danger }

Common Customizations

Customization	Where to Change
Variants	The *_variant.dart enum and the style data
Sizes	The *_size.dart enum and the size data
Widget type	Regenerate with another widgetType
Showcase knobs	The *_showcase.dart file

Next Steps

• Add a theme variant to style components differently
• Use the UI Kit Generator to track components and export tokens