Change is constant, especially in the fast-paced world of technology, and we are no strangers to this on our Design Systems Team: Phoenix. Our latest endeavor, migrating all platforms to the fifth iteration (DS5) of our design system, “Aviary” is a testament to our commitment to continuous improvement.

In this post I will share Team Phoenix’s journey into packaging Aviary, and how we are making strides to efficiently migrate to DS5 within our app’s codebase with our Aviary Migrator Tool.

Aviary’s New (Packaged) Home

Aviary’s long-time home was nestled within the company’s main monorepository that runs the Fullscript platform. This setup suited us well for a while; small iterations and hot fixes could be released quickly, and contributions from other teams could be implemented with ease. But as Fullscript’s offerings grew, especially with the introduction of the iOS and Android apps, we realized that Aviary needed to spread its wings.

Last year we decided it was time to move out of our parent’s house and get our own place. Aviary is set to migrate out of its current repo and into its very own Aviary package. This strategic shift will undoubtedly enhance our system’s autonomy and scalability. However, it also presents a substantial challenge: migrating from the current repo components (DS4 and below) to our DS5 package components.

That Was Then

Traditionally, component migrations have been a manual and arduous process. Our Front-End Developers (FEDs) are all too familiar with the drill — dedicating an entire day to migrate just one component at a time. For instance, our “column-palooza” last year was a day-long affair focused solely on the column component, which appeared in over a thousand instances! Developers would naturally gravitate towards tickets within their domains — a logical approach but one that highlighted the inefficiency of the entire process. We knew things had to change.

Given the sheer volume of components in our design system, we needed a solution that’s both efficient and developer-friendly. That’s where the Aviary Migrator Tool swoops in.

This Is Now: The Aviary Migrator Tool

Enter the Aviary Migrator Tool: a command-line utility designed for mass component migrations. It automates the conversion of props, the removal of outdated ones, updates import statements, and renames components. In short, it’s the magic wand that removes the need for manual migrations and paloozas altogether. Migrations that could take months are now possible in weeks or even days.

Under the hood, the Aviary Migrator Tool operates on two pivotal assets: JSON Config files and a Component Transformer. Each component in our package is accompanied by a colocated JSON config file, which essentially acts as instructions for that component’s migration. For example, in our Checkbox config file, we specify that the checkboxPosition prop needs to be renamed to alignment. Besides prop renaming, we can also declare things like a new import source, a new component name, props to remove, etc. This flexible strategy ensures that as our components evolve, so too can our migration process — simply by revising these config files.

The Component Transformer parses a React component file and generates an Abstract Syntax Tree. This tree is then traversed, and specific nodes — like the component name or prop names — are updated according to the instructions laid out in the config file.

We leveraged prompts to create a user-friendly CLI that empowers developers of all levels to be able to use the tool. We have outlined prompts to select the components they wish to migrate and the specific parts of the app they want to focus on. It’s a tool that respects an individual’s domain expertise and integrates seamlessly into their workflow and roadmap!

DS5 and Beyond

The Aviary Migrator Tool isn’t just a one-off solution; it’s a long-term companion. As Aviary continues to grow and evolve, our packaged design system, in combination with this tool, will ensure the implementation of our design system remains up-to-date within our Fullscript platforms.

We’re excited to roll out this tool and empower our teams to incorporate migrations into their roadmaps for the year!