Structure Rules
The relationship between component class selectors (Block/Element) follows these rules.
Allowed structures
Block > BlockBlock > Element
Disallowed structures
Element > BlockElement > 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 > Blockat 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_EXCEEDEDis 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.