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
HTML
Learn to structure accessible, meaningful web pages with a complete HTML course from first document to professional application patterns.
JavaScript
Build strong JavaScript foundations with browser examples, focused practice, beginner projects, and module quizzes.