CSS Architecture Review

The Problem

CSS grows into an unmaintainable swamp faster than any other language. Developers override specificity with !important instead of fixing the cascade. Hardcoded pixel values and hex colors scatter across hundreds of files, making theme changes impossible. Mobile styles are an afterthought bolted on with max-width queries. The result: a stylesheet where nobody dares to delete a rule because they do not know what it affects, and every new feature requires increasingly bizarre selectors to win the specificity war.

The Prompt

Review the following CSS architecture. Act as a design systems engineer evaluating for scalability, consistency, and maintainability.

METHODOLOGY: [e.g., BEM, Tailwind, CSS Modules, styled-components, vanilla CSS]
DESIGN SYSTEM: [e.g., custom tokens, Tailwind config, Material UI theme]

CSS/STYLE CODE:
[paste your stylesheets, component styles, or Tailwind config]

HTML/COMPONENT CODE (for context):
[paste relevant markup]

Evaluate across these dimensions:

1. **Specificity Management**
   - Are there !important declarations? Why?
   - Are selectors reasonably flat (max 2-3 levels)?
   - Are IDs used for styling (high specificity, hard to override)?
   - Is the cascade predictable or a specificity war?

2. **Design Token Compliance**
   - Are colors, spacing, typography, and shadows using tokens/variables?
   - Are there hardcoded hex values, pixel sizes, or raw rgba values?
   - Is the token naming semantic (--color-primary, not --blue-500)?
   - Can the theme be switched by changing token values alone?

3. **Responsive Strategy**
   - Is mobile-first approach used (min-width media queries)?
   - Are breakpoints consistent and using design tokens?
   - Do layouts use modern techniques (Grid, Flexbox) not floats?
   - Are touch targets at least 44x44px on mobile?
   - Does content reflow gracefully at all viewport sizes?

4. **Layout Patterns**
   - Are CSS Grid and Flexbox used appropriately (Grid for 2D, Flex for 1D)?
   - Are there unnecessary nesting levels (div > div > div > div)?
   - Are layout utilities reusable or copy-pasted per component?

5. **Performance**
   - Are expensive selectors avoided (universal *, deep descendants)?
   - Is unused CSS identified and removable?
   - Are animations using transform/opacity (GPU-accelerated)?
   - Are large box-shadows or filters used on frequently re-rendered elements?

6. **Consistency**
   - Is the naming convention followed throughout (BEM, utility, component)?
   - Are similar components styled consistently?
   - Is there dead/duplicate CSS that can be consolidated?

For each issue, provide:
- **Location**: File and selector
- **Severity**: broken (visual bug) / debt (maintainability) / inconsistent / optimization
- **Problem**: What makes this CSS problematic
- **Fix**: Corrected CSS with explanation

Example Output

## CSS Architecture Review: 5 issues found

### Debt: Hardcoded Colors Throughout
Location: 23 files contain raw hex values like #3b82f6, #1f2937
Problem: Theme change requires finding and replacing every instance. Dark mode impossible.
Fix: Define tokens and replace:
  :root { --color-primary: #3b82f6; --color-text: #1f2937; }
  /* Before */ color: #3b82f6;
  /* After */  color: var(--color-primary);

### Broken: Desktop-First Media Queries
Location: src/styles/header.css
Code: @media (max-width: 768px) { ... } — overrides stack up, mobile styles fight desktop.
Fix: Flip to mobile-first:
  /* Mobile base styles */
  .nav { flex-direction: column; }
  /* Desktop enhancement */
  @media (min-width: 768px) { .nav { flex-direction: row; } }

### Debt: Specificity War with !important
Location: src/components/Button.css:12
Code: `.btn-primary { color: white !important; }` — overrides a .card .btn rule
Fix: Flatten both selectors instead of escalating specificity.

When to Use

Run this when reviewing CSS PRs, setting up a design system, or when styles feel increasingly difficult to change. Essential before migrating styling approaches (e.g., from global CSS to CSS Modules or Tailwind). Use it to audit CSS debt that accumulated during rapid prototyping.

Pro Tips

• Include the HTML structure — CSS issues often stem from HTML structure. A div-soup forces complex selectors that a semantic structure would not need.
• Ask for a token extraction plan — follow up with “Extract all hardcoded values into a design token system with a migration script.”
• Audit with scope — for large projects, review one page or component group at a time rather than the entire stylesheet.