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

• 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>

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

• 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>

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

• 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.

• 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>

• 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.

• 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>

• - 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.
}

• 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>

• 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.

• 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>

• 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>

<!-- 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>

• - 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.

• Always add class if there are page-specific styles.

<html class-"some-page">
</html>

• CSS files might be concatenated.

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

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

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