コンテンツにスキップ

クイックスタート

import { Badge } from ‘@astrojs/starlight/components’;

現在のリリース — 変更履歴を見る

SpiraCSS のツールを導入する手順です。

まずは動くサンプルで試したい場合は、スターター を参照してください。

必須ファイル

SpiraCSS の運用には次の 2 つを用意します。

いずれかが欠けている場合、判断が不確かになり誤りやすくなるため、作業前に必ず確認してください(デフォルト適用は行いません)。

SpiraCSS Stylelint プラグイン

SCSS の構造・命名を自動検証します。

インストール

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

設定

stylelint.config.js を作成します。

// stylelint.config.js(ESM)
import spiracss, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'
export default {
plugins: [...spiracss, '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
}
}

createRules() を使う場合は spiracss.config.js の aliasRoots が必須です。stylelint の各サブセクションは未指定でもデフォルトが適用されます。詳細は spiracss.config.js を参照してください。

実行

ターミナルウィンドウ
yarn stylelint "src/**/*.scss"

SpiraCSS HTML CLI

AI エージェント(Codex、Claude Code など)向けの CLI です。HTML から SCSS を生成、HTML 構造を検証します。手動で使用する場合は VS Code 拡張 を推奨します。

ターミナルウィンドウ
yarn add -D @spiracss/html-cli
ターミナルウィンドウ
# SCSS 生成
echo "$HTML" | yarn spiracss-html-to-scss --stdin
# HTML 検証
echo "$HTML" | yarn spiracss-html-lint --stdin
# HTML プレースホルダ付与
echo "$HTML" | yarn spiracss-html-format --stdin

※ 断片 HTML を扱う場合は spiracss-html-to-scss / spiracss-html-lint に --selection を併用してください。spiracss-html-format は --selection / --root 非対応です。

VS Code 拡張

リンクコメント(@rel など)は関連ファイルへの移動を一発で行うための仕組みです。ない場合は参照先を手作業で辿る必要があり、運用負担が大きくなります。

→ VS Code Marketplace / Open VSX からインストール

HTML to SCSS

HTML から SCSS テンプレートを生成します。

→ VS Code Marketplace / Open VSX からインストール

共通設定

すべてのツールは spiracss.config.js を参照します。プロジェクトルートに作成してください。 Stylelint の createRules() を使う場合は、aliasRoots が必須です。stylelint の各サブセクションは未指定でもデフォルトが適用されます。

v0.5.0 からコンポーネントルートのデフォルトは scope-explicit です。従来のルート生成・ルート書式の lint 挙動を維持する場合は、generator.scssRootStyle: 'class' を指定してください。クラス形式の子は変換不要ですが、子ファイル内のすべての @scope は全設定でエラーになり、既存の子 scope は手動移行が必要です。詳細は scope の設定 を参照してください。スタイルシートを自動変換しないでください。

詳細は spiracss.config.js を参照してください。

最小構成(必須)

aliasRoots は必須です(spiracss/rel-comments のエイリアス解決に使用されます)。

// spiracss.config.js(ESM)
export default {
aliasRoots: {
src: ['src'],
components: ['src/components'],
common: ['src/components/common'],
pages: ['src/components/pages'],
parts: ['src/components/parts'],
styles: ['src/styles'],
assets: ['src/assets']
}
}

任意のプロジェクト方針

プロジェクトに合う場合だけ追加してください。

  • generator.rootFileCase: 生成する SCSS のファイル名(と Stylelint の root filename 検証)をプロジェクトの命名に合わせる
  • htmlFormat.classAttribute: spiracss-html-format 実行時に class ではなく className(React/JSX)を出力する

その他の設定項目は、プロジェクトやチームのガイドラインに合わせてカスタマイズしてください。 詳細は spiracss.config.js を参照してください。