Skip to main content
U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

Naming

  • HTML elements should be in lowercase.

    body,
    div {
    }
    
  • Classes should be lowercase.
  • Avoid camelcase.
  • Name things clearly.
  • Write classes semantically. Name its function not its appearance.

    // Bad
    // Avoid uppercase
    .ClassNAME { }
    
    // Avoid camel case
    .commentForm { }
    
    // What is a c1-xr? Use a more explicit name.
    .c1-xr { }
    
  • Avoid presentation- or location-specific words in names, as this will cause problems when you (invariably) need to change the color, width, or feature later.

    // Bad
    .blue
    .text-gray
    .100width-box
    
    // Good
    .warning
    .primary
    .lg-box
    
  • Be wary of naming components based on content, as this limits the use of the class.

    // Danger zone
    .product_list
    
    // Better
    .item_list
    
  • Don’t abbreviate unless it’s a well-known abbreviation.

    // Bad
    .bm-rd
    
    // Good
    .block--lg
    
  • Use quotes in type pseudo selectors.

    // Good
    .top_image[type="text"] {
    }
    
  • Name CSS components and modules with singular nouns.

    .button {
    }
    
  • Name modifiers and state-based rules with adjectives.

    .is_hovered {
    }
    
  • If your CSS has to interface with other CSS libraries, consider namespacing every class.

    .f18-component
    

Naming Methodologies

When it comes to naming, the most important thing is consistency. The recommended way to do this is using an existing methodology like BEM, or use a custom one that’s clearly defined.

BEM

BEM (Block, Element, Modifier) structures CSS such that every entity is composed of (you guessed it) blocks, elements and modifiers. From Harry Roberts:

The point of BEM is to tell other developers more about what a piece of markup is doing from its name alone. By reading some HTML with some classes in, you can see how – if at all – the chunks are related; something might just be a component, something might be a child, or element, of that component, and something might be a variation or modifier of that component.

TTS generally recommends using a modified BEM methodology outlined in the next subsection. However, you might want to use standard BEM when:

  • You need a naming scheme that general CSS developers will already be familiar with or an existing naming scheme hasn’t been consistent enough.
  • When you want to use JavaScript to modify the BEM class names dynamically.

Here is an example of BEM in SCSS:

// block
.inset {
  margin-left: 15%;

  // element
  .inset__content {
    padding: 3em;
  }
}

// modifier
.inset--sm {
  margin-left: 10%;

  .inset__content {
    padding: 1em;
  }
}

// modifier
.inset--lg {
  margin-left: 20%;
}

Suggested custom methodology

The TTS recommendation for a naming methodology is a modified version of BEM. It still uses blocks, sections within blocks and modifiers, but with an abbreviated syntax.

.accordion
.accordion-item
.accordion-item-selected

.nav_bar
.nav_bar-link
.nav_bar-link-clicked

Naming methodology resources

js- flagged classes

Don’t attach styles to classes with a js- flag. These classes are reserved for javascript.

// Bad
.js-people {
  color: #ff0;
}

Rationale

A js- flagged class needs to be highly portable. Adding styles to it breaks that portability.

test- flagged classes

Don’t attach styles to classes with a test- flag. These classes are reserved for testing hooks such as those used by selenium.

// Bad
.test-people {
  color: #ff0;
}
Looking for U.S. government information and services?

Visit USA.gov