The Brief and the Codebase

Download the Millworks starter project: millworks.zip

Unzip it, open the folder in VS Code, and launch it with Live Server. You should see a venue website (a music room in western Massachusetts). It mostly works.

Now read the client email:

Hey — we’ve had a few developers work on the site over the years and it’s starting to feel inconsistent. The buttons look different sizes on different pages, and the text spacing feels off. Our last developer mentioned something about an “important” issue she ran into but wasn’t sure how to fix it without breaking something else. Nothing’s broken broken, we just want it to feel more pulled together. Let me know what you’re thinking in terms of scope.

That’s the brief. Before you touch a single line of code, your job is to understand what you’re actually looking at.

Look at the site first, not the code

Open index.html in a browser. Click through all four pages: Home, Events, About, Contact.

You’re not diagnosing anything yet. You’re just looking. Write down what you notice in plain language, the kind of language you’d use explaining the problem to a non-developer friend. Not “there’s a padding discrepancy on the CTA element.” Just: “the button on the contact page is a different size than the one on the events page.”

The client gave you two specific complaints. Do you see them? What else do you notice that they didn’t mention?

Write down everything. Don’t try to explain it. Explanation comes later.

Read the HTML before the CSS

Before you open a stylesheet, open index.html and read it.

HTML is the source of truth for what’s on the page. The CSS might describe something that doesn’t exist anymore. The HTML won’t lie to you.

Look for:

• What class names appear on elements. Are they consistent from page to page?
• Any id="" attributes. Note which ones.
• Any style="" attributes directly on HTML elements. Note where.
• What class names appear on the buttons across all four pages. Are they the same?

Open about.html. Compare the <header> element there to the one in index.html. Look carefully at the class names. Write down what you see.

Open events.html. Look at the event cards. Some of them look slightly different from others. Look at their class names. Note anything that seems inconsistent.

Read the stylesheets

Three CSS files. Open each one and read it. Don’t change anything.

style.css: the original, from 2019. How long is it? Does it have sections? What do the class names look like?

custom.css: a different developer’s work, added around 2021. Does the naming style here feel like the same person wrote it? Note any differences.

fixes.css: before you read a single rule, the filename tells you something. Write down what you think this file is for, based on the name alone. Then read it. Was your guess right?

In fixes.css you’ll see a word that appears many times: !important. You don’t need to know what it does yet. Just write down how many times you see it, and note any comments that look like warnings or explanations.

Look for class names in the CSS that you couldn’t find in any of the HTML files. You’re not sure what to do with these. Just note that they’re there.

Glance at the JavaScript

Open main.js. You don’t need to understand all of it.

Scan for any lines that set a style directly on an element, something like element.style.display = 'block' or element.style.display = 'none'. If you find them, note them. These will come up again.

Note any class names that JavaScript is looking for, anywhere you see querySelector('...') or classList. Write those class names down separately.

Write down what you noticed

Open a new file: notes.md. Two sections.

What I see in the browser: Plain descriptions of visual problems. Don’t use CSS vocabulary. Write what you actually observed: “button on contact page is larger than button on events page.” Nothing more specific than that yet.

What I noticed in the files: Plain descriptions of things that seemed unusual or inconsistent. “There are three CSS files. The third one is called fixes.css and most of its lines contain the word !important.” “Some class names in style.css use hyphens, some in custom.css use capital letters.” “Found a comment that says DO NOT DELETE — Mike with no explanation.” “Some class names in the CSS don’t appear in any of the HTML files.”

Don’t explain any of it. Don’t guess at causes. Just list what you saw.

The scope question

Before you fix anything, you need to tell the client what you’re proposing.

Two directions:

Targeted fixes: address the specific symptoms the client mentioned and stop there. Faster. Less risk. Leaves the underlying problems in place.

Full refactor: rebuild the CSS with a coherent architecture so the problems don’t come back. More work. More value long-term.

Neither is automatically the right call. It depends on the client’s budget and timeline, and whether they plan to keep developing the site.

This series builds toward the full refactor, because that’s what teaches the underlying concepts. But the scope conversation is real professional work. Make a decision, be able to explain your reasoning, and commit to it before you start.

In Chapter 02, you’ll pick up your first item from notes.md (the nav link color that looks different on the about page) and trace it to its cause. That’s where the cascade comes in.