HTML

Topics

The basics

First and foremost, we make an attempt to adhere to the WordPress HTML coding standards.

Classes should follow the Block Element Modifier (BEM) format for naming consistency and ease of targetting in CSS. There are no hard rules for naming in BEM (other than what is provided in the link above). However, some names are better than others. This will usually come down to semantics of the HTML structure. The better the structure, the clearer the names will be.

A good example of using BEM is the product card seen below. It always follows the class name structure of block__element--modifier. The product card is the Block in BEM, with the class name product-card. It does not have an element or modifier as it is the top-level block. Child elements of the product card have classes that follow the block with two underscores and the element name. For example, we have product-card__header and product-card__content. These both follow a block__element structure. Modifiers are applied where needed, and can follow a block--modifier or block__element--modifier structure. Below, we see an example of a featured product card, with the class product-card--featured.

Bad

<div class="Product-Card">
  <header class="card_header">
    <img src="/tec-icon.png" class="product-_image" />
  </header>
  <div class="card__content">
    <h3 class="product-LABEL">The Events Calendar</h3>
    <p class="product_description">
      Easily create and manage an events calendar on your website with The Events Calendar.
      Whether your events are in-person or virtual events, this plugin boasts professional
      features backed by our world-class team of developers and designers.
    </p>
  </div>
</div>

Good

<article class="product-card">
  <header class="product-card__header">
    <img src="/tec-icon.png" class="product-card__header-image" />
  </header>
  <div class="product-card__content">
    <h3 class="product-card__label">The Events Calendar</h3>
    <p class="product-card__description">
      Easily create and manage an events calendar on your website with The Events Calendar.
      Whether your events are in-person or virtual events, this plugin boasts professional
      features backed by our world-class team of developers and designers.
    </p>
  </div>
</article>

<article class="product-card product-card--featured">
  <header class="product-card__header">
    <img src="/ecp-icon.png" class="product-card__header-image" />
  </header>
  <div class="product-card__content">
    <h3 class="product-card__label">Events Calendar Pro</h3>
    <p class="product-card__description">
      When events are your business, you need a calendar with more than the basics. Events
      Calendar Pro has all the features you need (and none of the junk you don’t).
    </p>
  </div>
</article>

When applying modifiers, they should be applied in a semantic manner. If we have a featured product card where the header and content element styles change, we should add a product-card--featured class to the product-card block rather than a product-card__header--featured and product-card__content--featured class to each of the elements that have featured styles. This implies that we could have a featured product card header without a featured product card content, and vice-versa, when they both are applied together. This also introduces a maintenance problem when the product card grows and new elements that require featured styles are introduced.

Bad

<article class="product-card">
  <header class="product-card__header product-card__header--featured">
    <img src="/tec-icon.png" class="product-card__header-image" />
  </header>
  <div class="product-card__content product-card__content--featured">
    <h3 class="product-card__label">The Events Calendar</h3>
    <p class="product-card__description">
      Easily create and manage an events calendar on your website with The Events Calendar.
      Whether your events are in-person or virtual events, this plugin boasts professional
      features backed by our world-class team of developers and designers.
    </p>
  </div>
</article>

Good

<article class="product-card product-card--featured">
  <header class="product-card__header">
    <img src="/ecp-icon.png" class="product-card__header-image" />
  </header>
  <div class="product-card__content">
    <h3 class="product-card__label">Events Calendar Pro</h3>
    <p class="product-card__description">
      When events are your business, you need a calendar with more than the basics. Events
      Calendar Pro has all the features you need (and none of the junk you don’t).
    </p>
  </div>
</article>