Anurag’s Read

Improving site performance by shipping more CSS.

A 14-month migration away from CSS-in-JS with measured gains, feature flags, codemods and the hidden theming work that surprised the team.
Score
8.5
Verdict
Must read
Blog and date
GitHub,
Original length and level
8 min, intermediate
Topics
migrations, frontend performance, design systems, feature flags
Read the original

Context

Primer is the design system behind GitHub UI parts such as buttons and banners. In 2023 Primer used CSS-in-JS. Styles started on the client, which slowed first page loads.

Server-side rendering also suffered, and style updates grew hard as components per page increased.

Architecture

The team moved Primer to CSS Modules, where each component has a CSS file next to its JavaScript. The build bundles the styles into stylesheets that ship with the HTML. No style runtime runs on the client or the server.

A bridge package, @primer/styled-react, wraps migrated components and still accepts the sx prop.

Mechanisms

M1

Per-component migration

For each Primer component, the team added a CSS Modules file that translated the old styles. A feature flag switched the component between old and new styles. Existing visual regression tests checked that the snapshots matched. The rollout went to the internal team, then GitHub staff, then all users.

M2

sx prop removal

The sx prop takes an inline style object, and dynamic objects cost runtime. For each package, engineers moved sx styles into CSS Modules files and changed imports to @primer/react. A VS Code extension migrated one prop at a time, and an internal codemod migrated whole files.

M3

Theme decoupling

GitHub has seven themes, each with a high-contrast variant, switched through styled-components. The theme variables already existed in CSS, so the team removed only the JavaScript theming utilities. They did this behind feature flags over about two months.

Design decisions

No.ChoseInstead ofWhy
D1Adopt CSS ModulesIt removes the style runtime and scopes class names locally. It also allows a gradual migration.
D2Remove sx usage first, behind a bridge packageThe post names sx as the largest remaining bottleneck, and the bridge kept old code working.

Key numbers

  • Server-side render time for a page fell 55% after the Primer migration.
  • Component initialization time on a page fell 25%.
  • The sx prop count peaked at about 7,760.
  • Eight engineers migrated 6,419 props in six months.
  • GitHub ran on 100% CSS Modules in June 2026.

Failures and limits

  • The post reports no breakage, only a few unspecified hiccups in the theme work.
  • The 55% and 25% figures belong to Primer, and gains per page ranged from 1% to 22%.

Lessons you can use

  • Migrate a styling system one component at a time behind feature flags.
  • Reuse existing visual regression tests as the safety net.
  • Keep a compatibility layer so other teams can move on their own schedule.

Glossary

CSS-in-JSA way to write styles in JavaScript so that a library builds them at runtime.
CodemodA script that rewrites source code automatically.