The Primer Design System serves as the architectural backbone of GitHub’s user interface. From the ubiquitous navigation bars and action-oriented buttons to the intricate banners and breadcrumbs that guide users through the platform, these foundational components are tasked with an ambitious mandate: they must be accessible, flexible, and performant across a dizzying variety of web scenarios. However, as GitHub’s scale evolved throughout 2023, the sheer density of components on individual pages began to create significant friction, leading the engineering team to confront the limitations of their existing styling architecture.
The primary culprit was the team’s long-standing reliance on CSS-in-JS, a popular paradigm that allows developers to write CSS directly within their JavaScript components. While this approach initially offered convenience, it eventually hit a ceiling. As the number of components on complex pages exploded, the runtime costs associated with CSS-in-JS—both on the client side and the server side—began to impact the platform’s performance metrics. It became evident that the Primer team needed to address the issue at its source. The challenge was twofold: they needed to identify a styling alternative that could eliminate these overhead costs while ensuring that the migration process itself would not cause any service disruptions to the millions of developers who rely on GitHub every day.
Introducing CSS Modules as a Scalable Alternative
After evaluating various strategies, the Primer team identified CSS Modules as the ideal solution to meet their stringent requirements. CSS Modules provided a compelling middle ground, allowing engineers to write and leverage native CSS features while maintaining the colocation and encapsulation benefits that the team had grown accustomed to with CSS-in-JS. Under this model, styles are authored in dedicated CSS files alongside the JavaScript source for a component. Crucially, CSS Modules treat class names as local by default, which effectively mitigates the risk of style collisions and the common pitfalls associated with global CSS selectors.
Beyond the organizational benefits, the shift to CSS Modules fundamentally changed how GitHub’s styles are processed. By removing the need for client-side or server-side runtime behavior, the styles are now rolled up into static CSS stylesheets that are delivered as part of the HTML for a page. This transition was a radical departure from the team’s existing architecture, requiring a complete overhaul of every Primer component and every GitHub component that utilized CSS-in-JS. However, the design system served as the perfect vehicle for this massive change, allowing the team to deliver updates at scale with a high degree of confidence.
A Gradual March Towards Modernization
The migration strategy was defined by a cautious, incremental approach. The team understood that they could not simply "flip a switch" without risking the stability of the platform. Instead, they implemented a plan that allowed them to ship updates to individual components while ensuring that the existing CSS-in-JS infrastructure remained fully functional for the portions of the codebase that had not yet been updated.
For each component, the team followed a rigorous cycle of refactoring, integration, and validation. They utilized feature flags to ship these changes in a controlled environment, which created a powerful feedback loop. By rolling out updates gradually, the team could flag issues early, monitor performance improvements in real-time, and confirm that the migration was yielding the expected gains before moving to the next set of components. By December 2024, all components within the Primer library had been successfully migrated to CSS Modules. The results were immediate and measurable, with significant performance wins observed across the board, particularly in reducing the rendering overhead that had previously plagued the platform.
Moving Away from CSS-in-JS at Scale
The success of the Primer migration naturally led to a broader question: could these performance benefits be replicated across the entirety of the GitHub codebase? Removing CSS-in-JS from the core design system was only the first step. One of the most significant hurdles in this endeavor was the prevalence of the sx prop. For years, the sx prop had been the primary method for developers to style and customize Primer components, allowing them to provide inline objects to adjust everything from layout to spacing. While this represented the flexibility that made CSS-in-JS attractive, it also embodied the performance bottlenecks that the team was now working to eliminate.
Reducing the usage of the sx prop across GitHub became the central focus of the next phase. This effort was essential to pave the way for the total removal of CSS-in-JS from the platform. The sheer scale of this task was daunting; there were thousands of instances of sx props scattered throughout the codebase. To manage this transition, the team employed a transitive library called @primer/styled-react. This library served as a vital bridge, allowing teams to continue using the sx prop in existing components while simultaneously enabling the team to begin migrating other parts of the application to the leaner @primer/react package, which did not rely on styled-components.
This transitional phase followed a methodical approach. The team targeted specific areas for refactoring, utilized feature flags to isolate changes, and continuously monitored the impact on production systems. As they undertook this work, the broader JavaScript community saw the maintainers of styled-components announce that the project was moving into maintenance mode, a development that served as further validation that GitHub’s pivot was the correct long-term strategy for the health of their codebase.
The Role of Automation and AI
The work to eliminate sx props was a monumental effort that spanned over a year. The process officially kicked off in April 2025, with approximately 7,760 sx props identified for migration. During the initial six-month period, a dedicated rotation of eight engineers worked to systematically replace these props. They were assisted by custom tools, including a VS Code plugin developed by engineer Ian Sanders and an internal codemod that allowed for the bulk migration of entire files. While the process required careful manual oversight and validation, this combination of automation and human effort proved highly effective. By the end of this phase, the team had migrated 6,419 props, resulting in server-side rendering performance improvements ranging from 1% to as high as 22% on key pages.
By the time the team resumed the final push in April 2026, the landscape of software development had shifted significantly due to the rapid advancement of artificial intelligence. The team found that they could leverage GitHub’s own AI-powered tools, including the Copilot coding agent, to accelerate the remaining workload. In just three weeks, a team of two engineers was able to reduce the remaining 895 sx props down to zero. This final sprint demonstrated the profound impact that modern AI tooling can have on large-scale infrastructure refactoring, turning a potentially months-long project into a brief, highly focused effort.
Decoupling Themes and Future-Proofing
Even after the removal of the sx props, the team had one final, complex challenge to resolve: the theming system. GitHub supports seven distinct themes, including high-contrast modes, all of which were historically managed through styled-components. Decoupling this theming logic was a prerequisite for the total removal of the dependency.
Fortunately, the team had planned for this eventuality years earlier. The core theming variables had always been defined in CSS via the @primer/css package, meaning the actual visual styles were already decoupled from the JavaScript logic. The task was to remove the specific JavaScript utilities that were tethered to the CSS-in-JS framework. After two months of careful migration and rigorous testing, the team was ready to remove the final styled-components dependencies. By June 2026, GitHub was running on 100% CSS Modules, marking the conclusion of a multi-year effort to modernize the platform’s styling architecture.
The project began as a targeted effort to improve component performance and evolved into a comprehensive re-platforming of how GitHub handles UI at scale. By prioritizing safety through feature flagging and utilizing both custom automation and AI-assisted workflows, the engineering team successfully navigated a massive architectural transition without disrupting the user experience. The result is a more performant, sustainable, and maintainable platform, ensuring that GitHub remains optimized for the millions of developers who depend on its interface every day.
