運用フロー

SpiraCSS の「生成→検証」運用の実践フローです。

必要なファイル

SpiraCSS の運用には以下の2つを準備してください：

spiracss.config.js（プロジェクトルート）
AI エージェント用ドキュメント（ダウンロードして AI ワークフローで使用）

どちらかが欠けていると判断が曖昧になりミスが起きやすくなります。作業開始前に必ず確認してください（デフォルトを仮定しないこと）。

1. 方針を固定する

プロジェクト開始時に、チームで以下を決めて spiracss.config.js に記述します。

決定事項	選択肢	備考
命名規則	デフォルト（Block=2語、Element=1語）/ カスタム	プロジェクトの運用ルールに合わせて設定
クラス属性	`class`（デフォルト）/ `className`（React/JSX）	JSX など構文に合わせる
Variant/State の表現	`data-*` 属性（推奨）/ クラスベース	プロジェクトの運用ルールに合わせる
マージンの方向	`margin-top` のみ（推奨）/ `margin-bottom` のみ
検証の厳しさ	全ルール有効 / 段階的導入
外部ライブラリ除外	使用するライブラリのクラス名を指定	Swiper、Splide など

// spiracss.config.js（例）
module.exports = {
  selectorPolicy: {
    variant: { mode: 'data', dataKeys: ['data-variant'] },
    state: { mode: 'data', dataKey: 'data-state' }
  },
  stylelint: {
    class: { elementDepth: 4 }
  }
}

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

2. Lint 設定を入れる

SCSS の生成前に、SpiraCSS の方針に合わせて Stylelint を設定します。

// stylelint.config.js（抜粋）
import spiracssPlugin, { createRules } from '@spiracss/stylelint-plugin'
import spiracssConfig from './spiracss.config.js'

export default {
  plugins: [spiracssPlugin, '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
  }
}

詳細はこちら: Stylelint 設定。

3. 構造を生成する

HTML を書いたら、SCSS テンプレートを自動生成します。

担当	ツール	コマンド / 操作
人間	VS Code 拡張	コマンドパレット → `SpiraCSS: Generate SCSS`
AI エージェント	CLI	`npx spiracss-html-to-scss src/components/card-list.html`

生成される SCSS には @rel コメントと基本構造が含まれます。

詳細はツール概要を参照してください。

4. 自動検証する

Stylelint が人間にも AI にも同じ基準で違反を検出します。

# 検証実行
npx stylelint "src/**/*.scss"

# 自動修正（可能なものだけ）
npx stylelint "src/**/*.scss" --fix

共通パーシャルは Stylelint の ignoreFiles で除外し、共有 keyframes は検証対象に含めます。

除外設定の例（共通パーシャルは除外し、共有 keyframes は検証対象に含める）:

// stylelint.config.js（抜粋）
export default {
  rules: { ...createRules(spiracssConfig) },
  ignoreFiles: [
    'src/styles/partials/**/*.scss',
    '!src/styles/partials/keyframes.scss'
  ]
}

エラーメッセージには正しいパターンと修正方法が含まれており、AI エージェントの自律的な修正に役立ちます。
エラーの理由を知りたい場合はルールページを参照：

class-structure - Block/Element の構造ルール
property-placement - プロパティの配置ルール
page-layer - ページエントリ SCSS の境界
rel-comments - @rel コメントのルール

5. ナビゲーションの負担を下げる

@rel コメントでファイル間を素早く移動できます。

// @rel/../components/card-list  ← Ctrl+Click でジャンプ

.page-home {
  > .card-list {
    // @rel/scss/card-list  ← 子 Block の SCSS へジャンプ
    margin-top: 24px;
  }
}

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

フロー全体像

HTML を書く
    ↓
Stylelint を設定
    ↓
SCSS を生成（CLI / VS Code）
    ↓
スタイルを実装
    ↓
Stylelint で検証
    ↓
エラーがあれば修正（人間または AI エージェント）

人間も AI も同じフローで作業できます。

前へ
rel-comments 次へ
Tips