Skip to content

spiracss/class-structure

Validates SpiraCSS naming rules and selector structure.

Scope component roots are supported from v0.5.0. @scope (.test-card) supplies the root Block for direct declarations and scoped child selectors; an inner :scope wrapper is optional. Existing ownership and selector nesting checks still apply. See scope root syntax for generation settings and examples.

Purpose

  • Keep Block / Element structure machine-readable
  • Stabilize parent-child responsibilities

What it checks

  • Naming (Block / Element / Modifier)
  • Parent-child rules for Block / Element (e.g. disallow Element > Block)
  • Require > for direct children of a Block (relaxed in shared; interaction is excluded from structure checks)
  • Child selectors of a Block must be nested inside that Block (top-level .block > .child is invalid)
  • Placement of shared / interaction sections
  • One root Block per file (rootSingle)
  • Root Block name matches the SCSS file name (rootFile)
  • Handling of data/state according to selectorPolicy

✅ Correct

.sample-block {
> .title {
font-size: 16px;
}
// --shared
.helper {
color: #999;
}
// --interaction
@at-root & {
&:hover {
opacity: 0.8;
}
}
}

❌ Incorrect

.sample-block {
.title { // ❌: in base structure, direct children should use `>`
font-size: 16px;
}
}
.sample-block {
> .title {
> .detail {
> .label {
> .meta {
> .text { // ❌: Element chain too deep (exceeds elementDepth)
color: #333;
}
}
}
}
}
}

Why

  • Enforcing > makes the parent-decides-child-layout structure explicit
  • Limiting Element chain depth keeps responsibilities from becoming ambiguous

Exceptions / notes

  • In the shared section, only the > requirement is relaxed
  • In the interaction section, structural checks are skipped (naming checks still apply)
  • rootFile accepts *.module.scss (CSS Modules; .module is ignored)
  • For rootFile, files under childDir use childFileCase (see configuration options)

Error list

rootScopeRequired (component root must use scope; v0.5.0+)

When generator.scssRootStyle is scope or scope-explicit, createRules() configures this check. A component root written as .test-card { ... } is rejected, even inside @container or @layer. Wrap its body in @scope (.test-card) { :scope { ... } }; direct scope contents are also accepted. Keep @use / @forward and page-entry link comments outside scope. Keep meta.load-css() and Block sections inside its root body. Child and descendant Block files stay in class form; every child-file @scope is a separate lint error. The message names the setting and Block and includes the repair example. The class-form examples below apply to child files or to roots configured for class output.

Keep the root include placement unchanged: moving it outside :scope lowers child specificity and is not the repair. See the child scope policy.

childScopeNotAllowed (child files must use class syntax; v0.5.0+)

Every @scope under the configured childDir is an error, including thematic wrappers, index files, and partials. This applies to child and descendant files for all root style settings, including an omitted direct-rule setting, and independently of rootSingle / rootFile. The path convention is the check’s boundary; lint does not follow a Sass import graph.

Configured component paths cover the entire child subtree. Outside these paths, only files directly under childDir are recognized as children; configure the owning component path to cover deeper directories. Stdin requires a filename to classify child code. Do not mistake an unclassified path for proof of safe Sass output.

Sass can prepend a loading parent’s selector to a child scope, turning :scope into the non-matching :scope :scope. Remove the child scope wrapper and write the child Block in class form:

// @rel/../test-card.scss
.child-card {
> .text { color: red; }
}

Replace child-root :scope references with the child Block selector or nested & as appropriate. Keep the component root’s scope and include placement unchanged. No automatic fix is provided because selector specificity can change. Existing child-file scopes must be migrated manually; native CSS nesting is not being declared invalid.

For a thematic wrapper, preserve its theme condition during manual migration; simply deleting the wrapper would apply conditional styles unconditionally. The class-form example is not an automatic rewrite for theme scopes.

scopeOwnerAmbiguous (nested scope ownership is unclear; v0.5.0+)

A Block-shaped scope around another Block scope must not silently bypass ownership checks. Identify the component with a matching filename or, with rootFile: false, its matching component directory. If neither is available (including stdin), declare a thematic wrapper class in external.classes / external.prefixes. Do not invent a theme name or disable structure lint. Normal thematic wrappers in component root files remain supported when ownership is identifiable.

invalidName (naming rule violation)

Example:

// ❌
.HeroBanner {
color: #222;
}
.titleText {
font-weight: 600;
}
// ✅
.hero-banner {
color: #222;
}
.title {
font-weight: 600;
}

Reason: structure is determined from naming

Notes: follows stylelint.base.naming / naming.customPatterns

elementChainTooDeep (Element chain is too deep)

Example:

// ❌
.card-list {
> .item {
> .content {
> .title {
font-size: 16px;
}
}
}
}
// ✅
.card-list {
> .item {
> .title {
font-size: 16px;
}
}
}

Reason: deep Element chains make responsibilities ambiguous

Notes: depth limit is elementDepth

elementCannotOwnBlock (Block under Element)

Example:

// ❌
.card-list {
> .item {
> .price-tag {
color: #333;
}
}
}
// ✅
.card-list {
> .price-tag {
color: #333;
}
}

Reason: Elements are parts of a Block and do not become parents

blockDescendantSelector (grandchild selector directly under Block)

Example:

// ❌
.card-list {
> .item > .title {
margin-top: 8px;
}
}
// ✅
.card-list {
> .item {
margin-top: 8px;
}
}

Reason: make it clear that the parent decides child layout

blockTargetsGrandchildElement (directly targeting a grandchild Element)

Example:

// ❌
.card-list {
> .price-tag {
> .amount {
font-weight: 700;
}
}
}
// ✅
.price-tag {
> .amount {
font-weight: 700;
}
}

Reason: parent Blocks should not touch grandchild Elements directly

tooDeepBlockNesting (too many nested Blocks)

Example:

// ❌
.card-list {
> .price-tag {
> .icon-badge {
color: #fff;
}
}
}
// ✅
.card-list {
> .price-tag {
color: #fff;
}
}

Reason: Block > Block > Block chains make responsibilities unclear

multipleRootBlocks (multiple root Blocks)

Example:

// ❌
.hero-banner {
color: #222;
}
.card-list {
color: #333;
}
// ✅
.hero-banner {
color: #222;
}

Reason: keep a single entry point per file

duplicateRootBlock (same root Block defined multiple times)

Example:

// ❌
.tab-panels {
> .tab-panel {
color: #111;
}
}
.tab-panels.swiper {
position: relative;
}
// ✅
.tab-panels {
> .tab-panel {
color: #111;
}
&.swiper {
position: relative;
}
}

Reason: rootSingle assumes one root entry point per file

needChild (missing > direct child)

Example:

// ❌
.card-list {
.title {
margin-top: 8px;
}
}
// ✅
.card-list {
> .title {
margin-top: 8px;
}
}

Reason: make direct parent-child relationships explicit

needChildNesting (top-level child selector is not allowed)

Example:

// ❌
.hero-banner > .title {
font-size: 16px;
}
// ✅
.hero-banner {
> .title {
font-size: 16px;
}
}

Reason: keep structure inside the Block and unify reading order

sharedNeedRootBlock (shared comment placement)

Example:

// ❌
.card-list {
> .title {
// --shared
.helper {
color: #999;
}
}
}
// ✅
.card-list {
// --shared
.helper {
color: #999;
}
}

Reason: keep the shared section scope unambiguous

needAmpForMod (Modifier must use &.)

Example:

// ❌
.card-list.-primary {
color: #111;
}
// ✅
.card-list {
&.-primary {
color: #111;
}
}

Reason: treat Modifiers as Block-internal states

needModifierPrefix (invalid & attachment)

Example:

// ❌
.card-list {
&.title {
color: #111;
}
}
// ✅
.card-list {
&.-primary {
color: #111;
}
}

Reason: only Modifiers can be attached to &

disallowedModifier (Modifier disallowed in data mode)

Example:

// ❌
.card-list {
&.-primary {
color: #111;
}
}
// ✅
.card-list {
&[data-variant="primary"] {
color: #111;
}
}

Reason: Variant/State should be expressed with data attributes

invalidVariantAttribute (variant uses class mode)

Example:

// ❌
.card-list {
&[data-variant="primary"] {
color: #111;
}
}
// ✅
.card-list {
&.-primary {
color: #111;
}
}

Reason: in class mode, use Modifiers

invalidStateAttribute (state uses class mode)

Example:

// ❌
.card-list {
&[data-state="active"] {
opacity: 1;
}
}
// ✅
.card-list {
&.-active {
opacity: 1;
}
}

Reason: in class mode, use Modifiers

invalidDataValue (invalid data value naming)

Example:

// ❌
.card-list {
&[data-variant="primary-dark-large"] {
color: #111;
}
}
// ✅
.card-list {
&[data-variant="primary-dark"] {
color: #111;
}
}

Reason: data values must follow naming rules

rootSelectorMissingBlock (selector missing the root Block)

Example:

// ❌
.swiper {
margin-top: 8px;
}
// ✅
.tab-panels {
> .swiper {
margin-top: 8px;
}
}

Reason: structure is read starting from the root Block

rootSelectorNeedNesting (root compound selector must be nested)

Example:

// ❌
.tab-panels.swiper {
position: relative;
}
// ✅
.tab-panels {
&.swiper {
position: relative;
}
}

Reason: keep the root Block as the top-level selector

missingRootBlock (no root Block)

Example:

// ❌
.title {
font-size: 16px;
}
// ✅
.card-list {
font-size: 16px;
}

Reason: one file, one root Block is assumed

selectorParseFailed (selector parse failed)

Example:

// ❌
.card-list {
> : {
color: #111;
}
}
// ✅
.card-list {
> .item {
color: #111;
}
}

Reason: unparseable selectors cannot be validated

fileNameMismatch (file name does not match Block name)

Example:

list.scss
// ❌
.card-list {
color: #111;
}
// ✅
// file: card-list.scss
// (CSS Modules: card-list.module.scss is also accepted)
.card-list {
color: #111;
}

Reason: keep file-to-Block mapping stable

Settings