For years, the Primer Design System has served as the bedrock of the user experience on GitHub. From the simple buttons that initiate a pull request to the complex banners and breadcrumbs that navigate the repository interface, these foundational components are designed to be accessible, flexible, and performant across a massive range of user scenarios. However, as the scale of the GitHub platform expanded throughout 2023, the engineering team began to encounter significant friction. The sheer number of components being rendered on complex pages started to climb, leading to a series of performance-related bottlenecks tied to the existing CSS-in-JS architecture.
It became increasingly evident that the Primer team needed to address these architectural constraints at their source. The goal was not merely to patch the existing system but to find a robust alternative that could eliminate the client and server-side runtime costs associated with CSS-in-JS. Critically, any proposed replacement had to be implemented in a way that guaranteed zero downtime or breakage for GitHub’s global user base. The engineering team embarked on a journey that would eventually see the company move away from a long-standing industry standard in favor of a more performant, native approach.
Introducing CSS Modules as a Scalable Solution
After evaluating various options, the Primer team identified CSS Modules as the ideal solution to meet their rigorous technical requirements. This format offered a unique advantage: it allowed engineers to leverage native CSS features while maintaining the benefits of colocation and encapsulation that teams had grown accustomed to with CSS-in-JS.
With CSS Modules, styles are authored in dedicated CSS files positioned directly alongside the JavaScript source code for a given component. By default, this approach treats class names as local, which effectively mitigates the risk of global style collisions—a common pain point in large-scale web applications. More importantly, this transition removed the necessity for client-side or server-side runtime behavior. Instead of the browser or server performing intensive calculations to resolve styles at runtime, the styles are compiled into static CSS stylesheets that are delivered as part of the HTML for a page.
While this represented a significant shift in methodology, the Primer team recognized that a design system is an ideal vehicle for driving architectural change at scale. By updating the core components that power GitHub’s UI, they could propagate these changes across the entire product ecosystem in a structured and controlled manner.
A Gradual March Towards Modernization
The migration strategy was designed to be methodical and incremental. The team understood that they could not simply "flip a switch." They needed to deliver updates to every component—moving them from CSS-in-JS to CSS Modules—without disrupting existing user experiences. Furthermore, the legacy CSS-in-JS infrastructure had to remain fully functional to support components that were still in the process of being migrated.
To achieve this, the team adopted an incremental strategy that allowed them to ship updates safely. They utilized feature flags extensively, which created a powerful feedback loop. As Primer continuously delivered changes to the main GitHub codebase, engineers could monitor performance metrics in real-time, allowing for rapid iteration and the early detection of any regressions. This rigorous approach ensured that the migration was not just a theoretical improvement, but a tangible, data-backed success.
By December 2024, the entirety of the Primer component library had been successfully migrated to CSS Modules. The results were immediate and impactful, with significant performance improvements observed across the platform. These wins provided the team with the confidence to look beyond the design system and consider how a broader transition away from CSS-in-JS might benefit other parts of the GitHub platform.
Moving Away from CSS-in-JS at GitHub
The most challenging aspect of this migration centered on the sx prop. For years, the sx prop had been the primary method for developers to style and customize Primer components. It allowed teams to pass inline objects to override component styles, embodying both the immense flexibility and the inherent performance costs of CSS-in-JS. While it was a powerful tool for rapid development, it also created a heavy dependency on the runtime styling engine.
Reducing the usage of the sx prop across the broader GitHub codebase became the next priority. This effort was a prerequisite for the total removal of CSS-in-JS from the platform. The team realized that while the Primer design system itself had moved on, the rest of the massive GitHub codebase remained deeply entrenched in styled-components and the sx prop paradigm. With thousands of instances to address, the team needed a strategy to manage this complexity.
To bridge the gap, the team created "wrapper" components within a transitive library titled @primer/styled-react. This library was designed to allow continued sx prop usage in newly migrated components, ensuring that developers could continue to use existing patterns while the team transitioned components to the cleaner, more performant @primer/react package. This created a phased migration path, allowing the team to realize performance gains incrementally while maintaining backward compatibility.
The Path to "Styled Box Zero"
The final phase of the transition was a monumental effort often referred to as "Styled Box Zero." By April 2025, the team faced the daunting task of migrating approximately 7,760 sx props. This effort was significantly bolstered by tooling; developer Ian Sanders created a specialized VS Code plugin to assist with per-prop migration, and an internal codemod was developed to automate the conversion of entire files.
Over the course of six months, a rotation of eight engineers successfully migrated 6,419 props. The results were quantifiable, with Server-Side Rendering performance gains ranging from 1% to as high as 22% for specific services. As this work progressed, the landscape of AI-assisted development began to shift as well. By the time the team returned to the final push in April 2026, they had access to significantly more advanced tools, including sophisticated Copilot coding agents. With these agents and a team of just two engineers, the final 895 sx props were eliminated in just three weeks.
Navigating the Complexity of Themes
Even after the sx props were successfully removed, the team faced one final hurdle: the complex theming infrastructure. GitHub supports seven distinct themes, including various high-contrast modes, all of which had been managed through styled-components. Decoupling this theming system was essential before the final dependencies could be purged.
The team had already planned for non-styled theming when they migrated @primer/react in late 2025, leveraging CSS variables defined in the @primer/css package. The challenge lay in removing the JavaScript utilities that were tightly coupled with styled-components. Again, the team employed a strategy of slow rollouts and rigorous feature flagging. After two months of careful execution and testing, they finally cleared the path for the total removal of the dependency.
By June 2026, GitHub was running on 100% CSS Modules. What began as a performance-focused initiative turned into a comprehensive re-platforming of how the company styles, themes, and ships its user interface at scale. The successful migration proved that even the most deeply embedded architectural choices can be evolved safely through a commitment to incremental change, robust testing, and the intelligent use of modern development tools. For the engineering teams at GitHub, the focus remains firmly on enhancing performance, user experience, and the long-term maintainability of the platform.
