The bug is a misaligned icon. The diff also renames .wrap to .container, .btn to .button, and .iconLeft to .iconStart “for clarity.” Every snapshot, every test id that happened to use a class, and every overlapping PR now conflicts. The layout fix is two lines.
I’ve started telling agents to leave existing CSS Module (and BEM, and CSS-in-JS hashed) class names alone unless the ticket is a rename. A bugfix is not a vocabulary exercise.
Why the rename sneaks in
The model likes tidier names. It will “improve consistency” in any file it already opened. CSS Modules make that look safe: the name is local, TypeScript will catch broken imports. What TypeScript will not catch is a snapshot, a visual test, a documented class in a README, or a sibling branch that edited the same module.
The churn also hides the real change. Reviewers scan a 40-line class rename and miss the gap that actually fixes the icon.
This is the same discipline as “don’t clean up unrelated imports in a UI bugfix,” applied to class identifiers.
A simple naming policy
- Bugfixes and features reuse the current class names
- Renames are their own PR, with no behavior change
-
New classes are fine — add
.iconSlot, do not rename.wrapto make room - Do not “align” names with a different component in passing
If the team is mid-migration from .btn to .button, point the agent at that migration branch or do the rename there, not in a visual bug ticket.
What to put in the prompt
Do not rename existing CSS Module class names (or the imported identifiers) in this PR.
You may add a new class.
If a name is genuinely wrong, leave a comment and we will do a rename-only follow-up.
Keep the diff limited to the layout bug.
In review, if the class map moved and the computed styles barely did, send it back.
Selectors in tests are the other casualty. If a Playwright or Testing Library query used a class because no test id existed, a “clarity” rename breaks the test without changing the product. The right follow-up is a test id, in a small PR, not a rename mixed into the layout fix.
The same restraint applies to styled-component display names and CSS-in-JS keys that appear in snapshots. If the agent rewrites those while fixing gap, you will review typography instead of the icon.
Global class names in CSS Modules (:global(.legacy)) are even more dangerous to rename in passing, because they may be referenced from another package or a server-rendered shell. If the agent touches a :global selector in a layout bugfix, treat that as a crossing of the rename boundary and send the PR back.
Reject / send back
Reject
- A drive-by rename of three or more classes in a bugfix
- “Consistency with another file” as the reason inside a layout PR
- A rename that forces snapshot and translation updates with no behavior change, mixed into a functional fix
Accept
- A new class for a new slot
- A rename-only PR, isolated and mechanical
- The two-line layout fix that leaves the identifiers alone
Top comments (0)