Skip to content

Instantly share code, notes, and snippets.

@whizark

whizark/class-naming-convention.md

Last active November 7, 2024 10:25
Show Gist options
  • Save whizark/92ed70d90d262a44db84 to your computer and use it in GitHub Desktop.
Save whizark/92ed70d90d262a44db84 to your computer and use it in GitHub Desktop.
Download ZIP
HTML/CSS Class Naming Convention #html #css #sass
Raw
class-naming-convention.md

HTML/CSS Class Naming Convention

A HTML/CSS Class Naming Convention for Scalable/Modular CSS.

ToC

Basics

  • You must use lowercase for a class name.
  • You should use a noun or noun phrase as much as possible.
<!-- Bad -->
<!-- A news -->
<p class="News">A news</p>

<!-- Not Good -->
<!-- A new something -->
<p class="new">A news</p>

<!-- Good -->
<!-- A news -->
<p class="news">A news</p>

Why

  • Most people use lowercase for HTML.
  • CSS is a lowercase language.

Phrase and Compound Word

  • You must use - for a phrase/compound word.
<!-- Bad -->
<!-- The latest news -->
<p class="latest_news">The news</p>

<!-- Bad -->
<!-- The latest news -->
<p class="latestNews">The news</p>

<!-- Good -->
<!-- The latest news -->
<p class="latest-news">The news</p>

Why

  • Most people use lowercase for HTML.
  • CSS is a lowercase language.
  • - is a standard character in HTML/CSS.

Disadvantage

  • You might not be able to select the phrase when you double-click on it in many editor environments.

However, you should use any features of your editor or vi" with Vim's key mapping.

Plural and Collection

  • You should add an additional word such as -list, -group or -collection etc. for a collection of elements.
  • You should avoid using plural as much as possible.
  • You should use -of- for [WIP]. See also: Namespace
<!-- Bad -->
<!-- A girs's book?, girls' book? or the girls book? -->
<h1 class="girls-book">A book</h1>

<!-- Not Bad -->
<!-- A girl's book -->
<h1 class="book-of-girl">A book</h1>

<!-- A girls' book -->
<h1 class="book-of-girls">A book</h1>

<!-- The girls book -->
<h1 class="girls-book">The book</h1>

<!-- Bad -->
<!-- A news? or some news? -->
<ol class="news">
   <li>A news</li>
   <li>A news</li>
</ol>

<!-- Good -->
<!-- A news list -->g
<ol class="news-list">
   <li class="news">A news</li>
   <li class="news">A news</li>
</ol>

Why

  • There are uncountable nouns that don't have plural. e.g. news
  • There are nouns that cannot be distinguished between plural, genitive case and plural genitive case. e.g. girls, girl's and girls' become the same class name girls.
  • Plural is unreadable and might cause typo.

Variant

  • You should create a new class name for a variant of a class.
  • The name must follow the Phrase and Compound Word.
  • You must not use -- for a variant such as BEM's Modifier.
<!-- Bad -->
<!-- A news list featured -->
<ol class="news-list--featured">
    <li class="news">A news</li>
</ol>

<!-- Good -->
<!-- A featured news list -->
<ol class="featured-news-list">
    <li class="news">A news</li>
</ol>

Why

  • - is a standard character in HTML/CSS.
  • The class used in HTML should be a concrete class.
  • More natural and readable than using a suffix. e.g. featured-news-list vs news-list--featured
  • The name can be shorter. e.g. animal and the variant cat vs animal--cat.
  • You cannot use -- in HTML comment. e.g. <!-- .news-list--featured --> is an invalid comment.

In addition, there is a bad use case when a suffix is used as a variant name such as BEM's Modifier with Sass.

// Bad
.news-list {
  // Because the featured news list is NOT A CHILD of the news list.
  // The featured news list is IS-A of the news list.
  // http://en.wikipedia.org/wiki/Is-a
  @at-root &--featured {
  }
}

// Good
.news-list {
}

.featured-news-list {
  @extend .news-list !optional;

  // Override properties here.
}

Namespace

  • You may use \ (back-slash) as a namespace separator.
  • A fully-qualified namespace should have the following structure: <Vendor Name>\(<Namespace>\)*<Class Name>
<!-- Good -->
<!-- A list in a news-list namespace -->
<ol class="news-list\list">
    <!-- A list item in a news-list namespace -->
    <li class="news-list\list-item">An item</li>
</ol>

<!-- Better -->
<!-- A list in vendor's news-list namespace -->
<ol class="vendor\news-list\list">
    <!-- A list item in vendor's news-list namespace -->
    <li class="vendor\news-list\list-item">An item</li>
</ol>

Why

  • It can avoid conflicting with other's naming in CSS framework/JavaScript library etc.
  • You cannot use -- in HTML comment. e.g. <!-- .news-list--featured --> is an invalid comment.

Disadvantage

  • A few IDE might not be able to correctly handle escaped selector.
  • You have to escape \ with \ in CSS.
.vendor\\news-list\\list {}
.vendor\\news-list\\list-item {}
  • You also need to escape \ with \ in JavaScript. However, you may add data-* attribute(s) instead of the class name.
<ol class="vendor\news-list\list" data-foldable="true">
    <!-- A list item in vendor's news-list namespace -->
    <li class="vendor\news-list\list-item">An item</li>
</ol>

Element

  • You must use \ for a descendant element of an element.
  • A variant of a descendant element must follow the Variant.
  • \ also represents a namespace separator. See also: Namespace
<!-- Bad -->
<!-- A news list -->
<ol class="news-list">
    <!-- An item of the news list -->
    <li class="news-list__item">A news</li>
</ol>

<!-- Bad -->
<!-- A list in a news-list namespace -->
<ol class="news-list\list">
    <!-- A new item in a news-liste namespace -->
    <li class="news-list\item--new">A new item</li>

    <!-- An item in a news-list namespace -->
    <li class="news-list\item">An item</li>
</ol>

<!-- Good -->
<!-- A list in vendor's news-list namespace -->
<ol class="vendor\news-list\list">
    <!-- A list item in vendor's news-list namespace -->
    <li class="vendor\news-list\item">An item</li>
</ol>

<!-- Good -->
<!-- A list in vendor's news-list namespace -->
<ol class="vendor\news-list\list">
    <!-- A new list item in vendor's news-list namespace -->
    <li class="vendor\news-list\new-list-item">A new item</li>

    <!-- A list item in vendor's news-list namespace -->
    <li class="vendor\news-list\list-item">An item</li>
</ol>

Global Class

WIP

<!-- Not Bad -->
<p class="error">An error message</p>

<div class="message">
    <p class="error">An error message</p>
</div>

<!-- Good -->
<p class="error">An error message</p>

<div class="message">
    <p class="error error-of-message">An error message</p>
</div>

<!-- Better -->
<div class="error">An error message</div>

<div class="message">
    <p class="message\error">An error message</p>
</div>

Why

  • - is a standard character in HTML/CSS.
  • Each word looks like well-separated. If you would use __ for a descendant element such as news-list__item and double-click it, list__item would be selected in many editor environments.
  • It has the consistency of the naming between CSS and Sass Naming Convention except for the Namespace.

Structure

  • WIP

Context

  • Always add class if there are page-specific styles.
<html class-"some-page">
</html>

Why

  • CSS files might be concatenated.

Examples

.media {}
.media--img {}
.media--rev-img {}
.media--body {}

.person {}
.person\\hand {}
.female {}
.female\\hand {}
.person\\left-hand {}

Resources

License

Copyright (C) 2014 Whizark. Released under the MIT License.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment