Skip to content

Configuration Options

All available options for spiracss.config.js.
Each section corresponds to a top-level key in the configuration file.

aliasRoots

Defines root paths for alias resolution.

aliasRoots: {
components: ['src/components'],
styles: ['src/styles']
}
  • The @ prefix is not required (e.g., components becomes @components/...)
  • Keys should match [a-z][a-z0-9-]* (Stylelint resolves only this pattern; Comment Links can recognize any key defined in aliasRoots)
  • Values must be arrays (relative paths recommended / absolute paths are allowed only within the project)
    • Stylelint: ignores candidates resolved outside the project root (does not validate bases)
    • Comment Links: ignores bases outside the project root and also ignores targets resolved outside the root
  • Project root basis:
    • Stylelint: cwd (running from a subdirectory changes the base path; createRulesAsync(path) only specifies the config file path and does not change the project root; run Stylelint from the project root or set the task runner working directory / Node API cwd)
    • Comment Links: the VS Code workspace folder
  • Stylelint cannot resolve aliases not defined in aliasRoots
  • Comment Links only link aliases defined in aliasRoots or the built-in defaults (@src / @components / @styles / @assets / @pages / @parts / @common)
  • CLI tools do not use aliasRoots
  • aliasRoots is required when using createRules() or createRulesAsync() in the SpiraCSS Stylelint plugin (missing it throws an error)

selectorPolicy

Shared configuration for how variants/states are represented.
Defaults to variant=data-variant / state=data-state, and aria-expanded / aria-selected / aria-disabled are also treated as state.

selectorPolicy: {
valueNaming: {
case: 'kebab',
maxWords: 2
},
variant: {
mode: 'data',
dataKeys: ['data-variant']
},
state: {
mode: 'data',
dataKey: 'data-state',
ariaKeys: ['aria-expanded', 'aria-selected', 'aria-disabled']
}
}

Settings:

Field Type Default Description
valueNaming object { case: 'kebab', maxWords: 2 } Naming rules for data values (shared)
variant object { mode: 'data', dataKeys: ['data-variant'] } Variant representation
state object { mode: 'data', dataKey: 'data-state', ariaKeys: [...] } State representation

Notes:

  • mode supports only data / class
  • Data value naming can be overridden by variant/state.valueNaming
  • HTML lint validates only the reserved keys specified here
  • If variant.mode=class and state.mode=class are both used, the HTML-to-SCSS generator treats modifiers as variants
  • aria-* values are not validated because their spec and allowed values vary widely

selectorPolicy.variant

Field Type Default Description
mode 'data' | 'class' 'data' Variant mode
dataKeys string[] ['data-variant'] Allowlist of data attributes (empty array falls back to defaults; cannot disable)
valueNaming object ← parent Naming rules for data values

selectorPolicy.state

Field Type Default Description
mode 'data' | 'class' 'data' State mode
dataKey string 'data-state' Data attribute key for state (only one key allowed)
ariaKeys string[] ['aria-expanded', 'aria-selected', 'aria-disabled'] Allowlist of aria attributes (empty array falls back to defaults; cannot disable)
valueNaming object ← parent Naming rules for data values

stylelint

Rule settings for the SpiraCSS Stylelint plugin.

Basics:

  • Subkeys like base / class / placement are optional (defaults apply)
  • aliasRoots is required

ESM projects:

  • Use createRulesAsync() when loading via path

Constraints:

  • Must be a plain object ([] or new Map() are invalid)

stylelint.base

Shared settings used across multiple rules.
comments / external / naming / cache / paths can be overridden per rule.

stylelint: {
base: {
comments: {
shared: /--shared/i,
interaction: /--interaction/i
},
external: {
classes: [],
prefixes: ['u-']
},
naming: {
blockCase: 'kebab',
blockMaxWords: 2,
elementCase: 'kebab',
modifierCase: 'kebab',
modifierPrefix: '-'
},
cache: {
selector: 1000,
patterns: 1000,
naming: 1000,
path: 1000
},
paths: {
childDir: 'scss',
components: ['components']
}
}
}

Settings:

Field Type Default Description
comments.shared RegExp / string /--shared/i Shared comment matcher
comments.interaction RegExp / string /--interaction/i Interaction comment matcher
external.classes string[] [] External class exclusions (exact match)
external.prefixes string[] [] External class exclusions (prefix match)
naming object – Naming rules (inherited by class / placement / keyframes / rel, etc.)
cache.selector number 1000 Selector parse cache
cache.patterns number 1000 Naming pattern generation cache
cache.naming number 1000 Naming pattern cache
cache.path number 1000 @rel path existence cache
paths.childDir string 'scss' Child Block SCSS directory (default for class / rel)
paths.components string[] ['components'] Component-layer directories (used by class/pageLayer when using createRules; if omitted, createRules falls back to aliasRoots.components)

stylelint.class

Defines class naming rules and selector structure.

Settings:

Field Type Default Description
elementDepth number 4 Max Element chain depth
childCombinator boolean true Require > for direct children of a Block
childNesting boolean true Require child selectors to be nested inside the Block
rootSingle boolean true Single root Block per file
rootFile boolean true Require root Block name to match the filename
scssRootStyle 'class' | 'scope' | 'scope-explicit' Derived from generator.scssRootStyle by createRules() Scope settings require @scope on component roots; every @scope in child Block directories is an error for all settings
rootCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' 'preserve' Case for root Block filename
childFileCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' 'preserve' Case for root filename checks under childDir
childDir string 'scss' Directory for child Block SCSS
componentsDirs string[] ['components'] Directories treated as the component layer (inherits stylelint.base.paths.components; createRules falls back to aliasRoots.components when missing)
comments.shared RegExp / string /--shared/i Shared comment matcher (overrides stylelint.base.comments)
comments.interaction RegExp / string /--interaction/i Interaction comment matcher (overrides stylelint.base.comments)
external.classes string[] [] External class exclusions (exact match)
external.prefixes string[] [] External class exclusions (prefix match)

naming sub-items:

Field Type Default Description
blockCase 'kebab' | 'camel' | 'pascal' | 'snake' 'kebab' Block case
blockMaxWords number 2 Max words for Block names (2–100; minimum 2 is fixed, values above 100 are clamped)
elementCase 'kebab' | 'camel' | 'pascal' | 'snake' 'kebab' Element case
modifierCase 'kebab' | 'camel' | 'pascal' | 'snake' 'kebab' Modifier case
modifierPrefix string '-' Modifier prefix
customPatterns object undefined Custom regex (subkeys: block / element / modifier; values are RegExp)

customPatterns subkeys:

Subkey Target Example
block Block base class /^custom-block-.+$/
element Element base class /^icon-.+$/
modifier Modifier /^--[a-z]+(-[a-z]+)?$/

Example:

stylelint: {
class: {
elementDepth: 4,
childCombinator: true,
childNesting: true,
rootSingle: true,
rootFile: true,
rootCase: 'preserve',
childFileCase: 'preserve',
childDir: 'scss',
componentsDirs: ['components'],
external: {
classes: [],
prefixes: ['swiper-']
},
naming: {
blockCase: 'kebab',
blockMaxWords: 2,
elementCase: 'kebab',
modifierCase: 'kebab',
modifierPrefix: '-',
customPatterns: {
block: /^custom-block-.+$/,
element: /^icon-.+$/,
modifier: /^--[a-z]+(-[a-z]+)?$/
}
}
}
}

Notes:

  • If you use customPatterns, verify it stays consistent with HTML placeholders (block-box / element).
  • customPatterns accept RegExp only. RegExp with g or y flags are invalid.
  • Element names are always a single word. Even with camel/pascal case, internal capitals do not count as word boundaries (bodyText / BodyText are invalid).
  • HTML lint / HTML generation also reference stylelint.base.naming / stylelint.base.external (fallbacks to stylelint.class when base is missing).
  • rootFile applies only under componentsDirs; assets/css, index.scss, and _*.scss are excluded.
  • For rootFile, files under childDir use childFileCase, while files outside childDir use rootCase.
  • For rootFile, both *.scss and *.module.scss are accepted (the .module suffix is ignored).
  • When using createRules() or createRulesAsync(), fileCase.root / fileCase.child and generator.rootFileCase / generator.childFileCase / generator.childScssDir are used as fallbacks for missing fields.

stylelint.pageLayer

Validates page-layer boundaries in page entry SCSS.

stylelint: {
pageLayer: {
enabled: true,
pageEntryAlias: 'assets',
pageEntrySubdir: 'css',
componentsDirs: ['components'],
aliasRoots: {
assets: ['src/assets'],
components: ['src/components']
}
}
}

Settings:

Field Type Default Description
enabled boolean true Disables this rule when set to false (only when using createRules() / createRulesAsync())
pageEntryAlias string 'assets' Alias key for page entry root (falls back to generator.pageEntryAlias when set)
pageEntrySubdir string 'css' Page entry subdir under the alias (falls back to generator.pageEntrySubdir; empty string means alias root)
componentsDirs string[] ['components'] Component-layer directories (inherits stylelint.base.paths.components; createRules falls back to aliasRoots.components when missing)
aliasRoots object – Alias map for page entry + link resolution (inherits spiracss.aliasRoots)
naming object – Naming rules (inherited from stylelint.base.naming, falls back to stylelint.class.naming)
external.classes string[] – External class exclusions (merged from stylelint.base.external + stylelint.class.external)
external.prefixes string[] – External class exclusions (merged from stylelint.base.external + stylelint.class.external)
cache object – Cache sizes (inherited from stylelint.base.cache)

If pageEntryAlias is missing from aliasRoots (or resolves to no directories), the rule is skipped.

stylelint.placement

Validates property placement (container / item / internal).

stylelint: {
placement: {
elementDepth: 4,
marginSide: 'top',
marginSideTags: true,
position: true,
sizeInternal: true,
responsiveMixins: []
}
}

Settings:

Field Type Default Description
elementDepth number 4 Max Element chain depth (when using createRules() / createRulesAsync(), falls back to class.elementDepth if unset)
marginSide 'top' | 'bottom' 'top' Allowed vertical margin side
marginSideTags boolean true Apply marginSide checks to tag-selector rules as well
position boolean true Enable child Block position restrictions
sizeInternal boolean true Treat width / height / inline-size / block-size / min-* / max-* as internal properties
responsiveMixins string[] [] @include mixins treated as transparent
comments.shared RegExp / string /--shared/i Shared comment matcher (overrides stylelint.base.comments)
comments.interaction RegExp / string /--interaction/i Interaction comment matcher (overrides stylelint.base.comments)

stylelint.interactionScope

Validates placement rules for the interaction section (// --interaction and @at-root & { ... }).

stylelint: {
interactionScope: {
pseudos: [':hover', ':focus', ':focus-visible', ':active', ':visited'],
requireAtRoot: true,
requireComment: true,
requireTail: true,
commentOnly: false
}
}

The interaction section must always be placed directly under the root Block (wrapper at-rules like @layer/@supports/@media/@container/@scope are allowed).

Settings:

Field Type Default Description
pseudos string[] [':hover', ':focus', ':focus-visible', ':active', ':visited'] Pseudo-classes to check
requireAtRoot boolean true Require @at-root & { ... } and selectors that start with &
requireComment boolean true Require // --interaction
requireTail boolean true Require the interaction block to be at the end
commentOnly boolean false Only validate blocks with the comment
comments.shared RegExp / string /--shared/i Shared comment matcher (overrides stylelint.base.comments)
comments.interaction RegExp / string /--interaction/i Interaction comment matcher (overrides stylelint.base.comments)

stylelint.interactionProps

Validates transition/animation placement and transition target properties in the interaction section.

stylelint: {
interactionProps: {
// override section comment patterns if needed
// comments: { shared: /--shared/i, interaction: /--interaction/i }
}
}

Settings:

Field Type Default Description
comments.shared RegExp / string /--shared/i Shared comment matcher (overrides stylelint.base.comments)
comments.interaction RegExp / string /--interaction/i Interaction comment matcher (overrides stylelint.base.comments)
naming object – Naming rules (inherited from stylelint.base.naming, falls back to stylelint.class.naming)
external.classes string[] – External class exclusions (merged from stylelint.base.external + stylelint.class.external)
external.prefixes string[] – External class exclusions (merged from stylelint.base.external + stylelint.class.external)
cache object – Cache sizes (inherited from stylelint.base.cache)

stylelint.keyframes

Validates @keyframes naming and placement rules.

stylelint: {
keyframes: {
enabled: true,
actionMaxWords: 3,
blockSource: 'selector',
blockWarnMissing: true,
sharedPrefixes: ['kf-'],
sharedFiles: ['keyframes.scss'],
ignoreFiles: [],
ignorePatterns: [],
// Skip placement checks for keyframes matched by ignorePatterns (default: false)
ignoreSkipPlacement: false
}
}

Settings:

Field Type Default Description
enabled boolean true Disables this rule when set to false (only when using createRules() / createRulesAsync())
actionMaxWords number 3 Max words in the action segment (1–3)
blockSource 'selector' | 'file' | 'selector-or-file' 'selector' Block name source (root selector, file name, or fallback)
blockWarnMissing boolean true Warn when the root Block cannot be resolved
sharedPrefixes string[] ['kf-'] Prefixes for shared keyframes
sharedFiles (string | RegExp)[] ['keyframes.scss'] File patterns allowed for shared keyframes (strings are suffix matches)
ignoreFiles (string | RegExp)[] [] File patterns to skip this rule (strings are suffix matches)
ignorePatterns (string | RegExp)[] [] Keyframes names to ignore (strings are treated as RegExp patterns)
ignoreSkipPlacement boolean false Skip placement checks (root/end) for keyframes matched by ignorePatterns

stylelint.pseudo

Requires pseudo-classes/elements to be nested under &.

stylelint: {
pseudo: {
enabled: true
}
}
  • Allowed: .btn { &:hover { ... } }, .btn { &::before { ... } }
  • Not allowed: .btn:hover { ... }, & > .btn:hover { ... }

Settings:

Field Type Default Description
enabled boolean true Disables this rule when set to false (only when using createRules() / createRulesAsync())

stylelint.rel

Defines rules for @rel link comments.

stylelint: {
rel: {
requireScss: true,
requireMeta: true,
requireParent: true,
requireChild: true,
requireChildShared: true,
requireChildInteraction: false,
validatePath: true,
skipNoRules: true,
childDir: 'scss',
fileCase: 'preserve'
}
}

Settings:

Field Type Default Description
requireScss boolean true Require @rel in SCSS under childDir
requireMeta boolean true Require a top-of-file comment when @include meta.load-css("<childDir>") is present
requireParent boolean true Require child-to-parent @rel (only when requireMeta / requireScss is enabled)
requireChild boolean true Require parent-to-child @rel
requireChildShared boolean true Require child @rel in shared sections
requireChildInteraction boolean false Require child @rel in interaction sections
validatePath boolean true Validate path existence
skipNoRules boolean true Skip SCSS files without selector rules
childDir string 'scss' Directory name for child Block SCSS (falls back to generator.childScssDir when using createRules() or createRulesAsync())
fileCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' 'preserve' Expected file name case for child @rel comments (non-childDir targets)
childFileCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' undefined Expected file name case when the @rel path includes childDir (falls back to fileCase when omitted)
aliasRoots object ← top-level Alias roots for @rel resolution
comments.shared RegExp / string /--shared/i Shared comment matcher (overrides stylelint.base.comments)
comments.interaction RegExp / string /--interaction/i Interaction comment matcher (overrides stylelint.base.comments)

Notes:

  • Alias resolution uses aliasRoots (when validatePath: true)
  • requireParent only fires when requireMeta is enabled and the parent Block includes @include meta.load-css(...), or when requireScss is enabled and the SCSS file lives under childDir
  • fileCase / childFileCase accept *.module.scss (CSS Modules) in addition to .scss

See Comment Links for details.

htmlLint

Controls class ownership checks for HTML structure lint and HTML-to-SCSS generation (HTML CLI / VS Code).

htmlLint.classlessTagCheck

Settings:

Field Type Default Description
classlessTagCheck boolean true Require classes on non-allowlisted HTML tags

Set this to false to disable only the classless-tag check. Other HTML structure checks remain enabled.

htmlLint.classlessTagAllowlist

Settings:

Field Type Default Description
classlessTagAllowlist string[] Built-in list Additional HTML tag names that may intentionally omit a SpiraCSS class

Built-in classless structural tags are picture, source, img, track, map, area, br, and wbr. The configured list is added to the built-in list.

SVG/MathML root elements still require a class; SVG/MathML-native drawing internals do not need SpiraCSS classes, while HTML integration points such as foreignObject and HTML annotation-xml are checked in HTML context. Template, document metadata, native-control internals, and parser-generated table structure are handled separately from this allowlist.

htmlFormat

Controls the output attribute when adding HTML placeholders.

htmlFormat.classAttribute

Settings:

Field Type Default Description
classAttribute 'class' | 'className' 'class' Class attribute to output

Notes:

  • Input class / className is normalized to this setting
  • Internally, class / className are temporarily converted to data-spiracss-classname and restored on output
  • No file extension auto-detection is performed

jsxClassBindings

Controls how JSX class / className bindings are interpreted (HTML CLI / VS Code).

jsxClassBindings.memberAccessAllowlist

Settings:

Field Type Default Description
memberAccessAllowlist string[] undefined Allowlist of base identifiers for member access (e.g. styles.foo). When set, only these bases are treated as class sources.

Notes:

  • When omitted, all member access is allowed
  • An empty array disables member access extraction
  • Applies to HTML-to-SCSS generation and placeholder insertion

generator

Configuration for HTML-to-SCSS conversion.

Settings:

Field Type Default Description
globalScssModule string '@styles/partials/global' Inserts @use "<value>" as *; at the top of each generated SCSS file (in root mode, the root Block SCSS also includes @use "sass:meta"; immediately after it)
pageEntryAlias string 'assets' Alias for the page entry comment
pageEntrySubdir string 'css' Subdirectory for the page entry comment
rootFileCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' 'preserve' Case for the root Block filename
childFileCase 'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal' 'preserve' Case for child Block filenames
scssRootStyle 'class' | 'scope' | 'scope-explicit' 'scope-explicit' Choose the component root SCSS syntax; meta-loaded Blocks retain class selectors
childScssDir string 'scss' Output directory for child Block SCSS; must be a safe relative path inside the document directory
layoutMixins string[] [] Array of layout mixins

Example:

generator: {
globalScssModule: '@styles/global',
pageEntryAlias: 'assets',
pageEntrySubdir: 'css',
rootFileCase: 'kebab',
childFileCase: 'kebab',
childScssDir: 'scss',
layoutMixins: ['@include breakpoint-up(md)', '@include breakpoint-up(lg)']
}

Notes:

  • pageEntryAlias / pageEntrySubdir: in root mode, outputs a comment like // @assets/css/index.scss at the top of the root Block SCSS file (in selection mode, // @rel/(parent-block).scss is output instead)
  • pageEntrySubdir: when empty, the subdirectory is omitted (e.g. // @assets/index.scss)
  • rootFileCase: does not apply to child blocks
  • childFileCase: used for child Block filenames and @rel comments
  • layoutMixins: generates one @include block per entry (default: disabled)

Scope root syntax

Migration from v0.4.x: v0.5.0 changes the component root default to scope-explicit. Existing projects can set generator.scssRootStyle: 'class' to preserve previous root generation and root syntax lint behavior. Child-file scopes remain prohibited for all settings and require manual migration; class-form children are unchanged. HTML lint is unchanged. Do not automatically rewrite stylesheets or change CSS specificity as a lint fix.

generator.scssRootStyle is shared by the HTML CLI and VS Code extension. The default is scope-explicit, with a :scope wrapper. It applies only to the component root SCSS generated in root mode, which loads the child Block styles with meta.load-css() only when independent child Blocks are present. Loaded Block files and their selectors remain in class form without individual scopes. Selection mode generates class-form Blocks to be loaded by the component root. class selects the previous syntax; scope writes declarations and child selectors directly inside @scope.

/* class (optional) */
.test-card { padding: 20px; > .title { color: red; } }
/* scope */
@scope (.test-card) { padding: 20px; > .title { color: red; } }
/* scope-explicit (default) */
@scope (.test-card) { :scope { padding: 20px; > .title { color: red; } } }

Stylelint recognizes all three forms and applies the existing Block ownership, filename, placement, section, link, page-layer, and keyframes rules. A :scope wrapper is optional. :scope:hover still has to follow the ordinary pseudo nesting and interaction rules; use :scope { &:hover { ... } } in the appropriate interaction section. Conventional component rules inside thematic scopes remain supported. Nested scopes do not allow a parent file to style a child Block’s internals.

The default is the recommended form for SCSS compiled with Sass; it can also be selected explicitly:

generator: {
scssRootStyle: 'scope-explicit'
}

The generation default changes to scope-explicit for new component root files only; existing stylesheets are not converted. Select class to keep the previous generation syntax. Direct scope output is still available. Sass currently warns about leading combinators such as > .title directly inside @scope, while direct declarations such as padding: 20px are a separate, supported CSS feature. The warning does not make valid native CSS a SpiraCSS lint error or make :scope mandatory.

These forms retain their native CSS specificity. Scoped direct declarations, :scope, and & are not interchangeable cascade rewrites; do not automatically wrap an existing direct scope in :scope. HTML classes, HTML structure lint, and HTML nesting remain unchanged.

Child and descendant Block files under the configured childDir must use class syntax. Stylelint rejects every @scope in these files, including thematic wrappers, index files, and partials, for all scssRootStyle values and direct rule configurations. This is a SpiraCSS safety policy, not a native CSS restriction. Existing child scopes require manual migration; selecting class does not disable this restriction.

The check uses file placement, not the import graph. Within configured component paths it recognizes the entire child subtree. Outside those paths, only a file directly under childDir is recognized; add the owning component location to componentsDirs / aliasRoots.components to cover deeper directories. Stdin without a filename cannot establish a child path; supply a filename when linting child code.

Sass safety and specificity: when meta.load-css() runs inside a parent style rule, Sass prepends that parent selector to the loaded child rules. A child’s :scope loaded inside the default parent’s :scope becomes the non-matching :scope :scope. Keep the include inside the component root’s :scope body in scope-explicit mode and keep the loaded files in class form. Moving the include to @scope directly would lower child specificity from (0,2,0) to (0,1,0); it is not the repair. Direct scope mode retains its explicitly selected lower-specificity form. Lint does not compile Sass or resolve arbitrary import graphs, and no automatic cascade rewrite is provided.

A root-mode component is still a component root when it has no independent child Blocks. It follows the configured root syntax; only the unnecessary meta.load-css() call is omitted. Adding or removing children does not change its root syntax.

createRules() / createRulesAsync() also passes this setting to spiracss/class-structure (default: scope-explicit). With scope or scope-explicit, a class-form component root is an error; either scope body syntax is accepted. Loaded child Block files must stay in class form. The check identifies component files outside the configured childDir, or a meta.load-css(childDir) include, excluding page entries and child Block files. Explicit component paths take precedence over the legacy assets/css page exclusion. Root scope enforcement and child scope prohibition are independent of rootSingle and rootFile. @container, @layer, @media, and @supports wrappers are supported and do not bypass either check. Diagnostics identify the setting or child directory, offending Block, cause, and repair example. For direct rule configuration, the same option is named scssRootStyle on spiracss/class-structure; an omitted direct-rule option does not enforce a root syntax, but still prohibits child scopes. An explicit stylelint.class.scssRootStyle overrides the generator-derived value.

For nested scopes in a root file, Block ownership must be identifiable. A matching component filename identifies the owner; with rootFile: false, a matching component directory can also identify it. If neither is available (including stdin), declare a thematic wrapper through external.classes / external.prefixes. Ambiguous ownership is an error, not an implicit exemption from structural checks.