Skip to content

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

  • HTML can nest Block > Block at any design depth. There is no rule requiring a grandchild Block to be moved or renamed solely because of its depth; leaf Blocks remain valid.
  • Each Block owns its own component styles. The parent Block’s SCSS covers itself and the placement of immediate child Blocks, not their internal Elements.
  • SCSS selector ownership/nesting diagnostics are not a maximum HTML Block-depth rule. The markup tool’s MAX_DEPTH_EXCEEDED is an implementation safety guard (256), not design guidance.

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

Component type-selector recommendation

Keep SCSS enforcement in Stylelint. Use its native selector-max-type rule rather than a second SpiraCSS type-selector rule. Apply zero only to the component paths that should be class-based, including scoped roots:

// Merge this override into the existing Stylelint config and SpiraCSS rules.
overrides: [
{
files: ['src/components/**/*.scss'],
rules: { 'selector-max-type': 0 }
}
]

Then @scope (.card-list) { :scope { > .body {} } } is class-based, while > p {} is rejected. Keep intentional page/global type selectors outside the component path override (or use an explicit project-specific exception). Do not globally enable this restriction and erase existing page/global exceptions. This recommendation changes neither HTML structure nor the existing @scope/child-file policy.