Architecting a themeable React component library

What's really being asked

This probes React architecture: how to distribute theme data without prop drilling and where Context helps versus hurts performance. A senior answer pairs Context with CSS variables.

The full answer

Expose a ThemeProvider component that consumers wrap their app in, passing a theme object of tokens. Internally it places that object into a React Context, and components read it through a useTheme hook. This avoids drilling theme props through every layer. For performance and SSR friendliness, have the provider also write the tokens as CSS custom properties on a wrapper element, so most styling reads from CSS rather than re-rendering React on theme changes. Memoize the context value so its identity is stable, and keep the theme relatively static. Default to a built-in theme when no provider is present so the library works out of the box.

The mistakes people make

Prop drilling the theme through every component, which is unmaintainable. Putting frequently changing state in the same Context, causing every consumer to re-render. Forcing consumers to import internal context objects directly instead of a clean hook.

What usually comes next

How do you avoid re-rendering all consumers when the theme changes? Why combine Context with CSS variables? How do you support nested providers for sub-sections with different themes?

A concrete example

You export ThemeProvider and a useTheme hook. The provider does const value = useMemo(() => theme, [theme]) and renders a div whose inline style sets --color-primary and friends from the theme, then wraps children in context. A Button uses var(--color-primary) in its CSS and only calls useTheme for logic, so swapping themes updates CSS variables instantly while React re-renders stay minimal.