Primer Design System provides the foundational components for experiences such as buttons, banners, and breadcrumbs on GitHub. These components need to be accessible, flexible, and highly performant across different scenarios.
In 2023, the number of components on some pages increased rapidly, exposing the following issues with the existing CSS-in-JS solution:
- Initial page loads became longer because styles were initialized on the client.
- Moving style collection away from the client reduced server-side rendering performance.
- Style updates became unmanageable as the number of components on the page increased.
The Primer team looked for a solution that would eliminate client and server costs without causing breakages on GitHub during the transition. CSS Modules made it possible to use local CSS features while preserving the level of encapsulation expected from CSS-in-JS. Styles would be written in CSS files located alongside the JavaScript source; class names would be local by default, and neither the client nor the server runtime would be required. Instead, styles would be bundled into CSS files sent with the HTML.
The following steps were followed for each component during the transition:
- A new file was added to convert the existing styles to CSS Modules.
- A feature flag was used to choose between the old and new styles.
- Visual regression tests were used to verify that the screenshots were identical.
- The flag was gradually enabled for the team, GitHub employees, and then all users.
This process provided early feedback. By December 2024, all components in Primer had been migrated to CSS Modules.
Why it matters
This change shows that in interfaces with a growing number of components, style management affects not only the developer experience but also page loading and server-side processing costs. Bundling styles into files sent with the HTML instead of processing them at runtime aims to reduce operations that create additional overhead on the client and server sides. Breaking the migration into stages using feature flags and visual regression tests is important for enabling technical changes in widely used design systems to be tested without causing user-facing breakages. Receiving early feedback also made it possible to track the issue not only at the code level but through the screens encountered by teams and users. However, the report does not assess how this approach would perform in design systems other than Primer.