KodingKaro
CSS · Advanced · CSS Architecture and Maintainability

Naming conventions and stylesheet refactoring

Naming systems help teams communicate, but the best convention is one that fits the codebase and is applied consistently.

✓ What you will learn in this topic

  • Explain the key idea: Adopt one useful naming approach and refactor without changing behavior accidentally.
  • Apply the concept: The base component, its title element, and its featured modifier have distinct, readable responsibilities.
  • Avoid this common mistake:

Concept explanation

Conventions such as block-element-modifier naming can make ownership and variants explicit. Other projects may use scoped component styles or utility classes. Do not mix systems casually: unclear ownership and duplicated rules create maintenance cost.

When refactoring, preserve behavior with small steps: find the active rule, move it into the intended layer or component, then remove the obsolete duplicate. Avoid broad find-and-replace changes without checking resulting selectors.

Syntax

A CSS rule has a selector followed by declarations. Each declaration is a property and a value; the braces group the declarations that apply to matching elements.

.card { padding: 1rem; }
.card__title { margin: 0; }
.card--featured { border-color: #2563eb; }

Example 1: a small page element

Use this HTML as the target and place the CSS in a stylesheet linked to the page, or inside a <style> element while experimenting.

<main class="demo card-grid course-grid dashboard-panel course-card-list dashboard-grid card-layout"><h2>Learning card</h2><p>Clear styles make this information easier to scan.</p><nav class="site-nav"><a href="/learn">Courses</a></nav><label class="form-field"><span>Email</span><input type="email" aria-invalid="true"></label><article class="card course-card dashboard-card theme-dark"><span class="badge status">New</span><div class="course-card__image"></div><h2 class="course-card__title card__title">Course update</h2><p class="status">New lessons are available this week.</p><a href="/learn" aria-current="page">Read the details</a><div class="actions course-card__actions dashboard-panel__actions"><button type="button">View lessons</button><button type="button" disabled>Unavailable</button></div></article></main>
.card { padding: 1rem; }
.card__title { margin: 0; }
.card--featured { border-color: #2563eb; }

Expected result: The base component, its title element, and its featured modifier have distinct, readable responsibilities.

Example 2: a practical interface card

The same idea can style a reusable card on a course page. The class selector keeps the rule attached to this component rather than changing every element of that type.

<section class="demo card-grid course-grid dashboard-panel course-card-list dashboard-grid card-layout"><h2>Learning card</h2><p>Clear styles make this information easier to scan.</p><nav class="site-nav"><a href="/learn">Courses</a></nav><label class="form-field"><span>Email</span><input type="email" aria-invalid="true"></label><article class="card course-card dashboard-card theme-dark"><span class="badge status">New</span><div class="course-card__image"></div><h2 class="course-card__title card__title">Course update</h2><p class="status">New lessons are available this week.</p><a href="/learn" aria-current="page">Read the details</a><div class="actions course-card__actions dashboard-panel__actions"><button type="button">View lessons</button><button type="button" disabled>Unavailable</button></div></article></section>
.course-card { padding: 1.25rem; }
.course-card__title { font-size: 1.25rem; }
.course-card--featured { border-inline-start: 0.25rem solid #2563eb; }

Expected result: The course update reads as a distinct interface card, and its content follows the spacing, color, and layout choices in the rule.

Common mistake

Creating an elaborate naming or utility system before understanding the project’s actual component needs.

Best practice

Choose a consistent convention, keep selectors shallow, and remove obsolete rules when components change.

Practice exercise

Refactor a page stylesheet into tokens, base styles, components, and small utilities without changing its appearance. Apply it to the example above and inspect the result at a narrow and a wide viewport.

Section summary

  • Adopt one useful naming approach and refactor without changing behavior accidentally.
  • Choose a consistent convention, keep selectors shallow, and remove obsolete rules when components change.

Knowledge check

What should a CSS naming convention clarify?

Reveal the explanation

A naming convention is valuable when it makes styles easier to navigate and maintain.

Finish the module lessons, then take the server-scored module quiz to check your understanding.

Practical example

css
.card { padding: 1rem; }
.card__title { margin: 0; }
.card--featured { border-color: #2563eb; }

Expected result:

The base component, its title element, and its featured modifier have distinct, readable responsibilities.

Hands-on practice task

Refactor a page stylesheet into tokens, base styles, components, and small utilities without changing its appearance.

In this section

Other lessons in CSS Architecture and Maintainability

Broaden your knowledge

Related learning topics