Catalypt LogoCatalypt.ai

Industry Focus

Developer Options

Resources

Back to Blog

I Let AI Refactor Our CSS. The Design Team Still Won't Talk to Me

March 2, 2024 Josh Butler Technical

"Our CSS is a mess. Let's have AI clean it up!" It seemed so logical. 2000 lines of legacy CSS, full of !important declarations and magic numbers. The AI would organize it, remove duplicates, and make it maintainable.

Three hours later, our lead designer was in my office asking why all the buttons were different sizes and nothing aligned to the grid anymore. The AI had been very helpful. Too helpful.

The Original Sin

Our CSS was admittedly terrible:

.header {
  padding: 13px 24px 11px 24px !important;
  margin-top: -2px; /* Don't ask */
}

.btn-primary {
  height: 38px;
  line-height: 38px; /* Fixes weird alignment issue */
}

.btn-secondary {
  height: 36px; /* Designer insisted this looks better */
  line-height: 34px; /* ¯_(ツ)_/¯ */
}

The AI saw inconsistency. It saw opportunities for optimization. It saw a chance to help.

The "Improvements" Begin

AI's First Helpful Change: Standardizing Spacing

/* AI: "I'll use a consistent 8px grid system!' */

.header {
  padding: 16px 24px; /* Normalized to grid */
}

.btn-primary,
.btn-secondary {
  height: 40px; /* Standardized button height */
  line-height: 40px; /* Consistent line height */
}

Looks cleaner, right? Except:

  • The header now overlapped the navigation
  • All buttons were 2-4px taller, breaking every. single. layout.
  • Forms no longer aligned because input heights didn't change

The Color "Optimization"

The AI noticed we had "redundant" colors:

/* Original */
--primary-blue: #0066CC;
--button-blue: #0067CD;
--link-blue: #0066CE;
--header-blue: #0065CB;

/* AI "optimization" */
--primary-blue: #0066CC; /* Consolidated all blues */

"They're basically the same color!" - The AI, colorblind apparently.

The designer: "Those are COMPLETELY different blues for COMPLETELY different purposes! The button blue has more saturation for better contrast! The link blue is specifically chosen for accessibility!"

Me: "They look the same to me..."

Designer: *death stare*

The Z-Index Disaster

Our z-indexes were a war crime:

.modal { z-index: 9999; }
.dropdown { z-index: 99999; }
.tooltip { z-index: 999999; }
.nuclear-option { z-index: 2147483647; } /* yes, really */

AI's solution:

/* AI: "I'll create a logical z-index system!' */
.layer-1 { z-index: 100; }
.layer-2 { z-index: 200; }
.layer-3 { z-index: 300; }
.layer-4 { z-index: 400; }

Beautiful! Organized! Completely broken! Turns out, those ridiculous z-indexes were battling third-party component z-indexes. Now our modals appeared behind ads.

The Great Flexbox Migration

The AI decided to modernize our layouts:

/* Original - worked since IE6 */
.container {
  display: table;
  width: 100%;
}
.col {
  display: table-cell;
  vertical-align: top;
}

/* AI "modernization" */
.container {
  display: flex;
  width: 100%;
}
.col {
  flex: 1;
}

Except:

  • Table-cell had equal height columns by default
  • Flex doesn't
  • Every two-column layout in the app broke
  • The AI didn't add align-items: stretch

The Media Query Massacre

We had messy breakpoints:

@media (max-width: 1024px) { }
@media (max-width: 1023px) { }
@media (max-width: 768px) { }
@media (max-width: 767px) { }

AI consolidated them:

/* AI: "Simplified to standard breakpoints" */
@media (max-width: 1024px) { }
@media (max-width: 768px) { }

Those 1px differences? They were preventing double-application of styles. Now tablets got both desktop AND tablet styles. Everything was bold, large, and broken.

The Utility Class Genocide

The AI found our utility classes "redundant":

/* Original */
.mt-10 { margin-top: 10px; }
.mt-11 { margin-top: 11px; }
.mt-12 { margin-top: 12px; }
.mt-13 { margin-top: 13px; }

/* AI "improvement" */
.mt-sm { margin-top: 8px; }
.mt-md { margin-top: 16px; }
.mt-lg { margin-top: 24px; }

Designer: "That 13px margin is EXACTLY what we need for optical alignment!"
AI: "Best I can do is 16px"
Designer: *quits*

The Specificity Nightmare

Our CSS had specificity problems. The AI made them worse:

/* Original sin */
#header .nav .menu-item a.active { color: blue; }

/* AI "fix" */
.navigation-link-active { color: blue; }

/* Surprise! The old rule still wins! */

Now we had clean class names that did nothing because the old specific selectors still won.

The Rollback

Git log from that day:

3:00 PM - "AI-powered CSS refactoring"
3:15 PM - "Fix button heights"
3:22 PM - "Fix more button heights"
3:31 PM - "Fix header overlap"
3:45 PM - "Restore original colors"
4:02 PM - "Fix z-index issues"
4:20 PM - "Fix flexbox layouts"
4:35 PM - "Fix everything"
4:47 PM - "Revert 'AI-powered CSS refactoring'"
4:48 PM - "I'm sorry'

What AI Doesn't Understand About CSS

  1. Magic numbers often have reasons - That 13px is for optical alignment
  2. Inconsistency might be intentional - Different buttons SHOULD be different sizes
  3. Legacy CSS is load-bearing - Remove it and everything collapses
  4. Designers see differences developers don't - #0066CC vs #0067CD matters
  5. Specificity wars have casualties - You can't just simplify selectors

The Right Way to AI-Assist CSS

After the disaster, here's what actually works:

1. Analysis Only First

"Analyze this CSS and identify:
- Duplicate declarations
- Conflicting rules
- Unused selectors
- Performance issues

Do NOT suggest fixes yet. Just report findings."

2. Targeted Refactoring

"Refactor ONLY the .header component styles.
Preserve all existing values.
Only reorganize and remove true duplicates."

3. Designer Approval Required

/* Before AI touches anything visual */
1. Document all magic numbers
2. Get designer sign-off on standardization
3. Test on all breakpoints
4. Have rollback ready

The Lessons

  • CSS that looks messy often has hidden logic
  • AI doesn't understand visual design
  • Standardization isn't always improvement
  • Designers hold grudges
  • Always work on a branch

Six Months Later

We did eventually refactor our CSS. With:

  • Designer involved at every step
  • One component at a time
  • Visual regression testing
  • AI for analysis only
  • Humans making the decisions

The designer still brings up the "button incident" at every retrospective.

Never let AI refactor your CSS unsupervised. It's like letting a very logical alien reorganize your house - technically correct, practically unusable, and guaranteed to upset everyone who actually lives there. CSS isn't just code; it's the result of a thousand micro-negotiations between designers and developers. AI doesn't know about the negotiations.

Get Started