General Assembly logo

Lab 13: Refactoring Modular CSS Architecture

Introduction

In earlier labs, you built functional page layouts using traditional CSS rules that evolved organically as features were added. While these styles work, they often contain duplication, inconsistent naming, and tightly coupled rules that make long-term maintenance difficult.

In this lab, you’ll refactor an existing stylesheet into a modular, scalable CSS architecture using CSS variables, component-based organization, and AI-assisted code review. You’ll evaluate maintainability, identify redundancies, and apply improvements that make the codebase easier to extend and reason about.

Rather than writing styles from scratch, this lab mirrors a real-world scenario: inheriting a working but messy codebase and making it production-ready.

Learning Objectives

By the end of this lab, you’ll be able to:

  • Identify maintainability issues in existing CSS
  • Refactor styles using CSS custom properties (variables)
  • Organize CSS into reusable, component-focused modules
  • Reduce duplication and overly specific selectors
  • Use AI tools to assess CSS quality and recommend improvements
  • Justify architectural decisions for scalability and clarity
  • Compare “before” and “after” CSS in terms of readability and extensibility

Getting Started

Prerequisites

Before beginning this lab, ensure you have:

  • Completed previous labs on HTML layout and basic CSS
  • Familiarity with:
    • CSS selectors and specificity
    • Flexbox or Grid
    • Class-based styling
  • Basic understanding of design tokens (colors, spacing, typography)
  • A modern browser with DevTools
  • Access to an AI assistant (e.g., ChatGPT, Copilot, Claude)

Setup Instructions

  1. Download or clone the lab repository
  2. Navigate to the lab directory:
cd lab4_2_refactoring_modular_css
  1. Open index.html in your browser
  2. Open the project folder in your code editor

Lab Structure

This lab contains the following files:

  • index.html – A small multi-section webpage
  • styles.css – The original, unrefactored CSS
  • styles-refactored.css – Target file for your refactor
  • README.md – Lab instructions (this document)

Exercise Overview

You are given a working webpage styled with a single, flat CSS file that has grown over time. It includes:

  • Hardcoded colors and spacing values
  • Repeated button and card styles
  • Inconsistent naming conventions
  • Overly specific selectors
  • Limited reuse across components

Your task is to refactor the CSS without changing the HTML or visual appearance.

You will:

  1. Audit the existing CSS
  2. Extract shared values into CSS variables
  3. Reorganize styles into component-like sections
  4. Remove redundancy and simplify selectors
  5. Use AI to critique and improve your architecture
  6. Reflect on maintainability improvements

How to Work Through the Lab

Step 1: CSS Audit

  • Open styles.css

  • Scan for:

    • Repeated color values
    • Repeated padding/margin values
    • Similar button or card rules
    • Deep or overly specific selectors

Reflection Prompt:

  • Which parts of the CSS feel hardest to change?
  • Where do you see duplication?

Step 2 - Introduce CSS Variables

In styles-refactored.css:

  • Create a :root section

  • Extract common values:

    • Colors
    • Font sizes
    • Spacing units
    • Border radius values
:root {
  --color-primary: #2a7ae2;
  --color-secondary: #f5f7fa;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --radius-md: 6px;
}

Replace hardcoded values throughout the file with variables.

Step 3 - Component-Based Organization

Reorganize the CSS into logical sections using comments:

/* ===== Base Styles ===== */
/* ===== Layout ===== */
/* ===== Components: Buttons ===== */
/* ===== Components: Cards ===== */
/* ===== Utilities ===== */
  • Group related rules together
  • Normalize naming conventions
  • Reduce selector specificity where possible

Step 4 - AI-Assisted Review

Use an AI tool to review your refactored CSS.

Suggested Prompt:

“Review this CSS for maintainability and scalability. Identify redundancies, specificity issues, and architectural improvements. Assume this project will grow to 20+ components.”

Incorporate at least two AI-suggested improvements, such as:

  • Further variable extraction
  • Utility class suggestions
  • Naming consistency
  • Selector simplification

Document what you changed and why.

Step 5: Comparison & Reflection (10 minutes)

Compare styles.css and styles-refactored.css.

Answer the following:

  • What changes would be easiest now that were hard before?
  • How does variable usage improve team collaboration?
  • What tradeoffs exist with more abstraction?
  • How did AI feedback differ from your own assessment?

Tips for Success

  • Refactor incrementally—don’t rewrite everything at once
  • Prefer fewer, simpler selectors over deeply nested ones
  • Treat CSS variables as design tokens oversimple constants
  • AI is a reviewer, not an authority—use judgment
  • If something feels clearer to read, that’s a win

Common Issues and Troubleshooting

Issue: Styles break after refactoring Solution: Verify variable names and fallback values

Issue: Too many variables Solution: Only extract values that repeat or define design intent

Issue: AI suggests changing HTML Solution: Ignore—HTML changes are out of scope for this lab

Issue: Unsure how far to refactor Solution: Optimize for readability and future change, not perfection

Lab Workflow Summary

  1. Audit existing CSS ↓
  2. Identify duplication and pain points ↓
  3. Extract CSS variables ↓
  4. Reorganize styles by responsibility ↓
  5. Reduce specificity and redundancy ↓
  6. Use AI for architectural feedback ↓
  7. Apply improvements ↓
  8. Reflect on maintainability gains

Key Takeaways

  • Clean CSS is about architecture, not just syntax
  • Variables turn styling into a system
  • Component thinking applies even without frameworks
  • AI can accelerate reviews—but human judgment matters