Avoid 5 Common CSS Mistakes for Cleaner Code

Master CSS by Avoiding Common Pitfalls

As developers, we all strive for clean, efficient, and maintainable CSS. However, even seasoned professionals can fall into common traps that lead to bloated code, unexpected behavior, and frustrating debugging sessions. This article will guide you through five frequent CSS “fouls” and provide practical solutions to help you write better CSS.

You will learn how to:

• Eliminate unnecessary CSS declarations that can cause layout issues.
• Leverage default browser behaviors for more adaptable layouts.
• Use minimum and maximum constraints effectively.
• Maintain code organization and avoid style duplication.
• Implement accessible focus states correctly using :focus-visible.
• Choose the right layout tool (Flexbox vs. Grid) for the job.

Prerequisites

• Basic understanding of HTML and CSS.
• Familiarity with browser developer tools.

The Five CSS Fouls and How to Fix Them

1. Useless Declarations: The Overly Prescriptive Width and Height

One of the most common mistakes is declaring width: 100% or height: 250px when it’s not necessary. Browsers have sensible defaults for element sizing. For block-level elements, the default width behavior is to be as wide as its parent container allows (similar to width: auto). Similarly, an element’s default height is to adapt to its content.

Why it’s a problem:

• Overflow issues: Explicitly setting width: 100% or 100vw can cause horizontal overflow, especially when combined with padding or margins, leading to scrollbars. While 100% typically respects the parent’s boundaries, 100vw can be problematic as it doesn’t account for scrollbar widths by default.
• Layout inflexibility: Fixed heights can break layouts when content exceeds the defined height, causing overflow or content clipping.
• Conflicting with layout modules: These explicit declarations can interfere with how Flexbox or Grid items are supposed to behave, leading to unexpected layouts.

The Fix: Embrace Defaults and Use Constraints Wisely

1. Rely on Default Width: For most block-level elements, simply omit the width property. The browser will automatically make it as wide as its container.
2. Use min-height Instead of height: If you need an element to have a minimum size but still grow with its content, use min-height instead of a fixed height. This allows the element to expand beyond the specified minimum if the content requires it. For example: min-height: 350px;.
3. Use max-width Instead of width: If you want to prevent an element from becoming too wide on larger screens but allow it to shrink on smaller screens, use max-width. For instance, max-width: 600px; will ensure the element never exceeds 600px but will shrink down as needed, preventing overflow.

Expert Tip: Understanding the difference between width: auto, width: 100%, and max-width is crucial. width: auto lets the browser decide based on context (often filling the parent). width: 100% forces the element to be exactly the width of its parent, which can cause issues with padding/borders if box-sizing isn’t border-box, and definitely with margins. max-width provides a ceiling while retaining flexibility.

2. Duplicating Styles and Poor Organization

As projects grow, it’s tempting to copy and paste styles for similar components or to “hack” styles directly into unrelated sections of your stylesheet. This leads to bloated CSS, makes updates difficult, and increases the chances of introducing errors.

Why it’s a problem:

• Maintenance nightmares: Updating a style requires finding and changing it in multiple places.
• Increased file size: Duplicated styles bloat your CSS files, slowing down page load times.
• Inconsistent design: Small differences between duplicated components can lead to visual inconsistencies.
• Unclear structure: Styles end up in unexpected places (e.g., utility styles within a reset), making the codebase hard to navigate.

The Fix: Refactor and Structure Your CSS

1. Create Reusable Components: If you have similar components (like link buttons and regular buttons), create a base component with shared styles and use modifier classes or variations for specific differences.
2. Use Utility Classes Sparingly: For highly repeatable, small styles, consider utility classes, but ensure they are well-defined and don’t become a dumping ground for unrelated styles.
3. Organize Your Stylesheet: Group related styles together. Common structures include: resets, base element styles, layout components, UI components, utilities, and themes.
4. Regular Refactoring: Set aside time to review and refactor your CSS. Look for duplicated code, unclear selectors, and overly specific rules. This is an investment that pays off significantly in the long run.

Expert Tip: When starting a new feature or fixing a bug, it’s okay to write code quickly to get it working (quick wins). However, make a note to refactor it later. Schedule time for refactoring, especially before a release or after completing a major feature.

3. Ignoring Accessibility: Using :focus Instead of :focus-visible

When users navigate a website using a keyboard (e.g., with the Tab key), interactive elements like links and buttons receive focus. Browsers provide a visual indicator (often an outline) for these focused elements. However, many developers remove these outlines using outline: none;, often at the request of designers or stakeholders, without providing an alternative.

Why it’s a problem:

• Poor keyboard navigation experience: Users who rely on keyboard navigation have no visual feedback about which element is currently focused, making it difficult or impossible to use the site effectively.
• Exclusion of users: This significantly harms accessibility for users with motor impairments, visual impairments, or those who simply prefer keyboard navigation for efficiency.

The Fix: Use :focus-visible

1. Replace :focus with :focus-visible: Instead of applying focus styles using the :focus pseudo-class, use :focus-visible.
2. Understand the Difference:
   • :focus applies an outline whenever an element receives focus, regardless of the input method (mouse click or keyboard).
   • :focus-visible applies an outline only when the browser determines that the user is likely navigating via keyboard and needs a visible focus indicator. It intelligently hides the outline when focus is achieved via mouse click, preventing unnecessary visual clutter.
3. Provide Clear Focus Styles: Ensure that the styles applied via :focus-visible are clear and noticeable. This might involve changing the background color, adding a border, or using a distinct outline color.

Expert Tip: For most interactive elements like buttons and form inputs, :focus-visible is the superior choice. It provides the necessary accessibility without the unwanted visual noise that :focus can introduce during mouse interactions.

4. Using the Wrong Layout Tool: Flexbox vs. Grid

CSS offers powerful layout tools like Flexbox and Grid. Flexbox is designed for one-dimensional layouts (either a row or a column), excelling at distributing space along a single axis. Grid is designed for two-dimensional layouts (rows and columns simultaneously), making it ideal for complex page structures.

Why it’s a problem:

• Over-reliance on Flexbox: Using Flexbox for complex, two-dimensional layouts often requires hacks or nested structures, leading to complicated CSS that is hard to manage.
• Underutilization of Grid: Conversely, not using Grid for page-level layouts means missing out on its power to create robust and maintainable structures.
• AI-generated code issues: AI tools, trained on vast amounts of code, might default to Flexbox patterns even when Grid would be a more appropriate and simpler solution.

The Fix: Choose the Right Tool for the Job

1. Use Flexbox for Components and Single-Axis Layouts: Ideal for navigation bars, aligning items in a card, distributing items in a form, or laying out elements in a single row or column.
2. Use Grid for Overall Page Layout and Two-Dimensional Structures: Perfect for creating main page layouts, dashboards, image galleries where both rows and columns matter, or any situation requiring precise control over both axes.
3. Learn the Fundamentals of Both: You don’t need to be an expert in every advanced feature. Understanding the core concepts and common patterns for both Flexbox and Grid will enable you to make informed decisions.

Expert Tip: When deciding between Flexbox and Grid, ask yourself: Am I laying out items along a single axis (row OR column)? If yes, Flexbox is likely suitable. Am I laying out items in both rows AND columns simultaneously, or do I need a complex page structure? If yes, Grid is probably the better choice. There’s a helpful video linked in the description for a deeper dive into making this decision.

5. Overly Prescriptive Specificity Wars

This is a broader concept related to the first point but focuses on how specificity can lead to issues. When you write highly specific selectors (e.g., #main-content .sidebar ul li a) or use !important, you create CSS that is difficult to override and maintain. This often stems from trying to force layouts or styles that fight against the natural behavior of HTML elements and CSS properties.

Why it’s a problem:

• Debugging difficulty: It becomes hard to figure out which rule is applying and how to change it.
• Cascading issues: You end up writing even more specific rules to override previous ones, creating a cascade of specificity that is fragile and hard to manage.
• !important abuse: Overusing !important is a sign that your CSS architecture might be flawed, making it nearly impossible to manage styles effectively.

The Fix: Lower Specificity and Work with Defaults

1. Prefer Lower Specificity Selectors: Aim for simple, low-specificity selectors like class names or element selectors where possible.
2. Use Naming Conventions: Adopt a methodology like BEM (Block, Element, Modifier) to create predictable and manageable class names that inherently keep specificity low.
3. Leverage CSS Custom Properties (Variables): Use variables to manage values, making it easier to update styles globally without increasing specificity.
4. Understand Inheritance and the Cascade: Work *with* the cascade and inheritance rules rather than fighting against them. Let elements inherit properties where appropriate, and use them to your advantage.
5. Avoid !important Unless Absolutely Necessary: Reserve !important for very specific, rare cases, such as utility classes that are designed to override everything else, or when dealing with third-party styles you cannot modify.

Expert Tip: The goal is to write CSS that is as simple and understandable as possible. By avoiding unnecessary specificity and embracing default browser behaviors, you create more robust, maintainable, and accessible websites.

Conclusion

Avoiding these common CSS fouls can significantly improve the quality of your code, reduce debugging time, and lead to more performant and accessible web experiences. By understanding how the browser works and choosing the right tools and techniques, you can write CSS that is both powerful and maintainable.

Source: 5 CSS fouls that I see way too often (YouTube)