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 > .childis 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)
rootFileaccepts*.module.scss(CSS Modules;.moduleis ignored)- For
rootFile, files underchildDirusechildFileCase(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:
// ❌.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
- spiracss.config.js / stylelint.class
- Section comment patterns can also be changed via
stylelint.base.comments