Skip to main content

Getting started

Before we dive into the concepts and inner mechanism of the framework. Let's take a quick look at how to quickly setup a minimum design environment and workflow using Flutter design.


There are mainly 3 packages you need to install, typically in 2 separate Flutter projects:

  • Your production/design package:

    • flutter_design: provide basic annotation & framework to integrate with the design ecosystem.
    • flutter_design_codegen: code generator used to generate code to integrate your widgets in the designer.
  • Your design viewer app:

    • flutter_design_viewer: designer app used to showcase your design system portfolio and/or to debug your designs under different situations.
Flutter design workflowFlutter design workflow

Basic usage

First, on your design code base you have to add the following dependencies to your pubspec.yaml:



Then you would need to annotate the widgets you want to integrate in the design system viewer using the @design annotation. Yes, it's that easy 😄


For more details on how to customize the generated page, please check out Codegen: Annotation.

@design // <- Add this single annotation
class SpecialWidget extends StatelessWidget {

In some cases, this single annotation is not sufficient, e.g. when you have a non-nullable field without a default value. In that case, you would need to specify the initial value/parameter of the field using @DesignField annotation. For more information, please take a look at Annotation.

After running the following build runner command,

flutter packages pub run build_runner build --delete-conflicting-outputs

the following files will be generated:

  • /lib/**/*.design.dart: generated widget component pagesfor the partial file.
  • /lib/ this contains the aggregated generatedComponentPages that can be directly pass to the DesignSystemViewerApp described later.

Note that you might need to add this to the pubspec.yaml file (I'm working on a fix to avoid needing this override):

analyzer: ^3.2.0
dart_style: ^2.2.1

If you see errors like:

class ToSourceIgnoringDesignAnnotationsVisitor implements AstVisitor {
../../../Dev/flutter/.pub-cache/hosted/ Context: 'AstVisitor.visitConstructorSelector' is defined here.

Finally you can create a flutter designer app (currently supporting Android, iOS, Web, macOS, Windows) to host the design system viewer by adding the following dependencies to the pubspec.yaml


Then you need to basically setup the design system viewer in your app using the generatedComponentPages along with some other things you might want to configure:

  • settings
    • enabledLocales: the locales your design system supports.
    • enabledThemes: the ThemeData your design system supports.
  • dataBuilders: your custom data builders
  • pageGroups: grouped pages in the design system catalog.

You can also customize the pages by creating static or dynamic contents. For more information, please check out Designer: Pages.

void main() {
// Recommended to make history browsing work better in web
settings: ViewerSettings(
enabledLocales: {
'en-US': const Locale('en', 'US'),
'de-DE': const Locale('de', 'DE'),
enabledThemes: {
'light': DesignTheme(materialTheme: ThemeData.light()),
'dark': DesignTheme(materialTheme: ThemeData.dark()),
widgetDisplayHeight: 500,
pageGroups: [
// Generated @design/@Design annotated pages
buildComponentPageTree(componentPages: generatedComponentPages),

That's it! You can then run your designer app on any supported platform ✌️