Iterating on CSS with Claude without losing the thread

Why CSS iteration tends to drift more than other code changes

A series of small CSS tweaks, each individually reasonable, can leave a stylesheet in a meaningfully worse state than any single change would suggest — a !important added to force a one-off override, then another to override that override, then a hardcoded value that quietly diverges from what the rest of the system uses. CSS's cascading, global-by-default nature makes this kind of accumulation easier to fall into than with most other code, because a local-feeling fix here can have effects elsewhere that aren't obvious from looking at just the change itself.

State the actual constraint, not just the visual symptom

"This still looks wrong" is a description of a symptom, not a specification Claude — or any collaborator — can act on precisely. Describing the actual constraint that's being violated — this element needs a fixed aspect ratio, this text needs to stay legible against a variable background, this layout needs to survive a specific narrow viewport — produces a far more targeted fix than describing the visual outcome you don't want and leaving the cause to be inferred. The more precisely you can name what's actually broken, the less likely the fix is to be a workaround that happens to make the symptom go away without addressing the underlying cause.

Resist the first fix that makes the symptom disappear

CSS has an unusually large space of "solutions" that technically make a symptom go away without addressing what actually caused it — a hardcoded pixel value that happens to fix today's content length but breaks the moment the content changes, an !important that wins the specificity fight without asking why the fight existed in the first place. When a fix appears, it's worth asking whether it addresses the actual cause or just suppresses the current symptom, because the second kind tends to resurface, usually in a less obvious form, a few iterations later.

Keeping a running record of intentional overrides

In any codebase where CSS gets iterated on repeatedly, a small number of overrides are genuinely intentional and necessary — a third-party component that needs a targeted exception, a legacy constraint that can't be immediately resolved. The problem isn't that these exist; it's that without a record of which ones were deliberate, every future iteration has to re-derive whether an existing override is safe to remove or was carefully placed for a reason. A short comment at the point of any deliberate override, stating why it's there, saves the next iteration — whether that's you, a teammate, or Claude working on the same file later — from having to reverse-engineer intent from the code alone.

Reviewing the diff, not just the rendered result

A CSS change that produces the correct visual result can still be a worse change than the one it replaced — introducing new specificity conflicts, duplicating a rule that already existed elsewhere, or overriding something in a way that'll conflict with the next change to the same area. Reviewing the actual diff, not just checking that the page looks right, catches this category of regression before it becomes the next iteration's problem to untangle.

When starting over on a section beats continuing to patch it

If a specific area of CSS has been patched repeatedly and each new fix is getting harder to reason about than the last, that's usually a signal the underlying structure needs rethinking rather than another targeted patch — asking for a fresh approach to that specific section, rather than one more incremental fix layered onto an already-tangled one, is often both faster and produces a more maintainable result than continuing to iterate on a structure that's already showing strain.

See common CSS mistakes Claude still makes for specific patterns worth watching for during review, beyond the general iteration discipline covered here.