The target was a legacy client CSS file: about 1,200 lines of hand-written Sass from before Tailwind was standard at Ideebv. It defined 47 component classes, 12 utility classes that duplicated Tailwind defaults, and a section of commented-out gradients from a 2021 rebrand.
I fed the whole thing to Claude with a single prompt:
“Refactor this to Tailwind v3 utility classes where possible, preserve the custom properties, and flag anything that looks dead.”
What came back was a neatly formatted diff that looked reasonable at first glance. The real work started after that, going line by line and deciding what to accept, what to change, and what to reject.
The audit took 45 minutes: about 20 minutes to get a usable diff, and 25 minutes to verify the context and consequences. The file ended up cleaner. The interesting part is how that happened.
The safest chunk was spacing. The original Sass was full of declarations like:
.card {
margin-top: 24px;
padding: 0 16px;
}
Claude systematically mapped these to Tailwind utilities:
margin-top: 24px;
became mt-6
padding: 0 16px;
became px-4
It also correctly identified that the client’s spacing scale was already on a 4 px base, so 4 px increments lined up with Tailwind’s default spacing scale. In total it caught 89 instances that were exact, lossless translations from raw values to Tailwind classes.
I accepted these without modification. They were pure syntax transformations: no layout changes, no semantic changes, no new assumptions about the design system. Just shorter, more consistent code.
Colors were where “looks right” and “is right” diverged.
The original Sass used custom properties like:
.btn-primary {
color: var(--brand-primary);
background-color: var(--brand-primary);
}
Claude suggested converting these to Tailwind’s default color utilities:
color: var(--brand-primary);
→ text-blue-600
background-color: var(--brand-primary);
→ bg-blue-600
The pattern was sane: replace custom color declarations with semantic Tailwind classes. The problem was the data behind it. This project has a custom tailwind.config.js
that maps a brand
color token to a specific hex value that is not Tailwind’s default blue.
The AI had no access to that config. It guessed. The guess was wrong.
I kept the structural idea but changed the actual classes to:
text-brand
instead of text-blue-600
bg-brand
instead of bg-blue-600
So the refactor went in two steps:
On paper that looks like a small edit. In practice this is the line between “AI refactored my CSS” and “AI suggested a template, and I refactored my CSS using it.” The syntax was automated. The semantics still came from the project’s existing design system.
One component used a CSS Grid setup with subgrid
for alignment. The idea was that nested cards should align their internal rows across columns, so when content varied in length, the visual grid still lined up. The key line was:
grid-template-rows: subgrid;
Tailwind does not yet support subgrid
natively, and Claude did not recognise why it was there. It proposed replacing the whole grid with a simpler layout:
grid-cols-4
for the outer gridOn real content, that would have broken as soon as one card had longer text than the others. The entire point of the original subgrid
setup was to avoid exactly that failure mode.
I rejected the suggestion and kept the original CSS grid declaration. I also added a comment to make the constraint explicit:
/* Using subgrid to align card rows across columns.
Tailwind does not support this yet; do not replace with grid-cols-* or flex.
*/
This was the first place where the cost of verification showed up clearly. The AI could rewrite the layout syntax, but it could not see the layout behaviour or the design intent. It saw an opportunity to use Tailwind utilities; it did not see the trade-off it was making.
The file also contained ::before
pseudo-elements used for decorative-looking borders. Claude flagged them as “likely unnecessary visual noise” and suggested removing them to simplify the CSS.
What was not in the file was the reason they existed. Those pseudo-elements were part of a specific accessibility requirement for the client’s WCAG 2.2 compliance audit. They provided a visible focus indicator for keyboard navigation. No pseudo-element, no visible focus ring. No visible focus ring, no compliance.
The AI saw CSS. It did not see the legal and accessibility constraints behind it.
I rejected the removal and added another explicit comment:
/* ::before used for WCAG 2.2 focus indicator.
Required for accessibility audit. Do not remove.
*/
This is where a “helpful cleanup” could have turned into an expensive regression. Not because the model was malicious, but because it had no way to know which parts of the file were bound to requirements that lived in tickets, audits and contracts, not in code.
On paper, the numbers looked like this:
The AI saved me the manual typing of 89 Tailwind spacing replacements. It also tried to “help” with three structural changes: color tokens, grid layout, and focus indicators. All three needed correction or rejection because they depended on project context the model could not see.
The net result was a cleaner file, fewer one-off spacing declarations, and a bit more documentation around the tricky bits. That was not AI magically refactoring a legacy stylesheet.
AI refactored CSS syntax. A human still had to refactor CSS meaning.