The Primer Design System powers many of the experiences you see on GitHub today. From buttons to banners to breadcrumbs, these foundational components are required to be accessible, flexible, and performant across a wide variety of scenarios. Back in 2023, the number of components on certain pages began to explode.

This led to several performance-related challenges with the existing CSS-in-JS solution: initial page loads took longer due to styles being initialized on the client, server-side rendering performance declined as style collection shifted from the client, and updates to styles grew out of control as component count grew on a page. It became clear that the Primer team needed to address the issue at the source. They found a solution that met all of their criteria: CSS Modules.

This format would allow them to write and use native CSS features, while still allowing some amount of the colocation and encapsulation that they had come to expect from CSS-in-JS. With CSS Modules, styles would be authored in a CSS file alongside the JavaScript source for the component. It would also allow them to treat all class names as local by default, preventing some of the collisions and challenges that can come from global selectors.

This format also removes the need for any client or server runtime behavior. Instead, styles would roll up into CSS stylesheets that were sent as part of the HTML for a page. However, this solution was radically different from the CSS-in-JS solution they had at the time.

This change would require an update to every Primer component and every component at GitHub authored using this technique. Thankfully, design systems are a perfect vehicle to deliver this kind of change at scale. The situation for moving towards CSS Modules was clear.

The Primer team would need to deliver updates to each of its components, moving them from CSS-in-JS to CSS Modules. At the same time, updates they made to these components could not break any usage in GitHub. Finally, the underlying technique they used for CSS-in-JS also had to continue working for any components in GitHub that were currently using it.

With all these constraints in place, they decided on an incremental migration strategy that would allow them to safely ship component updates without breaking the world. For each component, their plan was to: add a new file that translated existing styles to CSS Modules; add the component to a feature flag that would toggle between the new and old styles; use existing visual regression tests to verify snapshots were identical between their CSS-in-JS solution and CSS Modules; gradually roll out the feature flag to their team, then to GitHub staff, and finally to all GitHub users to catch any issues along the way. This process created a strong feedback loop where issues were flagged early in the process as Primer continuously delivered these changes to GitHub.

The use of feature flags allowed them to do this migration safely while giving them clear signals on the performance benefits of CSS Modules. By December 2024, all components in Primer were migrated over to CSS Modules using this process. They saw performance wins across the board, in particular: 55% less time to server-side render a page; 25% less time for components on a page to initialize.

With clear performance wins from doing this work in Primer, they began to wonder if they could see similar performance wins by doing these conversions in other parts of GitHub. Similarly, how long until they could ultimately drop support for CSS-in-JS across the company? Moving away from CSS-in-JS at GitHub, one of the trickiest parts about removing their CSS-in-JS solution was that it was deeply embedded in the build process. It was used not just for styling, but also for things like theme switching and responsive design.

This made it difficult to simply remove without breaking existing functionality. However, the success of the CSS Modules migration in Primer gave them confidence that t...