The Primer Design System underpins much of GitHub's user interface, providing foundational components like buttons, banners, and breadcrumbs that must function reliably, remain accessible, and perform well across diverse use cases. During 2023, the proliferation of components on certain pages created mounting performance problems with the existing CSS-in-JS infrastructure.
The performance bottlenecks manifested in three ways: client-side initialization delayed initial page loads, server-side rendering efficiency declined as style computation shifted from browser to server, and style updates became increasingly unwieldy as component density grew. The Primer team recognized the need to address the underlying architecture rather than optimize around it, seeking an alternative that would eliminate both client and server overhead while maintaining stability throughout the transition.
Adopting CSS Modules as the foundation
CSS Modules emerged as the solution meeting all requirements. This approach enabled the team to write native CSS while preserving the component-level encapsulation and colocation benefits they valued from CSS-in-JS. Styles would be authored in dedicated CSS files alongside component source code, with class names treated as locally scoped by default to prevent naming collisions. Critically, this eliminated runtime overhead: styles would compile into static stylesheets delivered as part of the initial HTML payload.
The shift represented a fundamental departure from the existing system, requiring updates to every Primer component and all GitHub components built using the previous technique. Design systems proved to be the ideal vehicle for orchestrating such a large-scale architectural change.
Incremental migration with feature flags
The migration strategy balanced three competing constraints: each component needed updating, changes could not disrupt existing GitHub usage, and the old CSS-in-JS infrastructure had to remain functional for components still depending on it. The team implemented a staged approach for each component:
- Create a new CSS Modules file translating existing styles
- Gate the new styles behind a feature flag toggling between old and new implementations
- Validate visual regression tests confirmed identical snapshots across both approaches
- Progressively enable the flag for the Primer team, then GitHub staff, then all users
This feedback loop caught issues early as Primer continuously shipped updates to GitHub, and feature flags provided clear signals on performance improvements. By December 2024, all Primer components had transitioned to CSS Modules. The results showed substantial gains: server-side rendering time dropped 55%, and component initialization time fell 25%.
Eliminating the sx prop across GitHub
The sx prop represented both the best and worst of CSS-in-JS at GitHub. It offered excellent TypeScript integration with design tokens and kept styling logic colocated with components, but imposed high runtime costs due to dynamic inline object evaluation and scaled poorly as component density increased. Reducing sx usage became the next priority, promising immediate performance gains and clearing the path for complete CSS-in-JS removal.
While Primer itself had moved off styled-components, thousands of sx props throughout the GitHub codebase still depended on it. Rather than attempt wholesale conversion, the team created a transitional wrapper package called @primer/styled-react. This allowed existing code using sx to continue functioning while new code could import directly from @primer/react and realize performance benefits immediately.
Scaling the sx migration
The migration process proceeded package by package: translate all sx usage into equivalent CSS Modules files, replace @primer/styled-react imports with @primer/react imports, validate in pre-production, and deploy. The effort began in April 2025 with approximately 7,760 sx props requiring conversion.
An in-house developer, Ian Sanders, created a VS Code plugin to assist with individual prop migration, while an internal codemod automated bulk file conversions. Over six months, a rotation of eight engineers migrated 6,419 props, observing server-side rendering improvements ranging from 1% to 22% depending on the page.
When work resumed in April 2026, the landscape had shifted. With Copilot coding agents now available, a two-person team reduced the remaining 895 sx props to zero in just three weeks, combining automation with human oversight.
Decoupling theming from styled-components
With sx migrations complete, styled-components removal appeared within reach—until the team confronted GitHub's theming layer. The platform supports seven distinct themes, each with a high-contrast variant, all implemented through styled-components. Before removing the dependency, theming had to be decoupled.
The challenge was manageable because theming variables had always been defined in CSS through the @primer/css package, and the team had already planned for non-styled theming when migrating @primer/react in late 2025. The remaining work involved removing JavaScript utilities and functions that styled-components enabled. Following the established pattern—migrate, feature flag, roll out gradually—the team completed theming decoupling within two months, including a feature flag around the dependency removal itself for maximum safety.
Completion and results
GitHub transitioned to 100% CSS Modules by June 2026. The safeguards implemented throughout—feature flags, staged rollouts, visual regression testing, and production validation—enabled the team to execute a major architectural shift without disruption. What began as a CSS migration evolved into a complete re-platforming of how GitHub handles styling, theming, and UI delivery at scale.
The final outcome eliminated sx, styled-components, and styled-system from GitHub's main codebase while maintaining stability and realizing substantial performance gains. The approach demonstrated how design systems can serve as vehicles for large-scale technical transformation when combined with careful staging, feature flags, and comprehensive testing.