Clarify component ownership, avoid premature scoping, and migrate global CSS to CSS Modules with a practical decision…
Comprehensive React guides covering hooks, performance optimization, and React 19 features. Includes code examples and prompts to boost your workflow.
No spam. Unsubscribe anytime.
If you had asked me a couple of years ago about CSS Modules, my honest reaction would have been: "Why would anyone choose CSS Modules today?"
Like many React developers, Tailwind CSS and utility-first styling had become my instinctive default for almost every project. Utility classes make styling fast, co-located, and immune to dead-code accumulation.
Then I took over a client frontend with almost 20,000 lines of legacy global CSS.
The client's designer had already begun cleaning up components and establishing consistent visual rules, but the sheer volume of cascading global overrides made touch-ups hazardous. Moving the entire codebase to Tailwind was out of the question—it would have required rewriting every markup file and halting all feature work. We needed a way to break up the stylesheet cleanly and give components isolated boundaries without triggering a risky rewrite.
That brought CSS Modules back into focus—and reminded me of an essential rule:
CSS Modules enforce existing ownership boundaries. Defining those boundaries is separate work.
And that distinction matters.
Large global stylesheets tend to trigger an immediate architectural reaction.
They look risky.
They can be hard to navigate.
They can create specificity problems.
They can make it difficult to know which styles belong to which component.
All of that can be true without meaning the architecture is broken.
A global stylesheet can still contain:
Those things are genuinely global. They belong there even if the stylesheet stays large.
The more useful question is:
Which styles are actually global, and which styles belong to a component but currently live globally?
That is a very different problem.
The frontend I was reviewing used a lot of BEM-style naming.
Something like:
.cp-product-card {}
.cp-product-card__title {}
.cp-product-card__media {}
.cp-product-card--compact {}
BEM does useful work here. It tries to establish ownership through naming.
The problem appears when other parts of the application start reaching into those internals.
For example:
.hero .cp-product-card__title {
color: white;
}
.recipe-feature .cp-product-card__media {
height: 140px;
}
The naming stays structured even as the ownership boundary erodes.
The parent feature knows too much about how ProductCard is implemented internally. That cross-boundary knowledge is the architectural smell, regardless of whether the class is global.
This is where CSS Modules can give you a false sense of progress.
Imagine we take:
.cp-product-card__title {}
.cp-product-card__media {}
and move it into:
ProductCard.module.css
Great. Now the internal selectors are locally scoped. Here's what happens to this:
.hero .cp-product-card__title {
color: white;
}
That selector was expressing a real requirement. The hero wanted a different version of the product card. Once the class becomes locally scoped, the parent can no longer reach into it directly.
Scoping the class removes the mechanism that expressed the requirement. The requirement itself stays.
That is why migrating a highly coupled component into CSS Modules too early can actually make the situation worse.
You need to understand the dependency first.
Before moving a component into a CSS Module, I would classify its external styling dependencies.
Most overrides I encounter fall into a handful of categories.
For example:
.hero .product-card__title {
color: white;
}
may really mean:
<ProductCard tone="inverse" />
The component has a legitimate alternate presentation. The API simply never exposed it. That's a gap in the component's contract.
Sometimes the difference applies to everything inside a section.
For example:
.dark-section .button {}
.dark-section .card {}
.dark-section .heading {}
That may be better expressed through semantic variables:
.darkSection {
--foreground: white;
--surface: #111;
--muted-foreground: #bbb;
}
Now components respond to context, and parents no longer need to manually restyle each one. This is a theme context, distinct from a component variant.
Consider:
.carousel .product-card {
width: 280px;
}
That may be completely fine. The parent owns layout. It is reasonable for a grid, carousel or section to decide:
Turning every parent rule into a prop, like:
<ProductCard width="280px" />
moves layout responsibility into the wrong place.
Not every unusual design needs to become a reusable variant. If something appears once and is genuinely specific to one feature, a local wrapper or composition may be cleaner than expanding a shared component API.
Otherwise you end up with things like:
<ProductCard
variant="homepage-summer-promo-left-column"
/>
That's a prop list built from accumulated one-off exceptions.
Sometimes an override exists because an earlier selector was too strong.
For example:
.page .section .product-card .title {}
followed by:
.homepage .hero .product-card .title {}
At that point, what you're looking at is CSS escalation: each new selector added just to out-rank the last one.
The right answer may simply be to simplify the selectors.
This is surprisingly common.
Large global stylesheets often preserve rules for:
Do not formalize those. Delete them.
Once you understand what a component actually owns, CSS Modules become valuable.
Now you can safely move:
ProductCard.tsx
ProductCard.module.css
and keep internal styles local:
.root {}
.title {}
.media {}
.actions {}
The component can own its intentional states:
.inverse {}
.compact {}
.featured {}
And the public API can expose them explicitly:
<ProductCard
tone="inverse"
density="compact"
/>
At that point the module is reinforcing a boundary that already makes sense.
That is where CSS Modules shine.
The biggest benefit is ownership. Everything else, including shorter CSS, follows from that.
A component stylesheet becomes much easier to reason about when you know:
These styles belong to this component.
You get several useful properties.
You no longer need to globally protect every class name. A prefixed list like this:
.cp-product-card__title {}
.cp-product-card__media {}
.cp-product-card__actions {}
can simplify to this:
.title {}
.media {}
.actions {}
The module provides the namespace.
If .title is truly private to ProductCard, you can change it without worrying that six unrelated pages are depending on it.
That makes component refactoring much less dangerous.
Two unrelated components can both have:
.title {}
without interacting.
This is underrated.
When you see:
ProductCard/
ProductCard.tsx
ProductCard.module.css
the architecture communicates itself. The component's styling location is immediately obvious, without searching through thousands of global lines.
You can absolutely build badly coupled components with CSS Modules.
For example, a component might accept:
<ProductCard
titleClassName={styles.specialTitle}
mediaClassName={styles.smallMedia}
actionClassName={styles.hiddenActions}
/>
The scoping is real, and the parent is still manipulating the child's internals beneath it. Global selectors have simply become prop-based selector injection, carrying the same coupling forward.
The real question is still:
Who should own this decision?
If the child owns it, expose a semantic API. If the parent owns it, let the parent control layout. If it is context, use context. If it is truly one-off, compose locally.
Design-system thinking has to happen regardless of scoping.
Even in a codebase that uses CSS Modules heavily, I would expect some global CSS to remain.
Usually things like:
Design tokens
Theme variables
Font declarations
CSS reset
html/body defaults
Document typography foundations
Global focus treatment
Accessibility helpers
Portal/body coordination
Third-party library overrides
Rare application-wide contracts
The goal: global CSS holds only things that are genuinely global, however many lines that leaves.
That's a far more useful target than counting bytes.
CSS Modules are particularly useful in projects with a strong custom visual identity.
In those projects you often have branded components like:
ProductCard
HealthGoalCard
StoryCard
HeroProductCard
SupplementQuiz
ResourceCard
Their visual behaviour is specific to the product. A local stylesheet next to the component gives that component a clear ownership boundary. Meanwhile, the interaction primitives underneath may come from another layer.
For example:
Product feature
↓
Brand Drawer
↓
Base UI behaviour
while:
Drawer.tsx
Drawer.module.css
owns the brand-specific visuals.
That produces a useful separation:
Interaction behaviour → primitive layer
Visual styling → local component
Global design language → tokens/theme
Layout → parent
Each concern has somewhere obvious to live.
This is probably the most practical lesson.
A project titled:
Convert globals.css to CSS Modules
sets a mechanical goal. It says nothing about whether the architecture improves.
Migrating incrementally, inside the path of real feature work, keeps the goal tied to the architecture. For example:
Component enters production work
↓
inspect external dependencies
↓
classify them
↓
formalize real component contracts
↓
remove unnecessary coupling
↓
move owned styles into CSS Module
↓
validate visual parity
That's slower per component, and safer for the project as a whole. Because you're doing it in the path of real implementation, you're spending time on components that actually matter.
When introducing CSS Modules into an existing application, start with something isolated.
For example, a marketing band that:
Move that first. Establish:
Then move to slightly more complicated components. Only later tackle the shared components with significant external dependencies.
This gives the team a working pattern before the difficult cases appear.
Suppose ProductCard is used everywhere.
Homepage.
Search.
Saved products.
Recommendations.
Recipes.
Product listings.
And each one modifies it slightly differently. That's a poor candidate for a first CSS Module migration.
First build a map of those differences. Maybe you discover that the dozens of overrides actually reduce to:
tone
density
metadata visibility
action presentation
layout context
Now you can design a stable API. Then move the styles. This is much better than translating every existing selector directly into another styling system.
One useful way to judge whether the refactor is working is to ask:
How much does the parent need to know about the child?
Before:
.hero .product-card__title {}
.hero .product-card__media {}
.hero .product-card__actions {}
The parent knows three implementation details.
After:
<ProductCard tone="inverse" density="compact" />
The parent knows two supported concepts. That is an improvement.
The goal here is less cross-component knowledge.
The same principle applies when teams respond to global CSS by moving everything into Tailwind utilities.
Utility classes can be excellent, and a mechanical migration from:
.product-card__title {
...
}
to a long list of classes inside JSX still doesn't automatically improve ownership.
You can still have:
Changing the syntax leaves the architectural question exactly where it was:
Where does this styling decision belong?
Once that's answered, the choice of CSS technology follows easily.
When I consider moving a component into CSS Modules, I would ask:
If not, figure out who does.
If yes, classify why before scoping them away.
If yes, create explicit component contracts.
Use semantic variables where appropriate.
Keep them in the parent.
Remove them.
Now CSS Modules are probably a good fit.
CSS Modules matter most for the architectural statement they make:
This styling belongs to this component.
Generating unique class names is a useful side effect. Once component contracts are explicit, that statement becomes a genuinely powerful constraint.
The mistake is applying that constraint before understanding the system.
So when I inherit a large global stylesheet now, the first question is:
What does this CSS tell us about the actual ownership boundaries in the frontend?
Speed comes later. Once those boundaries are understood, the migration gets both easier and more valuable.
The simplest version is:
Define ownership first. Scope it second.
CSS Modules do their real work once boundaries are already deliberate. The scoping just makes them permanent.