Organize CSS So You Can Find Things Later

A 2,000-line styles.css with no sections is a trap. You will re-declare .btn three times and wonder which one wins. Organisation is not bureaucracy. It is how you find the rule you need before the cascade finds you.

A simple split that scales past one page

1. Base — reset/box-sizing, typography, links, forms defaults.
2. Layout — page shells, grids, headers, footers.
3. Components — .card, .btn, .field, .site-nav.
4. Utilities — rare helpers (.u-sr-only, .u-hidden) if you need them.
5. Tokens — :root custom properties first.

One file with clear comment banners is fine at this level. Multiple files come when the team or the build step justifies them.

/* === tokens === */
:root { --color-brand: #034bff; }

/* === base === */
*, *::before, *::after { box-sizing: border-box; }

/* === layout === */
.page { display: grid; ... }

/* === components === */
.card { ... }
.btn { ... }

Names that mean something

• .card beats .box1.
• .site-nav beats .n.
• State: .is-open, .field--error — pick one pattern.

If a class describes a page (homeSidebarLeft), it will not survive a redesign. Describe the role.

Comments that help the next edit

/* Sticky header height is also used in scroll-padding-top (see base). */
.site-header { position: sticky; top: 0; height: 3.5rem; }

Comment the why, not the what. /* set colour to blue */ wastes space. /* matches brand token; do not hard-code hex here */ saves a future mistake.

Common mistakes

• Alphabetical classes with no grouping. Related rules live far apart.
• !important to "win" across sections. Fix order and specificity instead.
• Dead CSS left forever. If you delete a component from HTML, delete its rules.

A naming smoke test

Ask: “If I see .x7 in HTML, can I guess what it styles?” If not, rename it. Short is good. Cryptic is not.

Specificity budget

Prefer .card over .page .content .wrapper .card. Deep chains make overrides painful. If you need to win a fight, fix the conflicting rule or the order of the stylesheet sections — do not start a !important collection.

Dead code pass

When you delete a section from HTML, search the class names in CSS and remove orphans. Dead rules confuse the next reader into thinking they still matter. A five-minute pass after each feature keeps the file honest.

What happens if you skip this

Every change feels risky. You duplicate rules because you cannot find the original. The cascade looks random. It is not. Your file is.

Try it

Open your current stylesheet. Add three section banners. Move one duplicated button rule into .btn. Delete the orphans. Reload.

If you cannot find the rule that styles the checkout button in under a minute, what will you do under a deadline?