Anurag’s Read

Styling Linear for the future with StyleX.

The post shows how a team moved a whole React app between styling systems with a codemod, progress tracking and lint rules. The selection criteria and the checks that stop a relapse apply to other large migrations.
Score
8.1
Verdict
Worth reading
Blog and date
Linear,
Original length and level
10 min, intermediate
Topics
migrations, css-in-js, frontend performance, tooling
Read the original

Context

Linear moved its React apps from styled-components to StyleX in more than 1,000 PRs. Styled-components let code restyle a component from far away, so contracts stayed implicit. Runtime style injection cost render time, and a regression appeared after the React 18 upgrade.

The library had also entered maintenance mode.

Architecture

The team first defined shared StyleX variables, constants, and primitives. A deterministic codemod converted components, leaf first. Scoped agents extended the codemod and fixed edge cases.

Both systems ran together while product work continued. Oxlint rules and a type aware repo checker enforced the new rules.

Mechanisms

M1

Enforcement

Oxlint custom rules run per file and check token use and props that overwrite generated StyleX output. A type aware checker traces components, imports, and styles across files. It finds styles dropped by wrappers and polymorphic components.

M2

Adoption tracking

A dev toolbar counter showed the styled-components CSS rules on the page. A weekly graph tracked the share of files, and a bot flagged new styled-components in PRs.

M3

Theme system

Themes come from a base color, an accent color, and a contrast value. The system derives more than 100 color variables in LCH color space. A nested ThemeProvider injects one CSS rule per theme, scoped to its subtree.

Design decisions

No.ChoseInstead ofWhy
D1StyleX with colocated styles and a small APIvanilla-extractThe author found its API more fragmented, and its separate style files did not fit the team workflow.
D2A constrained atomic style systemThe open styled-components APIIt makes styling at a distance hard and gives deterministic precedence.

Key numbers

  • Files using styled-components went from 100% on March 8, 2026 to 0% on August 6.
  • Main thread CPU work fell 20 to 35% on view heavy pages.
  • Injected CSS rules per navigation fell from hundreds to zero.

Failures and limits

  • The migration took much longer than expected.
  • Early agent output looked right but was wrong.
  • Agents could not check visual changes such as hover states, so manual testing was needed.

Lessons you can use

  • Build the shared foundation before you run a codemod.
  • Migrate leaf components first to limit cascade effects.
  • Turn each rule into a lint check.

Glossary

CodemodA script that rewrites source code in bulk.
LCHA color space with lightness, chroma, and hue values.