設定オプション

spiracss.config.js で使用可能なすべてのオプションです。
各セクションは設定ファイルのトップレベルキーに対応しています。

aliasRoots

エイリアスパスの解決ルートを定義します。

aliasRoots: {
  components: ['src/components'],
  styles: ['src/styles']
}

• キーに @ プレフィックスは不要です（components → @components/...）
• キーは [a-z][a-z0-9-]* を推奨します（Stylelint はこの形式のみ解決可能 / Comment Links は aliasRoots に定義すれば任意キーでも認識）
• 値は配列で指定します（相対パス推奨 / 絶対パスはプロジェクト内のみ）
  • Stylelint: 解決結果がプロジェクトルート外になる候補を採用しません（ベース自体は検証しません）
  • Comment Links: ベースがプロジェクトルート外のものを無視し、解決結果がプロジェクトルート外のものも無視します
• プロジェクトルートの基準:
  • Stylelint: cwd（サブディレクトリから実行すると基準も変わります。createRulesAsync(path) は設定ファイルの読み込みパス指定で、プロジェクトルート自体は変わりません。必要ならプロジェクトルートで実行するか、タスクランナーの working directory／Node API の cwd を設定）
  • Comment Links: VS Code のワークスペースフォルダ
• aliasRoots に無いエイリアスは Stylelint 側では解決できません
• Comment Links は aliasRoots のキー、または既定エイリアス（@src / @components / @styles / @assets / @pages / @parts / @common）のみをリンク化します
• CLI ツールは aliasRoots を参照しません
• SpiraCSS Stylelint プラグインの createRules() / createRulesAsync() を使う場合、aliasRoots は必須です（未設定だとエラー）

selectorPolicy

バリアント/状態の表現方法を切り替える共通設定です。
デフォルトは バリアント=data-variant / 状態=data-state を使用し、aria-expanded / aria-selected / aria-disabled も状態扱いします。

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

設定一覧:

項目	型	デフォルト	説明
valueNaming	object	{ case: 'kebab', maxWords: 2 }	data 値の命名ルール（共通）
variant	object	{ mode: 'data', dataKeys: ['data-variant'] }	バリアントの表現方針
state	object	{ mode: 'data', dataKey: 'data-state', ariaKeys: [...] }	状態の表現方針

補足:

• mode は data / class のみ有効です
• data 値の命名は valueNaming を基準に variant/state.valueNaming で上書きできます
• HTML lint もここで指定した予約キーのみを検証します
• variant.mode=class と state.mode=class を同時に使う場合、生成側では modifier を variant 扱いに統一します
• aria-* の値は仕様や許容値が広いため検証対象外です

selectorPolicy.variant

項目	型	デフォルト	説明
mode	'data' | 'class'	'data'	バリアントの表現モード
dataKeys	string[]	['data-variant']	data 属性の allowlist（空配列はデフォルトにフォールバック。無効化不可）
valueNaming	object	← parent	data 値の命名ルール

selectorPolicy.state

項目	型	デフォルト	説明
mode	'data' | 'class'	'data'	状態の表現モード
dataKey	string	'data-state'	状態表現に使う data 属性（1 つに固定）
ariaKeys	string[]	['aria-expanded', 'aria-selected', 'aria-disabled']	aria 属性の allowlist（空配列はデフォルトにフォールバック。無効化不可）
valueNaming	object	← parent	data 値の命名ルール

stylelint

SpiraCSS Stylelint プラグインのルール設定です。

基本:

• base / class / placement など各サブキーは省略可（デフォルト適用）
• aliasRoots は必須

ESM プロジェクト:

• パス指定で読み込む場合は createRulesAsync() を使用

制約:

• プレーンオブジェクトのみ有効（[] や new Map() は不可）

stylelint.base

複数ルールに共通で使う設定です。
comments / external / naming / cache / paths は各ルール側で上書きできます。

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

設定一覧:

項目	型	デフォルト	説明
comments.shared	RegExp / string	/--shared/i	shared コメント判定
comments.interaction	RegExp / string	/--interaction/i	interaction コメント判定
external.classes	string[]	[]	外部クラスを除外（完全一致）
external.prefixes	string[]	[]	外部クラスを除外（前方一致）
naming	object	–	命名規則（class / placement / keyframes / rel などに継承）
cache.selector	number	1000	セレクタ解析キャッシュ
cache.patterns	number	1000	命名パターン生成キャッシュ
cache.naming	number	1000	命名パターンキャッシュ
cache.path	number	1000	@rel パス存在チェックキャッシュ
paths.childDir	string	'scss'	子 Block SCSS の配置ディレクトリ（class / rel のデフォルト）
paths.components	string[]	['components']	コンポーネント層ディレクトリ（class のデフォルト）

注意: comments.shared / comments.interaction は RegExp または文字列を指定できます。文字列は new RegExp(pattern, 'i') として扱われ、無効/危険なパターンはデフォルトにフォールバックします。柔軟性が必要な場合は RegExp の指定を推奨します。

stylelint.class

クラス命名規則とセレクタ構造のルールを定義します。

設定一覧:

項目	型	デフォルト	説明
elementDepth	number	4	Element 連鎖の段数上限
childCombinator	boolean	true	Block 直下に > を必須化
childNesting	boolean	true	子要素は Block 内でネスト必須
rootSingle	boolean	true	1 ファイル 1 ルート Block
rootFile	boolean	true	ルート Block 名とファイル名一致
rootCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	'preserve'	ルート Block のファイル名ケース
childFileCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	'preserve'	childDir 配下でのファイル名ケース（rootFile 用）
childDir	string	'scss'	子 Block SCSS の配置ディレクトリ
componentsDirs	string[]	['components']	コンポーネント層として扱うディレクトリ
comments.shared	RegExp / string	/--shared/i	shared コメント判定（stylelint.base.comments を上書き）
comments.interaction	RegExp / string	/--interaction/i	interaction コメント判定（stylelint.base.comments を上書き）
external.classes	string[]	[]	外部クラスを除外（完全一致）
external.prefixes	string[]	[]	外部クラスを除外（前方一致）

naming サブ項目:

項目	型	デフォルト	説明
blockCase	'kebab' | 'camel' | 'pascal' | 'snake'	'kebab'	Block のケース
blockMaxWords	number	2	Block の最大語数（2〜100。下限 2 は固定、100 超は 100 にクランプ）
elementCase	'kebab' | 'camel' | 'pascal' | 'snake'	'kebab'	Element のケース
modifierCase	'kebab' | 'camel' | 'pascal' | 'snake'	'kebab'	Modifier のケース
modifierPrefix	string	'-'	Modifier のプレフィックス
customPatterns	object	undefined	カスタム正規表現（下表参照）

customPatterns サブキー:

サブキー	対象	例
block	Block の base class	/^custom-block-.+$/
element	Element の base class	/^icon-.+$/
modifier	Modifier	/^--[a-z]+(-[a-z]+)?$/

例:

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]+)?$/
      }
    }
  }
}

注意事項:

• customPatterns を使う場合、HTML プレースホルダ（block-box / element）と一致しない可能性があるため整合性を確認してください。
• customPatterns は RegExp のみ有効 です。g / y フラグ付きは無効になります。
• Element は 常に 1 語です。elementCase=camel/pascal でも内部大文字で語分割しません（例: bodyText / BodyText は 1 語で 2 語以上に見えるため不許可）。
• HTML lint / HTML 生成でも stylelint.base.naming / stylelint.base.external を参照します（未指定時は stylelint.class の値）。
• rootFile は componentsDirs 配下のみを対象とし、assets/css、index.scss、_*.scss は除外されます。
• rootFile の期待値は childDir 配下なら childFileCase、配下外なら rootCase で整形したファイル名です。
• rootFile は *.scss と *.module.scss の両方を許可します（.module サフィックスは無視されます）。
• createRules() / createRulesAsync() を使う場合、fileCase.root / fileCase.child と generator.rootFileCase / generator.childFileCase / generator.childScssDir が未指定項目のフォールバックに使われます。

stylelint.pageLayer

ページエントリ SCSS の page layer 境界を検証します。

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

設定一覧:

項目	型	デフォルト	説明
enabled	boolean	true	false で無効化（createRules() / createRulesAsync() 使用時のみ有効）
pageEntryAlias	string	'assets'	ページエントリの alias キー（未指定なら generator.pageEntryAlias）
pageEntrySubdir	string	'css'	alias 配下サブディレクトリ（未指定なら generator.pageEntrySubdir。空文字は alias 直下）
componentsDirs	string[]	['components']	コンポーネント層ディレクトリ（stylelint.base.paths.components を継承）
aliasRoots	object	–	ページエントリとリンク解決の alias map（spiracss.aliasRoots を継承）
naming	object	–	命名規則（stylelint.base.naming を継承、未指定なら stylelint.class.naming にフォールバック）
external.classes	string[]	–	外部クラス除外（stylelint.base.external + stylelint.class.external をマージ）
external.prefixes	string[]	–	外部クラス除外（stylelint.base.external + stylelint.class.external をマージ）
cache	object	–	キャッシュサイズ（stylelint.base.cache を継承）

pageEntryAlias が aliasRoots に無い場合（または解決先が空）はスキップされます。

stylelint.placement

プロパティ配置（コンテナ / アイテム / 内部）を検証します。

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

設定一覧:

項目	型	デフォルト	説明
elementDepth	number	4	Element 連鎖の段数上限（createRules() / createRulesAsync() 使用時、未指定なら class.elementDepth を継承）
marginSide	'top' | 'bottom'	'top'	縦方向マージンの許可側
position	boolean	true	child Block の position 制限を有効にする
sizeInternal	boolean	true	width/height/min/max などを内部プロパティとして扱う
responsiveMixins	string[]	[]	@include で透過扱いにする Mixin 名
comments.shared	RegExp / string	/--shared/i	shared コメント判定（stylelint.base.comments を上書き）
comments.interaction	RegExp / string	/--interaction/i	interaction コメント判定（stylelint.base.comments を上書き）

stylelint.interactionScope

interaction セクション（// --interaction と @at-root & { ... }）の配置ルールを検証します。

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

interaction セクションは常にルート Block 直下に配置します（設定で無効化できません。@layer/@supports/@media/@container/@scope のラッパー内でも可）。

設定一覧:

項目	型	デフォルト	説明
pseudos	string[]	[':hover', ':focus', ':focus-visible', ':active', ':visited']	検証対象とする擬似クラス
requireAtRoot	boolean	true	@at-root & { ... } と & 起点のセレクタを必須化
requireComment	boolean	true	// --interaction コメントを必須にするか
requireTail	boolean	true	interaction ブロックを末尾に置くか
commentOnly	boolean	false	コメント付きブロックのみ検査するか
comments.shared	RegExp / string	/--shared/i	shared コメント判定（stylelint.base.comments を上書き）
comments.interaction	RegExp / string	/--interaction/i	interaction コメント判定（stylelint.base.comments を上書き）

stylelint.interactionProps

interaction セクション内の transition / animation 宣言と、transition 対象プロパティの整合を検証します。

stylelint: {
  interactionProps: {
    // comments.shared / comments.interaction の個別指定が必要ならここで上書き
    // comments: { shared: /--shared/i, interaction: /--interaction/i }
  }
}

設定一覧:

項目	型	デフォルト	説明
comments.shared	RegExp / string	/--shared/i	セクションコメントの個別指定（stylelint.base.comments を上書き）
comments.interaction	RegExp / string	/--interaction/i	セクションコメントの個別指定（stylelint.base.comments を上書き）
naming	object	–	命名規則（stylelint.base.naming を継承、未指定なら stylelint.class.naming にフォールバック）
external.classes	string[]	–	外部クラスを除外（stylelint.base.external + stylelint.class.external をマージ）
external.prefixes	string[]	–	外部クラスを除外（stylelint.base.external + stylelint.class.external をマージ）
cache	object	–	キャッシュサイズ（stylelint.base.cache を継承）

stylelint.keyframes

@keyframes の命名と配置ルールを検証します。

stylelint: {
  keyframes: {
    enabled: true,
    actionMaxWords: 3,
    blockSource: 'selector',
    blockWarnMissing: true,
    sharedPrefixes: ['kf-'],
    sharedFiles: ['keyframes.scss'],
    ignoreFiles: [],
    ignorePatterns: [],
    // ignorePatterns に一致した keyframes の配置チェックをスキップするか（デフォルト: false）
    ignoreSkipPlacement: false
  }
}

設定一覧:

項目	型	デフォルト	説明
enabled	boolean	true	false の場合はこのルールを無効化（createRules() / createRulesAsync() 使用時のみ）
actionMaxWords	number	3	action の語数上限（1〜3）
blockSource	'selector' | 'file' | 'selector-or-file'	'selector'	Block 名の取得元（selector は最初の root Block、file はファイル名、selector-or-file はフォールバック）
blockWarnMissing	boolean	true	Block を判定できない場合に警告するか
sharedPrefixes	string[]	['kf-']	共有 keyframes の prefix
sharedFiles	(string | RegExp)[]	['keyframes.scss']	shared keyframes を許可するファイルパターン（文字列は suffix 判定）
ignoreFiles	(string | RegExp)[]	[]	keyframes ルールを無視するファイルパターン（文字列は suffix 判定）
ignorePatterns	(string | RegExp)[]	[]	keyframes 名を無視するパターン（文字列は RegExp として解釈）
ignoreSkipPlacement	boolean	false	ignorePatterns に一致した keyframes の配置チェック（root/末尾）をスキップする

stylelint.pseudo

疑似クラス / 疑似要素を & にネストして書くルールです。

stylelint: {
  pseudo: {
    enabled: true
  }
}

• 例: .btn { &:hover { ... } }, .btn { &::before { ... } }
• 不可: .btn:hover { ... }, & > .btn:hover { ... }

設定:

項目	型	デフォルト	説明
enabled	boolean	true	false の場合はこのルールを無効化（createRules() / createRulesAsync() 使用時のみ）

stylelint.rel

@rel リンクコメントのルールを定義します。

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

設定一覧:

項目	型	デフォルト	説明
requireScss	boolean	true	childDir 配下の SCSS で @rel を必須にするか
requireMeta	boolean	true	@include meta.load-css("<childDir>") を含む親 Block で先頭コメントを必須にするか
requireParent	boolean	true	子→親の @rel を必須にするか（requireMeta / requireScss が有効な場合のみ）
requireChild	boolean	true	親→子の @rel を必須にするか
requireChildShared	boolean	true	shared セクション内でも子 @rel を必須にするか
requireChildInteraction	boolean	false	interaction セクション内でも子 @rel を必須にするか
validatePath	boolean	true	パスの実在検証を行うか
skipNoRules	boolean	true	セレクタルールが無い SCSS をスキップするか
childDir	string	'scss'	子 Block の SCSS を置くディレクトリ名（createRules() / createRulesAsync() 使用時のみ generator.childScssDir が未指定時のフォールバック）
fileCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	'preserve'	子 @rel コメントで期待するファイル名ケース（childDir を含まないパス向け）
childFileCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	undefined	@rel パスに childDir を含む場合のファイル名ケース（未指定なら fileCase にフォールバック）
aliasRoots	object	← top-level	@rel エイリアスの解決ルート
comments.shared	RegExp / string	/--shared/i	セクションコメントの個別指定（stylelint.base.comments を上書き）
comments.interaction	RegExp / string	/--interaction/i	セクションコメントの個別指定（stylelint.base.comments を上書き）

補足:

• エイリアスの解決は aliasRoots を参照します（validatePath: true の場合）
• requireParent は requireMeta が有効で @include meta.load-css(...) を含む親 Block、または requireScss が有効で childDir 配下にある SCSS の場合にのみ発火します
• fileCase / childFileCase は .scss に加えて *.module.scss（CSS Modules）も許容します

詳細は SpiraCSS Comment Links を参照してください。

htmlFormat

HTML にプレースホルダを付与する際の出力属性を制御します。

htmlFormat.classAttribute

設定一覧:

項目	型	デフォルト	説明
classAttribute	'class' | 'className'	'class'	出力するクラス属性

補足:

• 入力の class / className はこの設定に合わせて統一されます
• 内部では class / className を一時的に data-spiracss-classname に変換して処理し、出力時に設定値へ戻します
• ファイル拡張子などの自動判定は行いません

jsxClassBindings

JSX の class / className バインディングの解釈を制御します（HTML CLI / VS Code）。

jsxClassBindings.memberAccessAllowlist

設定一覧:

項目	型	デフォルト	説明
memberAccessAllowlist	string[]	undefined	member access のベース識別子許可リスト（例: styles.foo）。設定時は許可されたベースのみクラスとして扱います。

補足:

• 未指定の場合は member access を許可します
• 空配列の場合は member access の抽出を行いません
• HTML→SCSS 生成 / プレースホルダ付与の両方に適用されます

generator

HTML→SCSS 変換機能の設定です。

設定一覧:

項目	型	デフォルト	説明
globalScssModule	string	'@styles/partials/global'	各生成 SCSS の先頭に @use "<value>" as *; を挿入（root mode のルート Block SCSS では直後に @use "sass:meta"; が続きます）
pageEntryAlias	string	'assets'	ページエントリコメントのエイリアス
pageEntrySubdir	string	'css'	ページエントリコメントのサブディレクトリ
rootFileCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	'preserve'	ルート Block のファイル名ケース
childFileCase	'preserve' | 'kebab' | 'snake' | 'camel' | 'pascal'	'preserve'	子 Block のファイル名ケース
childScssDir	string	'scss'	子 Block SCSS の出力ディレクトリ
layoutMixins	string[]	[]	レイアウト用 Mixin の配列

例:

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

補足:

• pageEntryAlias / pageEntrySubdir: root mode のルート Block SCSS ファイル先頭（ヘッダ）に // @assets/css/index.scss 形式のコメントを出力（selection mode では // @rel/(parent-block).scss が出力されます）
• pageEntrySubdir: 空文字の場合は // @assets/index.scss のようにサブディレクトリを省略
• rootFileCase: 子 Block には適用しない
• childFileCase: 子 Block のファイル名と @rel コメントに適用
• layoutMixins: 配列の要素数だけ @include ブロックを生成（デフォルト: 無効）