Building a Design System in a Large Flutter App

CA24 Mobile is the mobile banking app built with the Flutter framework for retail clients of Credit Agricole Bank Polska. One of the crucial areas of developing this application was meeting the challenging UX requirements. Flutter is known for its seamless UI/UX features and robust design elements. So, in this case, it enabled the delivery of a unique customer experience.

This article shares lessons and pain points from implementing design systems in Flutter on this specific project, as well as a summary of the essential elements of every design system built with large-scale use in mind.

This article was originally published in our eBook, Building Mobile Banking Apps with Flutter. There, you can find even more content about the entire project.

What is a design system, really?

Different parties may focus on different parts of what a design system actually is. For us, it’s a system that consists of the following:

1. Components

All the building blocks needed to create a product experience for any device. Usually created by a design system designer and used by all the other designers to create experiences for the users - screens in mobile apps and more.

2. Visual & brand foundations

Meaning colors, typography, spacing, iconography, and more. The primitives and variables used by the components. Referenced, not hardcoded. This is also used to create marketing assets (social media or physical) and is meant to establish and maintain brand recognition among customers, so that they always associate certain looks with our products.

3. Patterns & UX

Motion, navigation, page structure, error, and loading states. So that all products and all parts of the product are consistent, and so that designers and developers have clear guidelines on handling the less obvious details.

4. Content guidelines

What should be the tone & voice of your brand, what are the writing rules, what is the common terminology used in the brand’s industry, or established in the product, and tied to the brand.

5. Code

Basically, the implementation of all the sections above.

6. Governance

Versioning the design system, both on the design and implementation side. The process of requesting new features and the policy on accepting contributions from external teams.

Why are design systems important?

• Consistency across products - ensures colors, typography, components, and interactions look and feel the same.
• Brand reinforcement - maintains the visual identity and tone of voice.
• Faster design & development - reusable components and guidelines reduce repetitive work.
• Better collaboration - designers, developers, and content creators speak the same language.
• Scalability - easier to maintain and expand multiple products or platforms.
• Reduced errors & technical debt - fewer one-off solutions and inconsistencies.
• Accessibility compliance - standardizes accessibility practices across all interfaces.

If you want to learn more about the benefits of design systems, read this article written by our UX Designer.

Building the CA24 Mobile design system

The design team should have already prepared the foundations of their design system at this point. The most primitive of which is a style guide that contains the very basic elements defined as design tokens, such as:

• fonts used throughout the application, 
• brand colors and styles for specific content, 
• titles, captions or hints,
• and many other concepts that are defined at the very beginning and then reused as a variable – rather than hardcoded – in all components.

The design team – from the Efigence company we worked with on this project – used Figma to design the CA24 Mobile app. Those basics are reused in the Figma design file as well as in Flutter widgets. Deciding how to define those styles must be well thought out. Well, all those 30 Flutter developers will use it later, right?

Approach to colors in the CA24 Mobile app

There are around 40 different colors in our style guide. All those colors come from Figma. They are validated in terms of contrast and brand compliance. 

We created two structures that help us use our defined colors. 

A CAColor class, which is a child class of Flutter’s Color class. The only difference is that it has its constructor private so that only the cabp_common_ui can instantiate new colors.

final class CAColor extends Color {
  const CAColor._(super.value);
}

If you prefer, you could also use the @internal annotation from the meta package. The goal is to prevent developers from creating their own instances of the colors. They must use only our defined and approved ones.

The second structure is our color palette. A CAColorSchemeData class holds all instances of CAColor and is used by all other widgets or screens. It should be provided by an inherited widget, so widgets that use colors from this color scheme are rebuilt when it changes. For that, we also have a lerp static method, which helps when changing schemes.

It is very handy in our case. The CA24 Mobile application has four color schemes: light & dark themes, and those have a few differences between Detal & SOHO themes (which are fancy names for retail and business account themes).

The second most important basic for us was text style. We also used a custom class for that purpose, making the constructor private.

The second most important basic for us was text style. We also used a custom class for that purpose, making the constructor private.

abstract final class CATextStyles {
  static const _fontFamily = 'Open Sans';
  static const headline1 = CATextStyle._(
    fontFamily: _fontFamily,
    fontSize: 24,
    height: 36,
    fontWeight: FontWeight.w600,
  );
  static const caption100 = CATextStyle._(
    fontFamily: _fontFamily,
    fontSize: 12,
    height: 18,
    fontWeight: FontWeight.w400,
  );
}

We found that keeping the text style and its color separate makes things much more manageable. The color usually isn’t strictly related to the text style, and it’s more convenient to have style and color parameters in CAText instead of using copyWith on style or other wild constructs.

It has also enabled us to accept only our constrained types for text and other widgets:

class CAText extends StatefulWidget {
 CAText(
   String data, {
   super.key,
   this.style,
   this.color,
   this.textAlign,
   this.maxLines,
   this.semanticsLabel,
   this.scalingStrategy,
 })  : data = [CATextSpan(data)],
       assert(maxLines == null || maxLines > 0);
 final CATextStyle? style;
 final CAColor? color;
 // ...
}

Box shadows (which we call elevations), curves, durations, and map styles are solved similarly.

Design system in Flutter – Atomic Design

Once we have the basics set up, it’s time to create our first widget! The Flutter technology already gives us a collection of many customizable widgets.

From the most trivial ones like SizedBox, Container or Text to Material’s ContainedButton, AlertDialog or Scaffold.

Those widgets are put into another. Small parts are reused in more extensive pieces of UI. Brad Frost formalized the process of placing UI pieces together in a methodology better known as Atomic Design.

It’s a design methodology oriented around components, not whole screens. It defines how the minor independent parts – atoms – are built and reused elsewhere, such as in molecules. It can be something simple, like an icon we always place on a small circular background.

A molecule is a group of UI elements that together can deliver some data to the user and simply add purpose to a screen fragment. We have a card where we put a title next to that icon and add some border and box-shadow around it.

Organisms group molecules together, creating fully meaningful parts of the user interface. If you see an organism somewhere, it will be entirely understandable and function as a container with some context that you can safely put next to other “contexts,” like a carousel of mentioned cards with a heading and a close icon on a bottom sheet. If we put it on top of anything, it will still be visually understandable to the user.

Templates help glue everything together. Pages are simply… screens.

I highly recommend reading more about the methodology in “Atomic Design” by Brad Frost, a free online ebook.

The Overall Design squad was developing mainly atoms and molecules, but there were also some complex organisms and templates.

Design system in Flutter – Ambiguity

One of the biggest pain points was the frustration when different people had different ideas on how something should work. Naturally, developers came to designers with questions regarding components they developed. 

Be it how something should behave in certain conditions, what should be clickable in this and that edge case, and how those parts should animate on the screen. 

We usually called each other for ad hoc calls and discussed that. The problems arose when some time had passed, and others started asking questions about why something works that way and not the other. 

Those small decisions led to scratching our heads, searching through conversations with designers on Teams, or revisiting Git history for that component to remind ourselves why we introduced such a change in the first place.

At some point, it became a frustration that needed to be addressed ASAP. From then on, we always update the specifications on Figma or documentation in code straight away so that all knowledge and changes with their motives persist.

On a higher level, this is known as an Architecture Decision Log.

Design system in Flutter – Future-proofing

During the implementation of this common UI library, there were a few situations where we were worried that we would need to rewrite many components because of some changes.

That was the case when we were introducing drastic changes to how the increased text scale accessibility feature was influencing our components, or when there were other changes to how everything should animate with the finger gestures on our custom scaffolds.

You can't see some of those changes, but preparing for some of them is possible.

When we were first developing more complex organisms, there was no motion design prepared at that point, unfortunately. If we completely ignored the transitions when changing the currently selected tab in the tab bar or carousel physics, adding them later would be a refactor. It would cost us not only the time needed to introduce changes in the widget but also the time wasted in migrating all of the code that already used it.

The same principle applies when introducing new variants to components. Let's say you have a card that, until now, had only one style. The designer prepared another state for this card. Let's say that's a card that describes a debit bank card. The new state is for a case when a bank blocks the card. You can add a boolean blocked parameter to that card or introduce an enum that describes its states, like normal, blocked, and probably some others like shipped or expired in the future.

The dark mode was one of the things we knew we'd be implementing at some point in the future, but we didn't have anything close to its specification. If we did not create this construct of color schemes mentioned at the beginning of the article, we would spend a horrendous amount of time replacing all colors with their dark mode counterparts. It paid itself back doubly when we had to introduce another dimension of color themes (retail/business account).

The most recent challenge we encountered was fixing the application's appearance with an increased text scale. You'd be surprised how many people reported issues related to that. Thankfully, all text content, labels, and paragraphs in the app used our custom CAText widget. So we could address the vast majority of those issues by remapping how Flutter's text scale factor influenced font size and its line-height, as we agreed with the design team.

Think ahead. It saves time and helps you stay sane.

Design system in Flutter – Navigation

Other developers develop screens using our UI components based on Figma designs. Figma allows navigating to component definitions from their instances conveniently. There, developers are welcomed with all available variants for a component, its specifications, and its Flutter widget name, which they can use straight away in their Dart code. 

Or, in other cases – an enum value, a named constructor, a few class names, or a widget’s name with some parameter value. Whatever a developer needs to use the component.

Developers from the Overall Design squad sometimes need to investigate how and why a component is used in a certain way. It generally comes down to finding the screen's source code, using Flutter Inspector, or searching for localized strings on a screen. Ideally, all screens have a one-line comment on top of their class that describes where this screen could be found in Figma. 

We have so many screens and designs that we have over a dozen Figma files for different squads with all screens numbered, so it's easy to give a file's name and the screen number to find it. It saves you the hassle of asking the developer or designer for directions when you can't find the design yourself.

Design system in Flutter – Storybook

If we were to name one thing that improved our productivity in the project the most, we would scream storybook without a second of thought.

It serves:

• The Overall Design squad of developers as our magic workplace. We develop widgets in isolation and check all edge cases, strings of different lengths, states, and parameter toggles straight away without needing to sign in to the application. We don't have to wait for the emulator/simulator to boot or click through complex processes to reach this specific widget in a chosen state. It's also much quicker to compile and launch the desktop storybook application than to wait for the mobile one. It's just faster.
• Other developers as a place to explore widgets before putting them inside a screen, checking if it suffices their needs even without writing code and hot reloading the app.
• Hosted on the Web as a place to display increments on Sprint Reviews, where we can open each new or modified component in a new tab and simply go through all of them prepared.
• As an environment to validate the components by the designers if everything looks and works correctly, as they wanted.
• Everyone else. Product Owners – they need to know whether a component is already developed or not to plan their squad's sprint more effectively. Social media people – they can set up and screenshot a card component with the travel credit information for their vacation marketing campaign.
  

All those buttons are easily accessible through the storybook via its knobs. Do you want to see how a button looks in different sizes? Different type? With a leading icon? With a trailing one? On dark background? Sure thing! Adjust the knobs in the sidebar, and you’re good to go!

Design system in Flutter – Communication

Being the code owner of a package used by everyone else makes you hold and create knowledge that needs to be shared with other developers.

When it is information that is crucial at the moment – an announcement of a new component that some squads were awaiting or a deprecation notice with some hints on what to replace the component with – we were using a simple means of a message on our dedicated Teams channel for Common UI announcements. It was marked as important, so everyone got this annoying push notification and wouldn’t miss the news.

We used Markdown documents in the repository for higher-level documentation and other communications that should stay in one place and be accessed when necessary. It is where we store the steps necessary for newly onboarded developers or for people who need to use a part of the framework or shared functionality for the first time.

It is a place with help not specifically on how something works but on what component or solution to choose and why when designing screens and business logic.

Apart from developer-to-developer communication, as the Overall Design developers, we also had developer-to-designer communication. Creating consistency in the app was important. There were three significant learnings for us:

- Formalizing each decision, as mentioned in Ambiguity.

- Process of receiving updates from designers.

A vast part of our daily work was developing components our designers had designed. Or we were updating the already created ones. But we need to be notified of those components that have changed. It is something that would usually be resolved simply by using the JIRA board, where designers drop a tile concerning their component into the next column on a board where we notice it and begin to work on it. For security reasons, designers could not access the JIRA back then, so we made our Kanban board in Figma.

- Components’ changelog would be very handy. 

Sadly, Figma doesn’t support something like that, and we didn’t maintain such changelogs by hand. Figma does indeed have file revision history, but it’s the specific component’s changes that we usually wanted to check, not the whole file.

Design system in Flutter – Responsibility

What is the responsibility of the Overall Design squad? It needs to be decided before developing any of the design systems. Clear code ownership is crucial for maintaining such a big codebase. Otherwise, code without clear ownership will be lost.

Here are some of the things you may wish to be responsible for as a squad or not:

Design system in Flutter – Technical challenges

During development, we stumbled upon many small and big challenges. The first significant decision involved choosing the correct tool for a storybook. As you already know, the outcome was relatively successful. 

When we had this dilemma, there were only two open-source players on pub available – storybook_flutter and dashbook. After doing some research and creating an MVP, we decided to go with `storybook_flutter.` Later, we refactored it to accommodate our requirements, such as a tree structure for the components, two theme dimensions, and Credit Agricole branding.

At the moment of writing, two more solutions are available: widgetbook and flutterbook, both of which seem promising.

Today (June 2023), I’d recommend going with Widgetbook, as it’s probably the most advanced of them all and offers all the features we needed to implement ourselves. They also offer some collaboration tools if you go with their cloud-based solution.

The application's biggest and most complex component is the root bottom drawer located on the start page, below the accordion and benefits river, connected to the screen it shows when expanding. When you play with the application, you can see how the drag gesture slowly reveals the second screen, which is a separate route. 

Apart from that, on this second screen, you can scroll the page, typical behavior, with the header elements folding themselves with the paging zip on the side. When you focus on the search bar, it also animates itself to the app bar. And if you happen to be on top of the page, you may drag the body down to collapse the drawer from the start page.

Trivial stuff, eh? No. The first iteration of this artifact took 2 weeks, heavy research, and deep-diving into the internals of scrolling, gestures, and routes.

Looking inside DraggableScrollableSheet was very helpful, as it did more or less the same things, just a magnitude of complexity less. But after the design team reiterated and reiterated more on how this screen should behave, the following updates were harder and harder to introduce until, at some point, we finally couldn’t introduce the change as the code was such an incomprehensible mess.

It was time for a clean and thought-out refactor. We started by drawing all available states on paper and laying them out on the floor to find how each state relates to the others. Then we knew what we were dealing with. We could start by looking for the correct math for concrete translations and applying them.

On the contrary, we also had some minor technical problems. One of them was the VisualDensity in a few of the Material components we used, like TextField and TextButton. At first, we didn’t notice it. Still, the buttons on mobile were bigger than on the desktop – in the storybook. Once we found the problem, it was a quick override in those widgets, and voila!

This project was a huge opportunity to dive into some Flutter internals. Some of the other things we dove into were inputs, input decorators, and the backend connecting Flutter with native input logic. Dropdowns, how they work, and how they use CompositedTransformFollowers and Targets. Scaffolds with all their insets. Routes, how they animate and handle popping, Overlay.

Summing up this project

Squad 01: Overall Design coordinated the development of the design system. Initially, this task was hardly trivial because even with the Atomic Design approach, during the development process, we had to quickly decide about the final shape of the main Molecules and the Organisms our app was built. We kept growing our library of fully developed components with every sprint. That was one of the most significant benefits of Flutter as a cross-platform technology: we could have just one instance of each component in our own design system.

Some words on building design systems today

The CA24 Mobile project showed us what it takes to build and maintain a design system at enterprise scale. It also taught us that a design system is never really “finished.” It evolves together with the product, the teams working on it, and the technology underneath it.

And Flutter has evolved considerably since we started this project. Some of the challenges we faced when building custom components are easier to solve today, while new approaches and tooling have emerged around maintaining design systems at scale.

What does the current Flutter ecosystem offer in terms of design systems?

Flutter is a framework designed for building applications for mobile, Web, desktop, and even embedded devices. It’s also a very powerful UI toolkit, as it allows us to control every single pixel on the screen rather than relying on a limited set of native components with limited customizability.

Even though Flutter allows you to create basically anything UI-wise, it also comes with batteries included. There are first-party design systems for Material 3 and Cupertino (Apple’s DS pre-Liquid Glass) available for Flutter.

The Material library is the most mature, having almost all Material Design 3 components implemented. It lacks a few of them, such as Side sheet, Split button, Button group, and Toolbar. All of them can be implemented by the app’s developer, though, if they haven't already been developed by the Flutter community as an open-source package on pub.dev.

The Cupertino library used to be much less complete and received less love from the Flutter team in the past. But the gap was narrowed most recently, with iOS-centric components receiving updates that improved their fidelity, and the number of components also rose.

“Decoupling design”

Right now (as of April 2026), there is a “Decoupling design” effort taking place in and around Flutter. The Material and Cupertino libraries were part of the main Flutter package, tightly coupled with the framework and its release cycles. That came with some problems; for example, projects that didn’t yet want to upgrade the framework to the newer minor release (e.g., because the project was now in a support phase and not actively developed) were unable to receive bug fixes regarding the UI part. For example, accessibility improvements related to the European Accessibility Act being in force wouldn’t be easily obtainable with a simple library update, but would be tied to the framework, possibly requiring a bump in the minimum Xcode/Android version, etc.

For this and a few other reasons, the Flutter team decided to move the UI design systems’ implementations into separate packages. Meaning their release cycles are separate, and their bug fixes, improvements, and new major updates don’t depend on having the newest Flutter version.

You can read more about the effort here. Or see the related issues here.

This effort also highlights occasional problems in the framework, where some widgets or classes that aren’t directly tied to any design system are included in that library. The design doc mentions that and requires that such core components be moved back to the framework’s widgets library rather than into a DS-specific one.

The “default”

Because of its completeness, ease of customization, and its integration with the framework, the Material widgets library was frequently considered the default library to use when creating a new project. Even for projects with a more customized or sophisticated appearance.

This definitely saved many hours of engineering work that would otherwise be needed to polish custom-made widgets to be fully functional, responsive, accessible, and keyboard-operable, etc. The problems arose when the design system wasn’t based on Material, or when the design constraints were strict and small details couldn’t be customized to the designer’s liking because they were hardcoded per the Material spec.

Custom design systems

Developing custom design systems from scratch was always possible in Flutter. And now it’s getting easier and cheaper (time-wise) than ever. Because of the decoupling design, more and more widgets from the first-party UI libraries get their “raw” version, being a fully functional widget, with all the features a given component would need to be usable, accessible, animatable, and so on, but with the design or appearance part abstracted out.

A few years ago, maintaining a custom design system meant reimplementing (or “borrowing” wink wink) the vast majority of the code that Flutter already had, tested and fixed over the course of months or years. For some cases, it was even impractical to create a custom widget from the ground up, because it would be missing so many features a user would expect that you’d still use the Material widget, hacked around (I’m looking at you, Mr TextField). Fortunately, that changes for our advantage.

And I’m expecting more open-source, custom-made design systems to pop up in the community over the coming quarters.

Third-party design systems

Apart from the UI libraries implemented by Google as first-party libraries for Flutter, there is some choice on pub.dev available to use.

• macos_ui - (32.5k downloads/mo) implementation of the macOS design language
• shadcn_ui - (56.6k/mo) Shadcn UI port to Flutter
• fluent_ui - (15.4k/mo) Fluent UI unofficial implementation
• yaru - (29.1k/mo) Ubuntu Yaru Flutter widgets and themes for building desktop and web applications
• moon_design - (1.51k/mo) Moon Design System for Flutter. A set of coherent, themable, and extensible widgets following the Moon Design System

The tooling behind an enterprise design system

The UI component implementation itself is just one part of a full design system. We shall consider additional tooling to help us maintain a good experience when using a DS.

Source of truth

The first and foremost is the tool in which the Design System’s single source of truth lies. That would most likely be the design team’s tool, like Figma, Adobe XD, Sketch, or something else. This should be used to build the products, referencing its primitives, variables, and components. If not natively, integrations or tools could be built around that tool to ensure everything is always in sync, and changes in colors, iconography, or variable values are reflected or at least monitored.

Tokens and asset sync script

For projects of any size, a must-have is to have the means to synchronize tokens and assets from your source of truth to the implementation of the design system. We, for example, rely on custom-written but pretty simple scripts that fetch all the variables and icons from Figma, arrange them in the repository, and generate Dart code for them in the right place and structure.

Components catalog and/or preview

Having the components implemented is one thing, but having a browsable preview of these implementations is another. To have a visual understanding of what is developed and how it looks or behaves.

There are many approaches to this.

Goldens

The components should be widget tested. Maybe you even write golden tests (also known as screenshot or snapshot tests in other technologies) for them. You can make the goldens produced less technical and more legible, so that they, besides being a key for comparison in tests, are also readable tables/lists of use cases for a given component.

The downside is that the goldens are primarily an asset for widget testing; specification may be a secondary purpose. They also reside in the project’s repository or in a service like Screenshotbot, which may not be the best-suited tool for browsing and exploring different images as a widget catalog.

Flutter widget previewer

Flutter’s widget previewer is still an experimental feature, but it’s already functional to some degree and has room to mature. This tool is solely for technical developers, as the preview appears in the IDE next to the code, or in a browser when run from the CLI. It’s a good tool for developing components in isolation, checking how they work, and seeing how they support different configs via their API in real time.

Storybook-like

For Flutter, there are a few Storybook-like tools available.

The most popular one, also offering a SaaS, is Widgetbook. It allows you to create stories showcasing individual Flutter widgets, where you can customize knobs that let you interact with them and pass different values. This allows users of Widgetbook to see how different properties can alter the component’s behavior and appearance.

The newest v4 beta also lets you embed component documentation in the stories nicely.

There are also a few other packages like this; most of them are abandoned, though. The newest one that is maintained is werkbank.

Golden tests

Now that we mentioned golden testing in the previous section, we need to store the reference golden files somewhere. The laziest way is to do it in the repository itself. If their number grows, you may add them to Git LFS. Your developers will have access to the goldens to run the tests locally. They can be compared using code editor extensions (e.g., Image diff viewer). Comparing them during code reviews may be trickier.

One tool that can be used for both keeping the golden files themselves and reviewing them is Screenshotbot. You run the golden tests on CI; it uploads the goldens to the service and provides checks for your PR showing changes that need to be inspected and accepted or marked as a regression.

What we'd recommend for a Flutter project

The CA24 Mobile experience - and the projects we've worked on since - have changed how we approach design systems in large Flutter applications.

You don't need to start by building every button, text field, navigation element, and interaction from scratch. At the same time, relying entirely on Material components and adapting them as requirements emerge can eventually become limiting when the product has its own strong visual identity and UX requirements.

Instead, we'd start with a solid design system foundation shared by design and development from day one. That's the approach behind the LeanCode Flutter Design System.

It provides a production-ready set of Flutter components together with their Figma counterparts, built around the same semantic token architecture. Colors, typography, spacing, radii, and other design decisions use corresponding tokens in Figma and Dart, helping keep design and implementation aligned as the product evolves.

The goal isn't to eliminate customization. Quite the opposite: it gives teams a tested foundation that can be adapted to the product's brand and requirements without spending the first months of a project rebuilding the same UI infrastructure.

If you're starting a large Flutter application, you can explore the LeanCode Flutter Design System and see how the Figma and Flutter sides work together.