設計原則
親が子のレイアウトを決め、子は内部だけを書く。
SpiraCSS は、この唯一の原則をベースにした CSS アーキテクチャです。
Tailwind CSS のようなユーティリティファーストとは異なり、BEM / SMACSS / RSCSS と同じ流れを汲んでいますが、命名規則だけでなく構造やプロパティの責務まで Stylelint で検証します。
SpiraCSS の Stylelint ルールは、エラーに「何が問題か」「どう直すか」を含めているため、AI エージェントによる自動修正にも対応しています。細かいルールを覚える必要はありません。
以下が全体像です。
CSS レイヤー
プロジェクト全体の CSS を 3 層に分けます。
| レイヤー | 役割 |
|---|---|
| グローバル層 | サイト全体の設定値・関数・Mixin・ユーティリティ |
| ページ層 | ページごとのエントリ CSS（コンポーネントの配置） |
| コンポーネント層 | Block / Element + Variant / State による部品設計 |
詳細は CSS レイヤー を参照してください。
コンポーネント
すべての構造は Block > 子（Block / Element） の繰り返しとして組み立てます。
命名
| 種別 | ルール（デフォルト） | 例 |
|---|---|---|
| Block | 2 語 | .hero-container, .card-list |
| Element | 1 語 | .title, .body |
| Utility | u- 接頭辞 | .u-hidden, .u-sr-only |
構造ルール
- 許可:
Block > Block,Block > Element - 禁止:
Element > Block,Element > Element（例外: 装飾目的のみ可）
Variant / State（デフォルト: data 属性）
| 種別 | HTML | SCSS |
|---|---|---|
| Variant | data-variant="primary" | &[data-variant="primary"] |
| State | data-state="active" | &[data-state="active"] |
| ARIA | aria-expanded="true" | &[aria-expanded="true"] |
ファイル管理
- 1 Block = 1 ファイル: 各 Block は 1 つの SCSS ファイルに対応
- 子 Block:
scss/に配置しmeta.load-css("scss")で読み込み - リンクコメント:
@relで関連ファイル間を辿れるように
詳細は コンポーネント を参照してください。
SCSS セクション構成
各 Block の SCSS を 3 セクションで整理します:
- 基本構造: Block のレイアウト + Variant
- —shared: Block 配下専用の共通クラス（必要なときだけ）
- —interaction: State / hover / ARIA / transition（必要なときだけ）
詳細は SCSS セクション を参照してください。
ツール連携
- 自動生成: CLI / VS Code 拡張で
@relコメントや SCSS を自動生成 - 自動検証: Stylelint が人間にも AI にも同じ基準で違反を検出
- 設定でカスタマイズ:
spiracss.config.jsで命名・Variant / State の表現モード・検証の強さなどを調整可能
詳細は ツール を参照してください。