Structure Rules

The relationship between component class selectors (Block/Element) follows these rules.

Allowed structures

• Block > Block
• Block > Element

Disallowed structures

• Element > Block
• Element > Element
• In a parent Block’s SCSS, targeting a child Block’s Elements directly (e.g. > .child-block > .element)

Exception

Element > Element is allowed only for non-layout decorative or semantic grouping (e.g. .content > .paragraph > .emphasis).

Nesting depth

Block nesting

• Block > Block is allowed, but avoid chaining three or more Blocks
• If a “meaningful unit” appears at grandchild depth, promote it to a separate Block directly under the parent
• The parent Block’s SCSS should only cover itself and immediate > .child

Element nesting

• Element chains are only allowed for decorative/semantic purposes
• Keep within four levels (Block > Element > Element > Element > Element)

Examples

Correct (parent Block)

.search-form {
  // Block (two words)
  > .field {
    // Element (one word)
  }
  > .actions-container {
    // child Block (two words)
    // Only specify placement here
  }
}

Incorrect (parent Block)

.search-form {
  > .actions-container {
    > .button {
      // ❌ Parent reaches into child Block's Element
    }
  }
}

Correct (child Block)

.actions-container {
  // Treat as its own component
  > .button {
    // Element (one word)
  }
}

All structure is a repetition of Block > (Block | Element).