コンテンツにスキップ
SpiraCSS v0.3.2-beta

Stylelint プラグイン

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

インストール

Stylelint v16 以上と Node.js >= 20 が必要です。

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

ルール

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

ルールの詳細（OK / NG 例）は ルールページ を参照してください。

設定

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

プロジェクトのモジュール方式に合わせて、CommonJS / ESM のどちらか1つを選んで設定します。

CommonJS（推奨）

stylelint.config.js
const spiracss = require('@spiracss/stylelint-plugin')
const plugin = spiracss.default ?? spiracss
const { createRules } = spiracss


module.exports = {
  plugins: [plugin, 'stylelint-scss'],
  customSyntax: 'postcss-scss',
  // 共通パーシャルは除外し、共有 keyframes は検証対象に含める。
  ignoreFiles: ['src/styles/partials/**/*.scss', '!src/styles/partials/keyframes.scss'],
  rules: {
    ...createRules('./spiracss.config.js'),
    'scss/at-rule-no-unknown': true
  }
}

ESM プロジェクト

package.json に "type": "module" がある場合は export default を使用してください。

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

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
  }
}

パス指定で読み込む方法

ESM でパス指定を使いたい場合は 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 を指定（常に有効）。
module.exports = {
  rules: {
    ...createRules('./spiracss.config.js'),
    '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 コメント）を検証
  • 設計判断（Element 連鎖の意図、data/state の妥当性）は自動判定不可
  • 設計レビューやコードレビューで補完が必要

Stylelint 推奨設定（任意）

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