Design Philosophy

From “memorizing CSS architecture” to “tools validate for you.”

SpiraCSS makes structural decisions verifiable via Stylelint based on one principle: “The parent decides the child’s layout; the child only styles its internals.”

Challenges with existing CSS methodologies

Many CSS methodologies—BEM / SMACSS / OOCSS / RSCSS / ITCSS / CUBE CSS—have tackled the question of how to structure CSS and keep it maintainable.

However, they share a common challenge:

“Decisions about component boundaries and naming depend on human interpretation.”

• How far does a single component extend?
• Is this element part of the parent, or an independent component?
• Should layout responsibility belong to the parent or the child?
• What naming convention should be followed?

These decisions are presented as “guidelines,” but there’s a burden of memorizing rules, and ultimately they’re left to the implementer’s experience and intuition. As a result:

• Component granularity and naming vary across projects
• Code reviews spend time debating component boundaries
• AI-generated code sometimes fails to maintain consistency

Additionally, RSCSS explicitly states One component per file, and BEM also advocates separating block implementations into different files by technology. However, tooling to ease file navigation was lacking, so only naming conventions were adopted while the file structure rarely took hold in practice.

The SpiraCSS approach

SpiraCSS expresses structure through class names and splits files by Block.

On top of that, SpiraCSS turns structural decisions into invariants rather than interpretations. Each Block has its own file, manages only its own responsibilities, children are self-contained, and the only thing parents do to children is lay them out. This approach may parallel object-oriented thinking in programming (separation of concerns, encapsulation).

Eliminate component boundary ambiguity

Existing CSS methodologies require human interpretation for component boundaries, and naming and placement change based on that judgment. SpiraCSS expresses structure solely through repetition of “Block > child (Block or Element)” and enforces that structure with Stylelint, preventing the architecture from drifting.

Prevent class name collisions by construction

Each component has its own SCSS folder, with the rules “one Block = one file” and “filename = Block name.” Since you cannot create files with the same name in the same folder, Block name collisions are structurally impossible. Rather than prohibiting it with rules, the structure itself makes it impossible.

Separate Modifiers into Variant and State

Traditional BEM Modifiers used the same mechanism for “appearance variations” and “interaction states,” making the distinction unclear. SpiraCSS separates static differences (Variant) from dynamic states (State), expressing them by default through data-variant / data-state attributes. This makes the distinction clear at the HTML level, and Stylelint verification ensures consistent placement across the codebase.

Clarify layout and property responsibilities

CSS layout is fundamentally about “parents arranging children” (parent gets display: flex, child gets align-self). A child’s margin also affects the parent’s layout, so it is specified from the parent rather than the child itself. Based on this nature, SpiraCSS explicitly defines which component should own each property. Thinking of it as separating responsibilities between parent and child—similar to object-oriented design—may make this easier to understand.

Clarify structure within files

Existing CSS methodologies specify “what goes in which file” but don’t address “how to structure content within a single file.” SpiraCSS defines section structure like —interaction and —shared to clarify organization within files.

Make file navigation easy

With one Block per file, you navigate between related files rather than searching within a single file. Manually finding files from directories is tedious, so @rel comments create links between files and the VS Code extension (SpiraCSS Comment Links) enables click-to-jump navigation, allowing fast editing while moving between parent-child Blocks.

Let tools validate, not memorization

Rules that humans struggle with won’t be stable when given to AI either. By adopting only mechanically verifiable rules and delegating to tools, both humans and AI can write correct code by the same standards.

Enable autonomous fixes via error messages

Making AI understand complex rules through instruction files is unrealistic. Like TypeScript’s type errors, if error messages include “what’s wrong” and “how to fix it,” AI can fix issues autonomously. Humans learn from the same messages, making it effective for training newcomers too.

Meaning of SPIRA

SpiraCSS = Simplified Practical Integrated Relational Architecture

Principle	Meaning
Simplified	”The parent decides layout; the child only styles its internals” as the core principle
Practical	Defines property responsibilities and section structure that tend to be ambiguous in practice
Integrated	HTML structure, SCSS, and tools work together under the same rules, validated by Stylelint
Relational	@rel comments make file dependencies explicit
Architecture	Three CSS layers and “one Block per file” design the overall structure