Cell Naming Convention

The naming convention as required by your markup/HTML when using by Cell is a variant of BEM, and is 90% identical. The main differences are:

• Blocks are called Modules
• Elements are called Components
• Modules and Components do not need separate classes for modifiers
• Cell has Sub-Components

BEM

<div class="panel panel--highlight panel--large">
  ...
</div>

Cell

<div class="panel--highlight--large">
  ...
</div>

Read the BEM page for more information, keeping in mind that Cell refers to Blocks as Modules, and Elements as Components

The Cell Naming Convention adheres to the principles of Cell Query. You can learn more about the theory behind the Cell Naming Convention by reading the Cell Query Introduction.

Module/Component Semantics/Gotchas

Due to the way Cell generates the selectors for your Modules and Components, you must take care to ensure your Component names do not conflict with any Module names. For example, if you have a button Module, you should not also have a header__button Component. This may seem draconian, but it's actually a featural byproduct of how Cell is built as it prevents accidental semantic confusions from occuring (you as the author may intend for a header__button Component to not receive button Module styles, but to Cell and other potential developers, it could be unclear).

The issue would be that the header__button Component may or may not receive the styles of the button Module (depending on whether the header__button Component had any Modifiers, as it would be matched by the [class*="button--"] part of the button selector). It's not clear from this case whether header__button should receive the button styles (i.e Cell is unable to determine if the author intends it), so it should be avoided.

Correct Solutions

If you have a button within the header (header__button), but it shouldn't received styles from an existing button module, then you have an inherent semantic issue; you are saying to Cell "it is a button, but it isn't". You could consider something more context appropriate, such as cta (call-to-action), leaving the Component as header__cta, or something like header__login etc.

If you have a button within the header that should receive styles from an existing button module but should also have additional styles when within the header, you can nest a new button include in the header Module:

@include module('header') {
  ...

  @include module('button') {
    ...
  }
}

Now you can use the button module as normal within your header and it will receive all default styles in addition to the new custom styles.

You can alternatively treat the header button as separate a Component of the header in addition to being a button Module by adding multiple classes (class="button header__cta"):

@include module('header') {
  ...

  @include component('cta') {
    ...
  }
}

Next steps...

Checkout the Creating a Module page.