Design Principles
The parent decides the child’s layout; the child only styles its internals.
SpiraCSS is a CSS architecture based on this single principle.
Unlike utility-first approaches like Tailwind CSS, it follows the lineage of BEM / SMACSS / RSCSS, but Stylelint validates not only naming, but also structure and property responsibilities.
SpiraCSS Stylelint rules include what’s wrong and how to fix it in error messages, enabling AI agents to apply corrections. No need to memorize detailed rules.
Here’s the overview.
CSS Layers
Split project-wide CSS into three layers.
| Layer | Role |
|---|---|
| Global | Site-wide values, functions, mixins, utilities |
| Page | Per-page entry CSS (component placement) |
| Component | Component design with Block/Element + Variant/State |
See CSS Layers for details.
Components
Build all structures by repeating Block > child (Block | Element).
Naming
| Type | Rule (default) | Examples |
|---|---|---|
| Block | Two words | .hero-container, .card-list |
| Element | One word | .title, .body |
| Utility | u- prefix | .u-hidden, .u-sr-only |
Structure rules
- Allowed:
Block > Block,Block > Element - Disallowed:
Element > Block,Element > Element(exception: decorative purposes only)
Variant / State (default: data attributes)
| Type | HTML | SCSS |
|---|---|---|
| Variant | data-variant="primary" | &[data-variant="primary"] |
| State | data-state="active" | &[data-state="active"] |
| ARIA | aria-expanded="true" | &[aria-expanded="true"] |
File management
- One Block per file: each Block maps to one SCSS file
- Child Blocks: place under
scss/and load withmeta.load-css("scss") - Link comments: use
@relto navigate between related files
See Components for details.
SCSS sections
Organize each Block’s SCSS into three sections:
- Base structure: Block layout + Variant
- —shared: shared classes scoped to this Block (only when needed)
- —interaction: State / hover / ARIA / transitions (only when needed)
See SCSS Sections for details.
Tooling
- Generate: CLIs / VS Code extensions automate
@relcomments and SCSS - Validate: Stylelint detects violations with the same criteria for humans and AI
- Configure: adjust naming, Variant/State expression mode, validation strength in
spiracss.config.js
See Tooling for details.