After a catalogue app moves to CSS Modules, a BookCard rule `img { border-radius: 8px }` rounds every image site-wide and `.card a` restyles links in nested components — what does CSS Modules scoping not protect?
answer
- names, not reach
- element selectors stay global
- descendants cross component lines
- equal specificity, load order
- inheritance and custom properties
basics
~20 sCSS Modules rename class, ID and keyframes names; they do not limit where a rule reaches. Element selectors stay global, descendant selectors match nested components, order between modules follows load order, and inherited values still flow down.
solid answer
~50 sCSS Modules guarantee **unique names**, not **contained effects**. Only class, ID and `@keyframes` names are rewritten, so `img { … }` in a module is a page-wide rule that applies once the module's CSS loads. A local class only fixes where a selector **starts**: `.card a` still matches every link rendered inside a card, including links owned by child components. Two modules' single-class rules on one element tie on specificity, so the **emitted stylesheet order** — driven by imports and chunking — decides, which is why a parent's override class passed down sometimes loses. Inherited properties and custom properties still cascade into children, and `:global` escapes leak by design. The guards: run modules in **pure** mode so selectors without a local class or ID fail, style only elements a component renders through its own classes, and keep overrides inside the owning module.
go deeper
Recall that only class, ID and keyframes names get renamed, so a bare img rule in a module still applies to the whole page.
Explain descendant reach, inheritance and custom properties as normal cascade behaviour that renaming does not touch.
Diagnose cross-module override bugs as equal specificity plus load order, and put guard rails in place: pure mode, class-anchored rules, variants owned by the component.
Judge when renaming is enough and when a codebase needs a real boundary, and set the lint and build rules that keep module files from accumulating page-wide CSS.
## What CSS Modules actually guarantee A CSS Modules transform rewrites **names**: class names, IDs and `@keyframes` names (with the `animation` references to them). Its output is ordinary global CSS. That gives one strong guarantee — two files cannot accidentally share a class name — and nothing else. Every other cascade behaviour is untouched, which is what a team migrating from one global stylesheet discovers. ## The gaps, one by one | Gap | Example in the catalogue app | Why scoping misses it | |---|---|---| | **Element, attribute and universal selectors** | `img { border-radius: 8px }` in BookCard.module.css | only class, ID and keyframes names are rewritten; `img` stays `img` | | **Descendant reach** | `.card a { color: teal }` | the local class anchors the start of the selector; the rest matches any descendant, including a child component's links | | **Order between modules** | a parent passes `styles.compact` to BookCard to shrink its padding | both rules are one class; emitted CSS order decides, and it follows imports and chunks | | **Inheritance** | `.card { color: grey }` | inherited properties flow into every child component regardless of class names | | **Custom properties** | `.card { --accent: teal }` | the PostCSS-based transform leaves custom property names alone, and they inherit | | **Explicit escapes** | `:global(.is-modal-open) …`, `@keyframes :global(spin)` | they opt out on purpose; their names are shared | ## Why the `img` rule is the worst of them A bare element selector in a module is not even anchored to the component. It becomes a page-wide rule the moment the module's CSS is in the page, and because loading follows imports, the bug can appear only on routes that render a BookCard — and persist after navigating away if the stylesheet stays loaded. Fix it by anchoring: `.cover { border-radius: 8px }` on the image the component renders, or `.card img` if every image in the card really should change. ## Why overrides across modules are fragile Suppose `BookCard.module.css` has `.root { padding: 1rem }` and a parent passes its own `.compact { padding: 0.5rem }` through a `className` prop. Both are single classes — equal specificity — so the **later rule in the emitted CSS** wins. That order is decided by which module's CSS was emitted first: import order, shared chunks, and what loaded on a previous route. A generated name is still one class; hashing adds no specificity. Robust options: 1. **Own the variant**: give BookCard a `compact` prop and keep `.compact` inside BookCard.module.css, where source order is under your control. 2. **Use composition** within one file, where order is defined, rather than across files, where the CSS Modules docs call the order undefined. 3. **Raise specificity deliberately** only as a last resort, and document why. ## Guard rails worth adopting - **Pure mode** in the local-by-default transform rejects any selector without at least one local class or ID, so `img { … }` and `:global(.x) { … }` fail the build. Exemptions need a visible `/* cssmodules-pure-ignore */` comment. - **Style what you render, by class**: give the image its own class rather than selecting it by element. - **Keep descendant selectors shallow**: `.card > .title` rather than `.card a`, so child components are not reached by accident. - **Treat `:global` as an audited exception**, with the global part as the anchor and a local class as the target. ## A migration checklist When the catalogue app splits its global stylesheet into `.module.css` files, review each new module for: - bare element, attribute or universal selectors that used to be harmless inside one big file; - descendant selectors deeper than one level, which now cross into child components; - override classes passed between components through props, which depend on emitted order; - properties set on a component root that children inherit, such as `color` or `font-size`; - custom properties defined on a component root, which every descendant can read; - `:global` escapes, each with a reason and a local class as its target. ## Where a different mechanism is the answer When a team needs a **lower boundary** — styles that stop at a child component — or true isolation from page styles, renaming is the wrong tool: native `@scope` limits and shadow DOM exist for that, and choosing between them and build-time hashing is a separate architectural question. CSS Modules remain a naming tool; knowing that is the point interviewers probe.
- How would you stop new page-wide rules from creeping into module files across a large codebase?Run the local-by-default transform in pure mode, which fails the build for any selector without a local class or ID, and allow exceptions only through the visible ignore comment, reviewed like any other suppression.
- Does a hashed class name have higher specificity than a plain one, so module styles win over global ones?No. A generated name is still one class selector. A module rule beats a global rule only through specificity or later emitted order, exactly as two plain classes would.
- Every selector in a module file is scoped to that component.
- A hashed class name carries higher specificity than a plain class.
- Module styles cannot affect a child component's markup.
- Inherited properties stop at a component's module boundary.
- A parent's override class always beats the child module's class.