クイックスタート

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

現在のベータ版 — 変更履歴を見る

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

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

必須ファイル

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

spiracss.config.js（プロジェクトルート）
AIエージェント用ドキュメント（ダウンロードし、AIエージェントワークフローの参照ドキュメントにする）

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

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

CommonJS の例:

// stylelint.config.cjs（CommonJS）
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
  }
}

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 拡張

Comment Links

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

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

HTML to SCSS

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

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

共通設定

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

モジュール方式に応じて、spiracss.config.js は ESM（export default）または CommonJS（module.exports）で記述してください。詳細は 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']
  }
}

CommonJS（package.json に "type": "module" が無い場合）:

// spiracss.config.js（CommonJS）
module.exports = {
  aliasRoots: {
    src: ['src'],
    components: ['src/components'],
    common: ['src/components/common'],
    pages: ['src/components/pages'],
    parts: ['src/components/parts'],
    styles: ['src/styles'],
    assets: ['src/assets']
  }
}

任意のプロジェクト方針

設定内容は ESM/CJS で同じです。プロジェクトに合う場合だけ追加してください。

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

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

次へ
スターター