設定オプション
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 のワークスペースフォルダ
- Stylelint:
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'] |
コンポーネント層ディレクトリ(createRules使用時に class/pageLayer へ適用。未指定時は aliasRoots.components にフォールバック) |
stylelint.class
クラス命名規則とセレクタ構造のルールを定義します。
設定一覧:
| 項目 | 型 | デフォルト | 説明 |
|---|---|---|---|
elementDepth |
number | 4 |
Element 連鎖の段数上限 |
childCombinator |
boolean | true |
Block 直下に > を必須化 |
childNesting |
boolean | true |
子要素は Block 内でネスト必須 |
rootSingle |
boolean | true |
1 ファイル 1 ルート Block |
rootFile |
boolean | true |
ルート Block 名とファイル名一致 |
scssRootStyle |
'class' | 'scope' | 'scope-explicit' |
createRules() が generator.scssRootStyle から取得 |
scope 設定時はコンポーネントルートに @scope が必要。子 Block ディレクトリ内のすべての @scope は全設定でエラー |
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'] |
コンポーネント層として扱うディレクトリ(stylelint.base.paths.components を継承。未指定時は createRules が aliasRoots.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 を継承。未指定時は createRules が aliasRoots.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', marginSideTags: true, position: true, sizeInternal: true, responsiveMixins: [] }}設定一覧:
| 項目 | 型 | デフォルト | 説明 |
|---|---|---|---|
elementDepth |
number | 4 |
Element 連鎖の段数上限(createRules() / createRulesAsync() 使用時、未指定なら class.elementDepth を継承) |
marginSide |
'top' | 'bottom' |
'top' |
縦方向マージンの許可側 |
marginSideTags |
boolean | true |
タグセレクタのルールにも marginSide チェックを適用する |
position |
boolean | true |
child Block の position 制限を有効にする |
sizeInternal |
boolean | true |
width / height / inline-size / block-size / 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 を参照してください。
htmlLint
HTML 構造 lint と HTML→SCSS 生成時のクラス所有チェックを制御します(HTML CLI / VS Code)。
htmlLint.classlessTagCheck
設定一覧:
| 項目 | 型 | デフォルト | 説明 |
|---|---|---|---|
classlessTagCheck |
boolean | true |
許可リストにないHTMLタグへのクラス必須チェック |
false にするとクラスなしタグ検査だけを無効化し、その他のHTML構造チェックは維持します。
htmlLint.classlessTagAllowlist
設定一覧:
| 項目 | 型 | デフォルト | 説明 |
|---|---|---|---|
classlessTagAllowlist |
string[] | 組み込みリスト | SpiraCSS のクラスを意図的に付けない追加HTMLタグ名 |
組み込みのクラスなし許可タグは picture、source、img、track、map、area、br、wbr です。設定したタグは組み込みリストに追加されます。
SVG / MathML のルート要素には引き続きクラスが必要です。SVG / MathML 固有の描画内部要素には SpiraCSS のクラスは不要ですが、foreignObject や HTML の annotation-xml など HTML との統合点は HTML 文脈としてチェックします。template、文書メタデータ、ネイティブコントロール内部、パーサーが生成するテーブル構造は、この許可リストとは別に処理されます。
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 のファイル名ケース |
scssRootStyle |
'class' | 'scope' | 'scope-explicit' |
'scope-explicit' |
コンポーネントルート SCSS の書式。meta で読み込む 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ブロックを生成(デフォルト: 無効)
scope のルート書式
v0.4.x からの移行: v0.5.0 ではコンポーネントルートのデフォルトを scope-explicit に変更します。従来のルート生成・ルート書式の lint 挙動を維持する場合は、generator.scssRootStyle: 'class' を指定してください。子ファイル内の scope は全設定で禁止し、既存の子 scope は手動で移行します。クラス形式の子と HTML lint は変更しません。スタイルシートや CSS 詳細度を、lint 修正のために自動変換しないでください。
generator.scssRootStyle は HTML CLI と VS Code 拡張で共通です。デフォルトは :scope で包む scope-explicit です。適用するのは root mode で生成するコンポーネントルート SCSS だけです。独立した子 Block がある場合に限り、meta.load-css() でそのスタイルを読み込みます。読み込まれる Block の各ファイルとセレクタはクラス形式のままで、個別の scope にはしません。selection mode も、コンポーネントルートから読み込むためのクラス形式を生成します。class は従来形式を選択し、scope は @scope 直下に宣言と子セレクタを書きます。
/* class(選択可能) */.test-card { padding: 20px; > .title { color: red; } }
/* scope */@scope (.test-card) { padding: 20px; > .title { color: red; } }
/* scope-explicit(デフォルト) */@scope (.test-card) { :scope { padding: 20px; > .title { color: red; } } }Stylelint は全形式を認識し、既存の Block の所有関係・ファイル名・配置・セクション・リンク・ページ層・keyframes の検査を適用します。:scope のラッパーは必須ではありません。:scope:hover の :hover には、既存の疑似クラスのネストと interaction のルールが適用されます。適切な interaction セクション内で :scope { &:hover { ... } } と記述してください。テーマ用の @scope 内に従来のコンポーネントを記述する形式も引き続き使えます。scope をネストしても、親ファイルから子 Block の内部を装飾することは許可されません。
デフォルトは Sass を通す SCSS の推奨形式です。明示的に選択する場合は次の設定です。
generator: { scssRootStyle: 'scope-explicit'}新規コンポーネントルート生成のデフォルトを scope-explicit に変更します。既存のスタイルシートは自動変換しません。従来の生成書式を維持する場合は class を選択してください。直接形式の scope も引き続き選べます。現在の Sass は @scope 直下の > .title などの先頭結合子に警告を出します。一方、padding: 20px などの直接宣言は別の機能で、CSS 仕様上認められています。この警告を理由に、有効な CSS を SpiraCSS lint エラーにしたり、:scope を必須にしたりはしません。
各書式の CSS 詳細度はそのまま保持します。直接宣言・:scope・& は、カスケード上で同じ意味に書き換えられるものではありません。既存の直接形式を自動的に :scope で包むことはしません。HTML クラス・HTML 構造 lint・HTML のネストは変更しません。
設定した childDir 配下の子・孫 Block ファイルはクラス形式に統一します。Stylelint は、この配置のファイル内のすべての @scope をエラーにします。テーマ用の囲み・index・partial も対象で、scssRootStyle の値や直接ルール設定の有無に関係なく適用します。これはネイティブ CSS の制限ではなく、SpiraCSS の安全な合成のための規約です。既存の子 scope は手動で移行してください。class を選んでもこの禁止は解除しません。
判定は import グラフではなくファイル配置に基づきます。設定したコンポーネント配置内では子ディレクトリのサブツリー全体を認識します。その配置外では childDir 直下のファイルだけを子として認識するため、深い配置を検査する場合は所有コンポーネントの配置を componentsDirs / aliasRoots.components に追加してください。ファイル名のない stdin では子の配置を判定できません。子コードの lint にはファイル名を渡してください。
Sass の安全性と詳細度: 親のスタイルルール内で meta.load-css() すると、Sass は子ルールへ親セレクタを前置します。デフォルトの親の :scope 内で読む子の :scope は、一致しない :scope :scope になります。scope-explicit では include をコンポーネントルートの :scope 内に維持し、読み込むファイルをクラス形式にしてください。include を @scope 直下へ移すと、子の詳細度が (0,2,0) から (0,1,0) に下がるため、修正として案内しません。直接形式の scope は、明示的に選択した低詳細度の書式を維持します。lint は Sass のコンパイルや任意の import グラフの解決を行わず、カスケードを自動変換しません。
root mode のコンポーネントは、独立した子 Block がなくてもコンポーネントルートです。設定されたルート書式に従い、不要な meta.load-css() 呼び出しだけを省略します。子の追加・削除によってルート書式を変えることはありません。
createRules() / createRulesAsync() は、この設定を spiracss/class-structure にも渡します(デフォルト: scope-explicit)。scope 設定時はコンポーネントルートに scope を要求し、クラス形式ならエラーです。ただし scope 本体は直接形式・:scope 形式の両方を許可します。読み込まれる子 Block ファイルはクラス形式にします。判定は設定されたコンポーネント配置の childDir 外、または meta.load-css(childDir) 呼び出しを基準とし、ページエントリ・子ファイルは除外します。コンポーネント配置の明示設定は、従来の assets/css のページ除外より優先します。ルートの scope 要求と子の scope 禁止は rootSingle・rootFile のオン/オフとは独立です。@container・@layer・@media・@supports で囲んでも回避できず、それ自体をエラーにはしません。診断には設定値または子ディレクトリ・対象 Block・原因・修正例を含めます。ルールを直接設定する場合も spiracss/class-structure の scssRootStyle で指定でき、省略時はルート書式を強制しませんが子 scope は禁止します。stylelint.class.scssRootStyle を明示すると生成設定より優先します。
ルートファイル内の入れ子 scope は、所有 Block を識別できる必要があります。コンポーネント名に一致するファイル名を基準とし、rootFile: false ではコンポーネントディレクトリ名も利用します。どちらも利用できない場合(stdin を含む)は、テーマの囲みを external.classes / external.prefixes で宣言してください。判定不能は構造検査の免除ではなくエラーです。