Skip to content

One unified design system for Flutter and React.

Role
Design Lead
Outcome
The POS was built using Flutter, and the retail management platform, React. I designed the components, the primitive and semantic tokens, and then the usage patterns for a unified design system for web and mobile experiences.
A Hub dashboard for Bret, a store manager, with an insight from Ivan, the AI assistant, that Black Friday is six weeks away and the current iPhone 17 Pro allocation may leave 12 stores understocked, above cards for total sales, profit, discount ratio, average order age and team sales.

The problem

The company's legacy platform, RQ, was being rebuilt as two new products. Storefront, the new POS, was built with Flutter, and Hub, the new retail management platform, was built with React. The tech teams chose the technologies, and each technology came with its own component library.

The design team had a design system in Figma, with the components, styles and rules for how to use them documented in Zeroheight. The developers had worked on RQ for most of their careers, and the fundamental concept of a design system and a component library was new to them. The developers recreated each style in their own code instead of using the design system's tokens. Even when a screen looked the same as the design, the screen was not built on the tokens, so custom styling spread through both products.

Storefront and Hub ended up on three component libraries. Storefront used Google's Material Design 3 library for Flutter. Hub was meant to use Google's Material Design 3 library for React, but Google stopped supporting it, so Hub moved to MUI. The design team later found that most of MUI was still Material Design 2.

Design teamDesign system in Figma:type, components, how to use themLibraryMaterial Design 3 for FlutterStorefrontBuilt on the defaultsStorefrontFigma styles recreated in codeCustom styling, not tokensCustom components that broke AALibraryMaterial Design 3 for ReactLibraryMUIHubFigma styles recreated in codeCustom styling, not tokensCustom components that broke AASupport endedStill in progress
Storefront and Hub were built on three component libraries, and both ended up with custom styling instead of the design system's tokens.

In both products, heading sizes and captions were set screen by screen. There were several custom buttons with different corner radii and different touch areas. Some custom components broke AA accessibility, and the gaps in MUI were hidden because the components were already customized.

The research

My research was about how to unify three component libraries. I knew the answer would have to be tokens, so I did a fair amount of research into naming conventions, how to structure the tokens, and what the tokens needed to define. I researched Figma plugins, read articles, and worked closely with the senior tech lead, who became my new design system champion.

I structured the tokens in two tiers. Primitive tokens hold the raw values, like every shade of each brand colour. Semantic tokens name each value by what it is for, like text, icons and surfaces, with a set for light mode and a set for dark mode. The tokens define colour, typography, spacing, corner radius, borders, elevation, opacity, motion, sizing and breakpoints. The token names became the variable names in the code, so designers, developers and AI agents all used the same name for the same thing.

This was also the start of my AI experience. I had to learn how GitHub worked, how repositories worked, and how to use agents to manage workflows. I had to learn how to update components, and how to make mistakes in the playground without impacting the core products that used the same design system code.

Decisions and trade offs

  1. I decided that Storefront would use the Material Design 3 Flutter library with no customizations. The company was still working out its new brand, so I chose the default styles until the brand was decided, when the components would be restyled with the design system's tokens. The trade off was an app with a very Google look and feel. Custom styling was added screen by screen anyway, and the design team and the developers had to fix the styling later.

  2. The custom styling spread at first because no developer owned the design system. Over the years, I had partnered with developers who championed the design system alongside me, but those allies came and went. When the company began planning a developer portal for enterprise customers to build their own workflows, I made the case that the portal needed a design system in code that outside developers could build on. The company made the design system a priority, and the senior tech lead took ownership of the design system and made it the standard for every developer.

  3. I decided to move the design system out of Figma and Zeroheight and into GitHub, because AI was moving fast. The design system lived in code beside a playground where designers built prototypes using GitHub Copilot. The trade off was leaving the Figma component library behind. Figma became a secondary tool, where the design team polished designs or workflows to feed back into the agents in the design playground.

DesignTokens: values and their usesShared systemOne shared design system in GitHubProductStorefront, on FlutterProductHub, on ReactDesignPlayground, with CopilotProductDeveloper portalPlanned
One set of tokens became one shared design system in code, and every product, the playground and the planned developer portal were built from it.

The work

Tokens

I wrote the tokens as files in GitHub and handed them to the senior tech lead, who built one shared design system from them. The developers on each product then updated their components to match, so Storefront and Hub finally shared the same styles across Flutter and React.

The design system's colour token file, tokens/color.semantic.light.json, in GitHub. Each colour is named by its use, for text, icons and surfaces, such as primary, secondary, disabled and error, and points to a raw value such as color.neutral.600.
The colour tokens I wrote, in GitHub. Each colour is named by what it is for, and points to a raw value.

Rules

I wrote the design system's rules in Markdown, in a file called TOKEN_GUIDELINES.md. The rules say which tokens each component uses and how each component should be used. A primary button, for example, has one corner radius and a 44px height that meets AA. Developers, designers and AI read the same file.

The design system's written rules, TOKEN_GUIDELINES.md, in GitHub, open at the primary button. Its normal state uses tokens for the background, border, padding and corner radius, and a height token marked as 44 pixels, WCAG AA compliant, with a 2 pixel focus ring for AA compliance.
The rules I wrote for a primary button: one corner radius, and a 44px height that meets AA. Developers and AI read the same file.

The playground

The playground ran on the same components and tokens as Storefront and Hub, so every prototype looked and behaved like the real product from the start. Designers used AI agents in the playground to update components and add new ones without impacting the products. Developers looked at the files to check their work against the design system.

The welcome page of the Design System Sandbox, inside Hub, listing what designers can try: components and design tokens from the company's React packages, Material-UI theming, prototypes, and navigation patterns, with steps for creating an app.
The playground's welcome page, inside Hub. Designers started every prototype from the real components and tokens.

Outcome

When I left, every major React component in Hub ran on the design system, and the Flutter components in Storefront were in progress. Colours met WCAG AA contrast in light and dark mode. The rules lived in Markdown files instead of Zeroheight, and code checks blocked custom styling before it reached the products.

What I would do differently

I would have found a developer to own the design system from the very start, instead of relying on allies who came and went. I would also have pushed for one component library for both products before the tech teams chose their technologies, and written the rules in Markdown from day one.