Skip to content

Stylelint Plugin

A Stylelint plugin that validates SpiraCSS design rules in SCSS files.
Designed to be used with the SpiraCSS Design Principles.

Install

Version 0.6.0 requires Stylelint 17 or 18 and Node.js >=24.22.3 <25. Version 0.5.1 requires Node.js >=24.22.2 <25 and supports Stylelint 17 and 18. Version 0.5.0 supports Stylelint 17 only and requires Node.js >=24.15.0 <25.

Check the peer dependencies of all SCSS plugins and shared configs before moving to Stylelint 18. The starter repositories remain on Stylelint 17 until those dependencies support 18; the install commands below intentionally use 17.

Stylelint v16 users: use @spiracss/stylelint-plugin@0.3.x.

Terminal window
yarn add -D @spiracss/stylelint-plugin stylelint@17 stylelint-scss postcss-scss
Terminal window
npm install -D @spiracss/stylelint-plugin stylelint@17 stylelint-scss postcss-scss

Rules

Rule Description
spiracss/class-structure Naming, parent-child structure, section structure
spiracss/property-placement Property placement (container / item / internal)
spiracss/page-layer Page entry SCSS boundaries and component links
spiracss/interaction-scope Interaction section placement and structure
spiracss/interaction-properties Transition / animation usage inside interaction
spiracss/keyframes-naming @keyframes placement and naming
spiracss/pseudo-nesting Pseudo-class / pseudo-element nesting
spiracss/rel-comments @rel comments for parent-child links

For rule details (✅ / ❌ examples), see the rule pages.

Configuration

This plugin reads spiracss.config.js at the project root.
Use createRules() or createRulesAsync() to generate rule settings from the config.

Passing config object directly

stylelint.config.js
import spiracssPlugin, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'
export default {
plugins: [...spiracssPlugin, 'stylelint-scss'],
customSyntax: 'postcss-scss',
// Exclude shared partials; keep shared keyframes linted.
ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
rules: {
...createRules(spiracssConfig),
'scss/at-rule-no-unknown': true
}
}

Path-based loading

If you need path-based loading, use createRulesAsync().

stylelint.config.js
import spiracssPlugin, { createRulesAsync } from '@spiracss/stylelint-plugin'
const rules = await createRulesAsync('./spiracss.config.js')
export default {
plugins: [...spiracssPlugin, 'stylelint-scss'],
customSyntax: 'postcss-scss',
// Exclude shared partials; keep shared keyframes linted.
ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
rules: {
...rules,
'scss/at-rule-no-unknown': true
}
}

Note: aliasRoots is required when using createRules() or createRulesAsync().

Disabling rules

There are two ways to disable or relax rules:

  1. Stylelint config: set a rule to null (always works).
// Using the same imports as the examples above
export default {
rules: {
...createRules(spiracssConfig),
'spiracss/rel-comments': null // disable this rule
}
}
  1. spiracss.config.js: set stylelint.<rule>.enabled = false or adjust rule options (only when using createRules() / createRulesAsync()).
spiracss.config.js
export default {
stylelint: {
keyframes: { enabled: false },
pseudo: { enabled: false },
rel: { requireChild: false }
}
}

For detailed options, see Configuration Options.

Limitations

  • Validates structural elements (class names, selector structure, @rel comments)
  • Some rules intentionally prioritize “mechanically verifiable” over “interpretive” (e.g. spiracss/property-placement sizeInternal)
  • Cannot automatically judge design decisions (Element chain intent, data/state validity)
  • Supplement with design reviews or code reviews

Recommended setup: stylelint-config-standard-scss + stylelint-config-recess-order.
The recommended config for that setup is documented in Tips.