コンテンツにスキップ

HTML CLI

AI エージェントや自動化スクリプト向けに設計された CLI ツールです。
SpiraCSS の HTML 解析と SCSS 生成のコアロジックを提供します。

  • 主な用途: AI エージェント(Codex、Claude Code など)が HTML から SCSS を生成する際に呼び出す
  • 副次的な用途: VS Code 拡張がエンジンとして内部で使用

人間がターミナルから直接使うことは想定していません。
手動で SCSS を生成する場合は VS Code 拡張を使用してください。

インストール

v0.6.0 は Node.js >=24.22.3 <25 が必要です。 v0.5.1 は Node.js >=24.22.2 <25 が必要です。 v0.5.0 は Node.js >=24.15.0 <25 が必要です。

v0.6.0 は以下の source-aware engine を追加します。この API と診断は 0.5.1 では利用できません。

ターミナルウィンドウ
yarn add -D @spiracss/html-cli
ターミナルウィンドウ
npm install -D @spiracss/html-cli

コマンド一覧

コマンド 説明
spiracss-html-to-scss HTML から SCSS を自動生成
spiracss-html-lint HTML 構造が SpiraCSS ルールに従っているか検証
spiracss-html-format プレースホルダクラス(既定 block-box / element)を付与

spiracss-html-to-scss

HTML / テンプレートから SCSS ファイルを自動生成します。デフォルトで構造 lint を実行し、エラーがある場合は終了します(--ignore-structure-errors で無視)。

基本的な使い方

ターミナルウィンドウ
# ルートモード(コンポーネントのルートを 1 つの Block として扱う)
yarn spiracss-html-to-scss --root path/to/file.html
# 選択モード(選択断片として扱う)
yarn spiracss-html-to-scss --selection path/to/fragment.html
# 標準入力から
cat file.html | yarn spiracss-html-to-scss --selection --stdin --base-dir src/components/sample

オプション

オプション 説明
--root コンポーネントのルートを 1 つの Block として扱う(デフォルト)
--selection 選択断片として扱う
--stdin 標準入力から HTML を読み取る
--format FORMAT 0.6.0 では html、webc、jsx、tsx、astro、vue を明示指定します。省略時は標準入力を html として扱い、ファイルは拡張子から形式を推定します。
--base-dir PATH SCSS 出力先ディレクトリ(入力ファイル指定時は上書き先、--stdin 使用時は省略でカレント)
--dry-run ファイルを書き込まず、出力パスだけを表示
--json 生成結果を JSON で標準出力(ファイル作成なし、AI/スクリプト向け)
--ignore-structure-errors 構造 lint のエラーを無視して生成を続行
--allow-provisional spiracss.config.js が無い場合にデフォルト設定で続行

補足:

  • --root と --selection は同時に指定できません。どちらも省略すると root モードになり、--root は明示的な互換用フラグとして利用できます
  • エラーメッセージの文言は変更される可能性があるため、文字列一致に依存しないでください

注意:

  • --root モードは入力から 1 要素をルートとして解釈し、その要素を起点に配下を含めて生成します。該当要素に class が無い場合は生成できずエラーになります。コンポーネント単位の入力に合わせて使ってください
  • --selection モードで class 属性を持つ要素が 1 つも無い場合はエラーになります
  • --ignore-structure-errors を付けても、ルート要素が存在しない / 複数ある / class が無いなど、生成に必要な前提を満たさない場合はエラー終了します。続行した場合も ignored は正常 PASS ではないため終了コードは 1 です
  • 設定ファイルが無い場合はデフォルトで停止します。--allow-provisional で続行できますが、JSON は status: "provisional"、ok: false、終了コード 1 になります
  • JSON の status は pass / provisional / ignored / failed / blocked で、ok: true になるのは pass だけです

出力例

your-component/
├─ hero-section.scss ← ルート Block
├─ scss/
│ ├─ feature-card.scss ← 子 Block
│ └─ index.scss ← @use 自動マージ
└─ your-template.html

出力先のルール

  • 入力ファイル指定: 入力ファイルと同じディレクトリ(--base-dir 指定時は上書き)
  • --stdin: --base-dir(省略時はカレントディレクトリ)
  • 子 Block は childScssDir(既定 scss)

SCSS ルート書式(v0.5.0+)

generator.scssRootStyle は VS Code 拡張と共通です。デフォルトは scope-explicit(@scope 内を :scope で包む)です。直下形式なら scope、従来のルート書式なら class を選びます。v0.5.0 より前のバージョンでは使えない設定です。

設定に従うのは root mode のコンポーネントルートだけです。meta.load-css() で読む子 Block のファイルと selection mode の出力はクラス形式です。独立した子がないルートも設定に従い、不要な meta 呼び出しだけを省略します。既存ファイルや HTML クラスを自動変換することはありません。

generator: {
scssRootStyle: 'scope-explicit'
}

以下の変換例は v0.5.0 のデフォルトのルート書式です。子ファイルはクラス形式を維持します。Stylelint の createRules() 連携では scope 設定時にコンポーネントルートへ scope を要求し、ルート本体は直接形式・:scope 形式を許可します。子 Block ディレクトリ内のすべての @scope は全設定で lint エラーです。詳細は scope の設定 を参照してください。

読み込む子はクラス形式を維持してください。Sass はスタイルルール内で読む子へ親セレクタを前置し、デフォルトの親の :scope 内で読む子の :scope は、一致しない :scope :scope になります。子の詳細度が変わるため、ルートの include を移動して修正しないでください。既存の子 scope は診断の修正方法に従って手動移行します。

生成仕様の補足

  • 同一 base class が複数ある場合、modifier / variant / state / aria は重複排除して統合されます
  • 予約キーは selectorPolicy で変更できます(例: data-theme, data-status, aria-hidden, aria-expanded)
  • data モードでは variant は基本構造に出力されます(インタラクション初期値は手動で interaction に移してよい)

spiracss-html-lint

HTML 構造が SpiraCSS の Block / Element / Modifier ルールに従っているかを検証します。

設定ファイルが無い場合はデフォルトで停止します。明示的に許可する場合だけ --allow-provisional を使ってください。その場合も status: "provisional"、ok: false、終了コード 1 となります。

基本的な使い方

ターミナルウィンドウ
# コンポーネントのルート要素として検証
yarn spiracss-html-lint --root path/to/file.html
# 標準入力から断片を検証
cat fragment.html | yarn spiracss-html-lint --selection --stdin
# JSON 形式で結果を取得
yarn spiracss-html-lint --root path/to/file.html --json

オプション

オプション 説明
--root コンポーネントのルートを 1 つの Block として扱う(デフォルト)
--selection 複数の選択断片として扱う
--stdin 標準入力から HTML を読み取る
--json { file, mode, ok, errors[] } 形式で JSON 出力

Source-aware engine (0.6.0)

lint / 生成は拡張子から HTML(.html / .htm)、WebC、JSX、TSX、Astro、Vue を選び、--format html|webc|jsx|tsx|astro|vue で明示できます。stdin の既定は従来どおり HTML です。未知拡張子は FORMAT_UNSUPPORTED、正式 parser の構文失敗は PARSE_ERROR で blocked とし、HTML や legacy に黙ってフォールバックしません。.ejs / .njk / .nunjucks / .svelte は従来の限定抽出経路(parserPath: "legacy")で、正式な6形式と同じ保証ではありません。

HTML / WebC は断片、Astro は frontmatter / script / style を除く template、Vue は SFC の template または snippet が検査単位です。JSX / TSX は返却構文の根拠がある式を単位とし、callback の return や補助変数内の JSX を一律に component root にしません。同一 scope・単一 const・直接 children への参照1か所の補助要素は可視の親に結び、それ以外の不確定な関係だけを未解決とします。

JSX の className はスカラであり、素の配列 / object は Vue / Astro の class list と同義ではありません。Vue は class + :class、Astro は class + class:list を扱います。同一ファイル import と shadowing なしを確認した clsx / classnames だけを有限評価し、任意 JavaScript や推測した cn を実行しません。三項 / && / || の枝の相関を保ち、関連する未知値は pass にしません。WebC の : 属性式は確認済み serializer の意味に従い、元位置を確定できない式は unresolved です。

JSON の5status(pass / provisional / ignored / failed / blocked)は維持し、pass だけが ok: true・exit 0 です。解析後は format / parserPath / coverage / metrics を追加します。markup・式・scriptのparse回数は別々に数えます。standalone Astroは公式同期 convertToTSX、Babel、公式source mapを使い、astroConversions: 1 と generatedParses: 1 を別計数します。coverage.scope: "source" であり、props転送・slot展開・描画後DOMは範囲外として件数を示すだけで検査済みとはしません。範囲内の未解決は failed、構文(PARSE_ERROR)・parserの資源/内部失敗(PARSER_RUNTIME_ERROR)・設定不正(CONFIG_INVALID)・開始不能・深度安全ガードは blocked です。資源失敗をAstro構文不正の根拠にしたり、クラス改名で直そうとしたりしないでください。

Vueでは、class転送が未解決のcomponent要素を元sourceの要素ごとに1回だけ数えます。bind数や v-else の枝数では増えません。native要素はこの件数に含めず、静的なcomponentだけなら0です。JSXは未知spreadごとに数えるため、形式間で件数を比較できません。数えた箇所でも、可視sourceから証明できる違反は報告します。ESLintはcoverageを公開しません。

診断は code に加え、kind、reason、repair.conditions、当該判断に効いた repair.effective、必要に応じた condition と repair.missingInformation、補助リンク docs を返します。実効設定は naming / customPatterns / external / selectorPolicy / mode などで、空のobjectの場合もあります。元UTF-16半開範囲 range: [start, end] と position は、元sourceに帰属する証拠がある場合だけ付けます。

MULTIPLE_ROOT_ELEMENTS は、root modeがcomponent rootを1つだけ想定していることを示します。repair.effective は { mode: "root" } で、repair.missingInformation は意図したrootまたはselection modeの選択を確認します。rootを1つに決めるか、複数componentが意図した入力ならselection modeで検査してください。正しいクラスの改名・削除は不要です。

HTML / WebCの開始タグで class または selectorPolicy の設定属性を繰り返すと、SOURCE_RELATION_UNRESOLVED でfailedになります。元markupで意図した属性を確認して再lintしてください。この診断だけで勝者を選んだり、正しいクラスを改名したりしません。全属性の重複を検査する機能ではありません。

元位置の根拠がないfilelevelのparser / runtime / config / unsupported報告では、[0, 0] や1:1を捏造せず、range / position の両キーを省略します。JSON consumerは省略を扱ってください。点だけ分かる失敗は range: [n, n] とし、1文字幅を作りません。parserが終端を返す場合はその終端を保ちます。根拠のあるsource先頭0・EOF位置は維持します。ESLintが表示上必要とするfile先頭位置は元sourceの帰属証拠ではありません。深度・未対応の修復案内は専用の内容で、命名変更を求めません。

VueではCLIがcompilerの元位置を、ESLint接続がhost parserの範囲を使います。対応済みの静的なclass記述では位置が一致することをテストで確認していますが、文字参照を含むbinding式、script/式の構文エラー、parserの回復では、backendの違いにより診断や位置が異なる場合があります。Vue文法全体への対応や全診断の一致を意味しません。

正常Astroは astroConversions: 1 / generatedParses: 1 / scriptParses: 0 です。生成parse失敗時だけ元frontmatterをTypeScript / TSX両文法で確認する場合があり、public metricsは追加parseの実数を維持します。元構文原因を証明できないgenerated-only失敗は PARSER_RUNTIME_ERROR のblockedですが、原因不明の案内とし、根拠なしにfrontmatter編集や資源復旧を求めません。生成側の行列を元source位置として示すこともありません。

AI修正ループの受入は「診断の範囲・理由・repair.effective・repair.conditions・必要に応じた repair.missingInformation を読む → 意図の決まった最小変更 → 同じ形式 / mode / config で再lintしてpass」です。全文ガイド再読を前提にせず、意図が一意でない場合は候補や不足条件を確認します。動的挙動やクラスを勝手に削除・改名してpassにせず、万能な構造autofixも提供しません。

UNCLASSIFIED_CLASS_TOKEN は正常な先頭baseでなく後続の未分類tokenを指します。lintは出現を統合しないため、以前見逃した兄弟等の診断が増え、既定の生成が停止する場合があります。生成時だけ集約し、許可入力のファイル名 / 順序 / 内容とformat互換は維持します。命名 / 所属 / 末端Block / SCSS scope方針は変更しません。HTMLのBlock設計深度は無制限で、MAX_DEPTH_EXCEEDED(256)は実装安全ガードです。

APIは await loadMarkupParsers(formats) で呼出側のhandleを準備後、lintMarkup(source, { format, mode, parsers, config }) を同期実行します。既存同期APIのsignatureは維持します。configは既存 loadProjectOptions(projectRoot) で事前解決し、configStatus !== 'loaded' の既定値を意図せず正式設定にしないでください。

任意subpath @spiracss/html-cli/eslint は単一 markup rule(error推奨)と createMarkupEslintConfig(config, htmlParser) を公開し、通常CLIにESLintは不要です。HTML / WebCは @html-eslint/parser とhelperでflat config接続します。他形式もhost ASTを直接共通validatorへ渡し、rule内でmarkupや供給式ASTを再parseしません。WebCは薄いhost parser wrapperで関連する動的属性式を初めてparseし、parser servicesで渡します。wrapperを省いて不足ASTを静的扱いにはしません。構文でruleが呼ばれないときはhost固有のfatal code / 位置 / 非成功を確認します。

ESLint cacheとRegExpのcustom namingを併用する場合は、対象host parserとfilesを指定した createMarkupEslintConfig(config, parser, files) を使います。patternのsource / flagsをrule optionsへ直列化し、その変更がcache identityに反映されます。全設定や外部状態のdigestではありません。

回復と代替展開の境界

全到達枝で有効な非externalのBlock / Element baseが先頭と確定した後、lint・生成・所有者に影響しない既知optional tokenだけを直積の前に除きます。modifier / 三項一般の順序、先勝ち診断の位置、枝guardは維持し、未知spreadや所有者が変わる場合は従来の有限経路です。classExpressionProducts は式内の代替組の試行数、inertOptionalTokens は積前に除いた静的token数です。solverや上限引上げではなく、予約属性の代替は別の安全budgetのままです。

Astroの終了タグ省略(li / p / td等)は公式変換が受理しても、source lintに使える木・範囲を保てない場合があります。省略を証明できた局所だけ SOURCE_RELATION_UNRESOLVED と明示closeを案内します。生成parse成功後に境界・属性・親子関係を照合できない場合は、その範囲の式・コメント・開閉対応の確認を求め、解析/資源失敗・命名不備・既存closeの不足と断定しません。局所化できれば検証済み開始範囲を指し、できなければ位置を捏造せず原因未確定のblockedです。独立検証できる兄弟は検査しますが、不確実な範囲は未検査で、所属・root数を断定せず、文書生成もできません。本物のbackend / source map欠損はruntime、実構文エラーは根拠のある元token / frontmatter範囲とし、rule前のhost構文拒否とも区別します。

Astroの終了境界は元sourceとの対応を確認できる必要があります。metadata / scriptだけのrootは従来どおり「No source element found」です。native HTMLのclose名だけASCII大小文字非依存とし、componentや未証明の外部namespaceへ広げません。現Astro ESLint parserは </DIV> をrule前fatalにするため、standaloneが受理してもhost成功とはしません。

optional extraのprefix判定より前に、各hostの有効class合成順を確定します。Vueは属性順を維持し、後の静的classから前の動的listへbaseを貸しません。Astroの直接classは直接 class:list より前に畳み込まれ、listの位置で出力されます。native要素のspread classと直接listは別々のHTML class属性で、実際に出力された最初の属性が勝ちます。component propsの同名property上書きはcompilerの畳込み後のkeyに起き、その後 class → class:list 順で正規化します。後続class spreadは、別keyのlist内に畳込み済みの元classを消しません。これらを同値として扱いません。

native Astroでは既に検査するclass / selector keyと必要なinput typeだけ、実出力で選びます。静的 className は字面のclassName(HTML canonical名classname)のまま、動的 / shorthand / backtick / spreadのclassNameだけclass aliasです。このAstroのalias選択後に、実emitするnative HTML名だけASCII小文字化します。component props / JSX / Vueのkey処理を説明するものではありません。nullishな属性値は非出力、通常classの空文字・空白は出力、falseは文字列falseを出力します。class:list はclsx結果が空なら非出力([] / false)、空白文字列は出力です。既知object spreadは同名keyの上書き後もJSのkey挿入順を保持し、lint / SCSSは同じ実効selector代替を使います。未対応scalar arrayの保守的未解決は維持します。

JSX / TSXとAstro componentでは、null または証明済み未束縛 undefined のspreadはlint・生成とも寄与せず、省略と同じ結果です。native Astroで同様に扱うのは、証明済み未束縛 undefined だけです。native Astroの null、shadowingされた undefined、その他の未知spreadは未知のままです。

hidden inputのtypeは、classless検査が実際に必要な枝だけで判断します。JSX既知propsは後勝ち、native Astroは最初のemit、Vueの同一props群では先勝ちで、引数なしv-bind / mergeProps群とは別です。確定hiddenはASCII大小文字非依存、未知typeは局所 SOURCE_RELATION_UNRESOLVED で静的根拠またはhidden / 非hidden意図を求め、class追加・命名変更を断定しません。class有り / classless checkoffでは無関係なtype診断を増やしません。証明済み未束縛undefinedだけ値では不在・述語では偽とし、束縛済み / 未証明は未知です。classExpressionProducts は外側結合と不一致guardを含む試行組を数え、budgetは変更しません。

既存の検査keyでは、存在・値・修復位置を枝ごとの別の事実として保持します。属性禁止は実際の出力元属性全体、値違反は値範囲を指します。nullableな未知値だけでは禁止属性の存在を断定せず、存在が確定しても勝者が一意でなければ修復rangeを捏造しません。命名規則があるvariant / stateのdata値が未知なら局所未解決のままです。既定dataモードの設定済み動的ARIA(open、String(open))は、他の違反がなければlintはpassです。ARIA値の命名規則や真偽文字列への強制書換えは追加しません。書換えでnullableな「属性なし」が変わる場合があります。未知props転送全体・必要なinput typeの判断・明示ignore / 直接helperの契約は従来範囲のままです。

生成するのは、到達可能な既知の勝者だけです。Astroの <div class="card-list" {...{"aria-expanded":open}} aria-expanded="true" aria-expanded="never"/> はlintがpass、既知のtrue selectorだけ生成し、coverage.generationUnenumeratedSites: 1(動的値1箇所は未列挙)となります。生成対象の要素と設定keyの組を1箇所として数え、枝数・ファイル数で重複せず、非適用・確定不在・確実に負ける未知は数えません。errors・未解決件数・status・終了コードとは別です。JSONは既存coverageへ含め、生成CLI通常表示とVS Code Outputには非ゼロ時だけ1行表示します。ESLintは生成しないので診断を追加しません。既存同期APIのGeneratedFile[]は形を変えず、件数を持ちません。CLI / 拡張と同様、既存の生成前lint結果から取得し、表示のための再parse・再集計はしません。

設定済みdata属性の動的値は未解決となり、0.5.1と結果が変わる場合があります。意図を保てる場合だけ既知の有効値や対応する有限分岐を示し、未知の実値を正しいと仮定したり、診断だけを消す改名をしたりしません。

Vueの設定済scalar selector keyと必要なinput typeは、同一props群では先勝ち、引数なしv-bind / mergePropsの群間では後勝ちです。合法値もlint / SCSSが同じ実効勝者を使い、負けたselectorは生成しません。class / style / eventのmergeへ広げません。対応済み単純list objectはkey初回挿入位置・最後の値をtoken / emit両方で使い、guardが偽のx && valueはclass:listへ寄与しません。directiveは元key完全一致のclass:listだけで識別し、HTML名の小文字化後のCLASS:LISTから再認識しません。

VueのHTML名前空間にあるnative要素では、属性・静的bind引数・引数なし v-bind のobject literal keyを、検査対象のscalar keyについてASCII大小文字を区別せず比較します。componentとSVGなどの外部名前空間では書かれた綴りを保ちます。class listとして扱うのはcompile後のkeyが class と完全一致する場合だけです。nativeの Class、:Class、:class.prop、.class、:class.attr は属性全体の範囲で DYNAMIC_CLASS_UNRESOLVED となり、classlessやrootの診断は連鎖しません。静的な Class="card-list" も安全側の過剰報告として未解決になります。理由文は汎用で綴りやtargetを説明するとは限りません。scalar全般の .prop / .attr / .camel 対応ではありません。

異なる綴りの2つのVue属性が同じ設定済みscalar keyに対応すると、後の属性全体が未解決となり、勝者は断定しません。同じ綴りの重複は両入口ともcompilerの PARSE_ERROR です。この衝突の保証は2属性までです。引数なし v-bind のobject literalを含む、3つ以上の供給元が絡む衝突は未対応です。

Astro shorthand Fragmentは元の区切りとsource上の関係を確認できる必要があります。未確定範囲は、確認済みの包含openingがあれば局所化し、なければ位置なしのblockedです。独立検証できた兄弟は検査しますが、不確実文書の生成はできません。

doctypeと最上位のshorthand Fragmentの間にraw textがある文書は、Astroの既知の未対応形です。standaloneは位置なし PARSER_RUNTIME_ERROR でblockedとなり、同じ入力でESLint hostはSpiraCSSの診断を出しません。hostが無診断でも、普遍的なpassやstandaloneの受理を意味しません。

供給HTML / WebC ASTが、元sourceの実終了タグを越えて後続の実要素をRAWTEXT / RCDATAへ吸収した場合は、局所 SOURCE_RELATION_UNRESOLVED とnative CLIの利用を案内します。正常なtext・命名・nestingの修正を求めず、失われた要素の再parse / 付け替えもしません。正当にEOFまでopaque textとなる入力は受理します。これは不正sourceの回復とは別の対応制約です。

HTML回復はselect脱落・table移動・非void自己終了を未解決として報告します。関連属性の重複は前述の別の報告です。回復後も既知の静的classを保持している一方で値の正確な範囲が分からない場合、その診断はtoken単位でなく元の属性全体の範囲を使うことがあり、回復の根拠は未解決のままです。属性引用符の未閉鎖(eof-in-tag)の一部では、standaloneの未解決に対して現在の供給HTML hostが同じ回復証拠を報告しない既知差があります。HTML全体の妥当性保証ではありません。元の引用符を閉じて同じhostで再検査してください。これらの報告は独立の回復parserを提供するものではありません。

Astro巨大入力の検証境界

astro-eslint-parser 3.2.0、@astrojs/compiler-rs 0.5.3、ESLint 10.14.0では、70,000要素のAstro入力がSpiraCSSルール無効でも45秒以内に完了しなかった既知制約があります。この時間はruleでなくhost側のもので、特定の上流bugを断定する根拠ではありません。

standaloneの完走は、巨大入力のhost対応や性能保証の根拠にはなりません。サイズcapやlegacy fallbackは設けていません。大きい入力で利用する前に、この制約を許容できるか確認し、実環境で検証してください。

注意:

  • --root モードは入力から 1 要素をルートとして解釈し、その要素を起点に配下も検証対象とします
  • 該当要素に class が無い場合は INVALID_BASE_CLASS になります
  • コンポーネント単位の入力に合わせて使ってください。複数のルート Block を検証する場合は --selection モードを使用してください

補足:

  • --root と --selection は同時に指定できません。どちらも省略すると root モードになり、--root は明示的な互換用フラグとして利用できます

エラーコード

コード 説明
INVALID_BASE_CLASS Block/Element の命名規則に違反、またはルート要素に class が無い/検証対象要素が見つからない
MODIFIER_WITHOUT_BASE Modifier クラスのみで基底クラスがない
DISALLOWED_MODIFIER data モード(variant/state 両方 data)で Modifier クラスが使われている
UTILITY_WITHOUT_BASE ユーティリティクラスのみで基底クラスがない
MULTIPLE_BASE_CLASSES 複数の基底クラスが存在
ROOT_NOT_BLOCK ルート要素が Block ではない
ELEMENT_WITHOUT_BLOCK_ANCESTOR Element が Block の子孫ではない
ELEMENT_PARENT_OF_BLOCK Element が Block の親になっている
DISALLOWED_VARIANT_ATTRIBUTE class モードで data-variant などのバリアント属性が使われている
DISALLOWED_STATE_ATTRIBUTE class モードで data-state/aria-* などの状態属性が使われている
INVALID_VARIANT_VALUE data モードのバリアント値が valueNaming に違反
INVALID_STATE_VALUE data モードの状態値が valueNaming に違反
DYNAMIC_CLASS_UNRESOLVED クラス値が動的で静的に検証できない
CLASSLESS_TAG_NOT_ALLOWED 許可リストにない HTML タグに class 属性がない
UNBALANCED_HTML HTML の開始・終了タグが不整合
MULTIPLE_ROOT_ELEMENTS ルートモードで複数のルート要素が検出された
MAX_DEPTH_EXCEEDED 安全上限を超過。SpiraCSS の HTML 深度ルールではなく status: "blocked" で返される

補足:

  • --selection モードでは class のないルートも検証します。許可リストにない classless タグは CLASSLESS_TAG_NOT_ALLOWED になり、class を持つ子孫は独立した検証対象として扱います
  • data-* / aria-* は予約キー(variant.dataKeys / state.dataKey / state.ariaKeys)のみ対象
  • data 値の命名は selectorPolicy.valueNaming と variant/state.valueNaming で検証
  • stylelint.base.external.classes / stylelint.base.external.prefixes に一致するクラスは外部扱い(base 判定から除外)
  • 先頭トークンが外部クラスで、外部以外のクラスが後続にある場合は INVALID_BASE_CLASS(Block/Element を先頭に置く必要あり)。外部クラスのみの要素は許容
  • variant.mode=class + state.mode=class は state 分離不可のため 全 modifier を variant 扱い
  • エラーメッセージの文言は変更される可能性があるため、文字列一致に依存しないでください

spiracss-html-format

HTML にプレースホルダクラスを付与して SpiraCSS 構造を整形します。

基本的な使い方

ターミナルウィンドウ
# ファイルから読み取り、別ファイルに出力
yarn spiracss-html-format path/to/file.html -o formatted.html
# ファイルから読み取り、標準出力
yarn spiracss-html-format path/to/file.html
# 標準入力から読み取り、ファイルに出力
cat file.html | yarn spiracss-html-format --stdin -o formatted.html

オプション

オプション 説明
--stdin 標準入力から HTML を読み取る
-o, --output PATH 出力先ファイルパス(省略時は標準出力)

出力属性は spiracss.config.js の htmlFormat.classAttribute に従います(既定は class)。
className を使う場合は className を指定してください。
内部では class / className を一時的に data-spiracss-classname に変換して処理し、出力時に設定値へ戻します。

付与されるクラス

すべての子孫要素を再帰的に走査し、SpiraCSS の Block > Element 構造に整形します。

  • 子要素を持つ要素 → Block プレースホルダを先頭に付与
  • 子要素を持たない要素(葉ノード) → Element プレースホルダを先頭に付与
  • 既に Block 名がある要素 → そのまま維持し、内部を再帰処理
  • Element 名があるが子を持つ要素 → Block 形式に変換(例: title → title-box)

※ ルート要素が Element の場合は Element → Block 変換を行わず、block-box title のように Block プレースホルダを先頭に付与します(Block/Element 以外でも同様)。

プレースホルダ名は blockCase / elementCase 設定に応じて変わります(両者は独立して設定可能):

case Block プレースホルダ Element プレースホルダ
kebab(既定) block-box element
camel blockBox element
pascal BlockBox Element
snake block_box element

注意:

  • Element は 常に 1 語です。elementCase=camel は小文字 1 語(例: element)、elementCase=pascal は大文字始まり 1 語(例: Element)のみ許可され、bodyText / BodyText のような内部大文字は使えません
  • customPatterns を指定している場合、プレースホルダ(block-box / element)が命名規則に合わない可能性があるため整合性を確認してください

制限事項

テンプレート構文(EJS <% %>, Nunjucks {{ }} {% %} {# #}, Astro frontmatter 等)を含む HTML は処理をスキップします。
これらの構文は HTML パース時に破壊される恐れがあるため、静的な HTML 断片に対してのみ使用してください。

プレースホルダ付与では JSX の class / className は静的に判定できる場合のみ対応します(文字列リテラル、${} 内が静的 member access または文字列リテラルのテンプレートリテラル、styles.foo / styles['foo'] / styles["foo"] のような member access)。jsxClassBindings.memberAccessAllowlist を設定している場合は、許可されたベース識別子のみクラスとして扱い、styles.layout.hero のようなチェーンは動的扱いにします。props.className や条件式、関数呼び出し、非静的な ${} を含む場合は HTML 全体の処理をスキップします。JSX/TSX をフォーマットする場合はバインディングをクラス文字列に正規化してプレースホルダを付与するため、CSS Modules のソースは上書きしない前提で使ってください。

テンプレート構文が検出された場合:

  • 標準出力モード(-o 未指定): 元の HTML をそのまま出力し、標準エラーに警告を表示
  • ファイル出力モード(-o 指定): ファイルへの書き込みをスキップし、標準エラーに警告のみ表示(mtime 更新を防止)
  • 断片 HTML で <template> / <textarea> の閉じタグが欠けている場合は挙動保証なし(明示検知は行いません)

変換仕様

変換例

<!-- 選択した HTML -->
<section class="hero-section">
<h1 class="title">Welcome</h1>
<p class="body">Introduction text...</p>
<div class="feature-card">
<h2 class="heading">Feature</h2>
</div>
<div class="cta-box">
<a class="link" href="#">Learn more</a>
</div>
</section>

↓ SpiraCSS 形式の SCSS を自動生成

hero-section.scss(ルート Block):

@use "@styles/partials/global" as *;
@use "sass:meta";
// @assets/css/index.scss
@scope (.hero-section) {
:scope {
@include meta.load-css("scss");
@include breakpoint-up(md) {
// layout mixin
}
> .title {
@include breakpoint-up(md) {
// layout mixin
}
}
> .body {
@include breakpoint-up(md) {
// layout mixin
}
}
> .feature-card {
// @rel/scss/feature-card.scss
@include breakpoint-up(md) {
// child component layout
}
}
> .cta-box {
// @rel/scss/cta-box.scss
@include breakpoint-up(md) {
// child component layout
}
}
// --shared ----------------------------------------
// --interaction -----------------------------------
// @at-root & {
// }
}
}

scss/feature-card.scss(子 Block):

@use "@styles/partials/global" as *;
// @rel/../hero-section.scss
.feature-card {
@include breakpoint-up(md) {
// layout mixin
}
> .heading {
@include breakpoint-up(md) {
// layout mixin
}
}
// --shared ----------------------------------------
// --interaction -----------------------------------
// @at-root & {
// }
}

scss/cta-box.scss(子 Block):

@use "@styles/partials/global" as *;
// @rel/../hero-section.scss
.cta-box {
@include breakpoint-up(md) {
// layout mixin
}
> .link {
@include breakpoint-up(md) {
// layout mixin
}
}
// --shared ----------------------------------------
// --interaction -----------------------------------
// @at-root & {
// }
}

scss/index.scss(子 Block 集約):

@use "cta-box";
@use "feature-card";
your-component/
├─ hero-section.scss ← ルート Block
├─ scss/
│ ├─ cta-box.scss ← 子 Block
│ ├─ feature-card.scss ← 子 Block
│ └─ index.scss ← @use 自動マージ
└─ your-template.html

対応テンプレート

※ このセクションは SCSS 生成 の対応範囲です。
プレースホルダ付与の制限は上記「制限事項」を参照してください。

テンプレート 対応状況
プレーン HTML 完全対応
Astro Front-matter を自動削除
EJS <% ... %> を自動削除
Nunjucks {{ }} / {% %} / {# #} を自動削除
JSX class / className から静的クラスを抽出
Vue / Svelte v-* / :prop などの属性を削除(v-bind:class などは残留する場合あり)

テンプレート構文は正規表現で除去します。

  • <%...%>(EJS)
  • {{...}} / {%...%} / {#...#}(Nunjucks)
  • JSX コメント {/*...*/}
  • JSX フラグメント <>...</>
  • <script>...</script> / <style>...</style> ブロック
  • dangerouslySetInnerHTML 属性
  • 属性スプレッド {...foo}
  • テンプレートリテラルの ${...}(class / className 内は静的 member access や文字列リテラルを抽出する場合あり)

一般的な {...} は除去対象ではありません。class / className 属性の静的クラス名を抽出します。

Block/Element 判定

class 属性の先頭トークンを base class として判定します。
先頭トークンが blockCase(または customPatterns.block)に一致する場合のみ Block として扱います。
Block/Element として扱いたいクラスは先頭に置いてください。

blockCase Block の例 elementCase Element の例
kebab(既定) hero-section, feature-card kebab(既定) title, body
camel heroSection, featureCard camel title, body
pascal HeroSection, FeatureCard pascal Title, Body
snake hero_section, feature_card snake title, body

注意:

  • Element は 常に 1 語です。elementCase=camel は小文字 1 語(例: title)、elementCase=pascal は大文字始まり 1 語(例: Title)のみ許可され、bodyText / BodyText のような内部大文字は使えません
  • customPatterns を指定した場合は該当パターンが優先されます
  • customPatterns を指定している場合、プレースホルダ(block-box / element)が命名規則に合わない可能性があるため整合性を確認してください
  • modifierPrefix(デフォルトは -)で始まるクラスは Modifier 扱い、u- で始まるクラスは Utility 扱いになり、base class にはなりません
  • - / _ / u- 始まりのクラスは customPatterns でも base 判定できません

動的クラスの制限

  • Vue/Svelte の :class バインド内の静的クラスは抽出しない(class="..." 側に書くことを推奨)。v-bind:class は :class が残る場合があるため注意
  • 動的に出現するクラス名は追跡しない
  • JSX の class / className は SCSS 生成では静的クラスを抽出します(文字列リテラル、テンプレートリテラルの静的部分 + ${} 内の静的 member access や文字列リテラル、member access 例: styles.foo, styles['foo'], styles["foo"])。jsxClassBindings.memberAccessAllowlist を設定している場合は、許可されたベース識別子のみクラスとして扱い、チェーン(例: styles.layout.hero)は動的扱いになります。動的な式は除去されます
  • プレースホルダ付与は動的式を含む JSX バインディングをスキップします(props.className、foo && 'bar'、非静的な ${} など)

設定

すべての CLI は spiracss.config.js の設定を参照します。
package.json に "type": "module" がある場合は export default を使用してください。

HTML CLI は CJS バンドルのため、Node を --disallow-code-generation-from-strings で起動している場合は ESM 設定を読み込めません。

  • CJS 運用へ切り替え可能な場合は module.exports に切り替えるか、フラグを外してください
  • "type": "module" のプロジェクトでは spiracss.config.js を CJS にできないため、実質フラグを外す必要があります(.cjs / .mjs の自動探索はありません)
  • spiracss.config.js が存在するのに読み込みできない場合は、CLI がエラー終了します(設定の記法や type: "module" を確認してください)