コンテンツにスキップ

Stylelint プラグイン

SpiraCSS の設計ルールを SCSS ファイルで検証する Stylelint プラグインです。
SpiraCSS 設計原則に基づいて設計されています。

インストール

v0.6.0 は、Stylelint 17 または18と Node.js >=24.22.3 <25 が必要です。 v0.5.1 は Node.js >=24.22.2 <25 が必要で、Stylelint 17 と18に対応します。 v0.5.0 は Stylelint 17 のみに対応し、Node.js >=24.15.0 <25 が必要です。

18系へ更新する前に、併用する SCSS プラグインや共有設定すべての peerDependencies を確認してください。 スターターは周辺依存が18系に対応するまで17系を維持します。以下のインストール例も17系を指定しています。

Stylelint v16 をお使いの方は @spiracss/stylelint-plugin@0.3.x を使用してください。

ターミナルウィンドウ
yarn add -D @spiracss/stylelint-plugin stylelint@17 stylelint-scss postcss-scss
ターミナルウィンドウ
npm install -D @spiracss/stylelint-plugin stylelint@17 stylelint-scss postcss-scss

ルール

ルール 説明
spiracss/class-structure 命名・親子構造・セクション構成
spiracss/property-placement プロパティ配置(コンテナ / アイテム / 内部)
spiracss/page-layer ページエントリ SCSS の境界とリンク
spiracss/interaction-scope interaction セクションの位置と構造
spiracss/interaction-properties interaction 内の transition / animation
spiracss/keyframes-naming @keyframes の配置と命名
spiracss/pseudo-nesting 疑似クラス / 疑似要素のネスト
spiracss/rel-comments @rel コメントによる親子リンク

ルールの詳細(✅ / ❌ 例)は ルールページ を参照してください。

設定

このプラグインはプロジェクトルートの spiracss.config.js を参照します。
createRules() または createRulesAsync() で設定からルールを生成します。

設定オブジェクトを直接渡す方法

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',
// 共通パーシャルは除外し、共有 keyframes は検証対象に含める。
ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
rules: {
...createRules(spiracssConfig),
'scss/at-rule-no-unknown': true
}
}

パス指定で読み込む方法

パス指定で読み込む場合は 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',
// 共通パーシャルは除外し、共有 keyframes は検証対象に含める。
ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
rules: {
...rules,
'scss/at-rule-no-unknown': true
}
}

注意: createRules() / createRulesAsync() を使う場合は aliasRoots が必須です。

ルールの無効化

無効化や緩和には 2 つの方法があります。

  1. Stylelint 設定で null を指定(常に有効)。
// 上記の例と同じ import を使用
export default {
rules: {
...createRules(spiracssConfig),
'spiracss/rel-comments': null // このルールを無効化
}
}
  1. spiracss.config.js の stylelint.<rule>.enabled = false や各ルールのオプション調整(createRules() / createRulesAsync() 使用時のみ有効)。
spiracss.config.js
export default {
stylelint: {
keyframes: { enabled: false },
pseudo: { enabled: false },
rel: { requireChild: false }
}
}

詳細なオプションは Configuration Options を参照してください。

制限事項

  • 構造的な要素(クラス名・セレクタ構造・@rel コメント)を検証
  • 一部のルールは「解釈」より「機械的に検証できること」を優先して割り切っている(例:spiracss/property-placement の sizeInternal)
  • 設計判断(Element 連鎖の意図、data/state の妥当性)は自動判定不可
  • 設計レビューやコードレビューで補完が必要

Stylelint 推奨設定(任意)

推奨構成は stylelint-config-standard-scss + stylelint-config-recess-order です。
その前提の推奨設定は Tips にまとめています。