Keeping CSS Maintainable

Every stylesheet starts clean. Maintainable CSS stays that way. This is a checklist to review before you ship, and every month afterwards.

The checklist

1. Selectors are short. One or two classes. No IDs, no long descendant chains. See Avoiding Specificity Problems.
2. No !important except for deliberate utilities and accessibility overrides.
3. Names mean something. Purpose over appearance. See Naming Classes.
4. Values come from variables. No same hex code typed in 20 places.
5. No magic numbers. If margin-top: 37px is there to nudge something into place, find out why. A comment is better than a mystery.
6. Layout uses layout tools. Flexbox and grid, not margins and absolute positions pushing things around.
7. Sizes are flexible. max-width, rem, %, fr. Fixed widths and heights only when a design truly needs them.
8. Components are independent. A card does not rely on being inside .sidebar to look right.
9. Responsive and accessible by default. Visible focus, enough contrast, reduced motion.
10. Dead code is removed. If you comment something out “just in case”, delete it. The version history remembers.

Comment the surprising things

Comments are for why, not for what:

1
2
3
4
5
6

/* Not "make it flex". Instead: */
.nav { display: flex; }

/* The login button must stay inside the 44px touch target
   required by the mobile design, so the padding is bigger than it looks */
.nav .login { padding: 14px 20px; }

Refactor as you go

When you touch a rule, tidy it. Replace a hard-coded color with a variable. Shorten a selector. Rename a vague class. Small steps are easier than a rewrite.

Test in more than one situation

• Narrow phone and wide desktop.
• Browser zoom at 200%.
• Longer text than your design assumed (translations are often 30% longer).
• Keyboard-only navigation.
• Dark mode, if supported.