DEV Community: zetsubo

Same Lint, Same Result — A Stylelint Toolchain for Humans and AI Agents

zetsubo — Sat, 14 Feb 2026 00:31:11 +0000

Part 4 laid out SpiraCSS's core principles and structure. This final part covers the tools and procedures for adopting it in practice.

Tool Overview

SpiraCSS is both a design methodology and a toolchain that supports it.

Tool	Role	Users
Stylelint plugin	Automatically verifies SCSS structure, naming, and placement	Humans and AI agents
HTML CLI	Generates SCSS from HTML, validates HTML structure	Primarily AI agents
AI Agent Guide	Self-contained document covering rule specs, decision flow, and fix procedures	AI agents
VS Code: Comment Links	Click `@rel` comments to navigate between files	Humans
VS Code: HTML to SCSS	Generate SCSS from HTML via keyboard shortcuts	Humans

Humans use VS Code; AI agents use the CLI. Both share the same generation logic and the same validation rules.

Stylelint Plugin — The Design Guardian

This plugin is the core of SpiraCSS. Eight rules systematically verify the design principles described in Part 4.

Rule	Verification
`spiracss/class-structure`	Block/Element naming, parent-child structure, section composition
`spiracss/property-placement`	Container/Item/Internal property placement
`spiracss/page-layer`	Page layer boundaries and links
`spiracss/interaction-scope`	--interaction section position and structure
`spiracss/interaction-properties`	transition/animation placement
`spiracss/keyframes-naming`	@keyframes naming and placement
`spiracss/pseudo-nesting`	Pseudo-class and pseudo-element nesting
`spiracss/rel-comments`	@rel comment parent-child links

Setup

yarn add -D @spiracss/stylelint-plugin stylelint stylelint-scss postcss-scss

// 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',
  ignoreFiles: [
    'src/styles/partials/**/*.scss',
    '!src/styles/partials/keyframes.scss'
  ],
  rules: {
    ...createRules(spiracssConfig),
    'scss/at-rule-no-unknown': true
  }
}

createRules() reads the spiracss.config.js settings and distributes appropriate options to all eight rules. Individual rules can also be disabled.

Error Message Examples

Here are simplified examples showing the "feedback-style" error messages discussed in Part 3. Actual output includes additional context and configuration hints.

Structure violation:

Element ".title" cannot contain Block ".nav-links".
Only Blocks can contain other Blocks.
Move ".nav-links" to be a direct child of a Block instead.

Naming violation:

Block names must use two-word kebab-case (e.g., "hero-container").
Single-word names are reserved for Elements.

Section placement violation:

":hover" must be inside the --interaction section.
Use "@at-root &" to create the interaction scope.

Every error explains what's wrong and how to fix it. AI agents parse these messages and autonomously correct the code. Humans can also understand the fix the first time they encounter a rule.

HTML CLI — A Generation Tool for AI Agents

The HTML CLI is designed for AI agents and automation scripts.

yarn add -D @spiracss/html-cli

It provides three commands:

SCSS Generation (`spiracss-html-to-scss`)

Generates SpiraCSS-compliant SCSS scaffolding from HTML.

cat component.html | yarn spiracss-html-to-scss --root --stdin \
  --base-dir src/components/feature-card

Output:

feature-card/
├── feature-card.scss
└── scss/
    ├── card-header.scss
    ├── card-body.scss
    └── index.scss

AI agent workflow: Load the AI Agent Guide (a self-contained document covering rule specs, decision flow, and fix procedures) into context → Write HTML → Generate SCSS via CLI → Add styles to generated SCSS → Validate with Stylelint. The document provides structural understanding; lint verifies the result — this two-layer approach supports autonomous AI correction.

To be clear: lint alone is enough to guarantee convergence. Even without the AI Agent Guide, the feedback loop described in Part 3 — write, lint, fix, re-lint — will converge to architecture-compliant code. The Guide accelerates the process by reducing the number of iterations, but it's supplementary, not required. The AI Agent Guide is included in each starter project and available on the SpiraCSS site.

HTML Structure Validation (`spiracss-html-lint`)

Detects SpiraCSS structural rule violations at the HTML stage.

cat component.html | yarn spiracss-html-lint --root --stdin

Catches issues like Elements acting as parents of Blocks or naming rule violations before any SCSS is written.

Placeholder Insertion (`spiracss-html-format`)

Assigns placeholder classes to HTML elements that don't have classes yet.

cat raw.html | yarn spiracss-html-format --stdin

When creating a new component, the workflow — write HTML, insert placeholders, generate SCSS — can be fully automated.

VS Code Extensions — Productivity Tools for Humans

Comment Links

Navigate between files by Cmd/Ctrl+clicking @rel comments. With one Block per file, jumping between parent and child Blocks is common. This extension eliminates that friction.

.feature-card {
  > .card-header {
    // @rel/scss/card-header.scss   ← Cmd+Click to navigate
    margin-bottom: 16px;
  }
}

Supports aliases (@components/..., @styles/...), enabling one-click navigation from page SCSS to components as well.

HTML to SCSS

Generate SCSS via keyboard shortcuts in VS Code. Uses the same generation logic as the CLI, delivered through a human-friendly UI.

Command	Shortcut	Action
Generate from Root	`Cmd+Ctrl+A`	Generate SCSS for the root Block and child Blocks
Generate from Selection	`Cmd+Ctrl+S`	Generate SCSS for the selected Block only
Insert Placeholders	`Cmd+Ctrl+D`	Assign placeholder classes to elements without classes

Shared Configuration (`spiracss.config.js`)

A configuration file referenced by all tools. Place it in the project root.

export default {
  aliasRoots: {
    components: ['src/components'],
    common: ['src/components/common'],
    pages: ['src/components/pages'],
    parts: ['src/components/parts'],
    styles: ['src/styles']
  }
}

aliasRoots is used for file path resolution. Comment Links aliases, Stylelint @rel validation, CLI output destinations — all share this configuration.

Variant/State syntax (data attribute mode / class mode) and Element naming case conventions are also configurable.

Getting Started

The minimal setup is three steps:

Place spiracss.config.js in the project root
Install the Stylelint plugin and configure with createRules()
Run yarn stylelint "src/**/*.scss" — then fix issues following the error messages

That's all it takes to get SpiraCSS structural verification running. VS Code extensions (Comment Links / HTML to SCSS) and the HTML CLI can be added as needed.

Setup Notes

Node.js 20.19.0 or higher required (for the Stylelint plugin; the HTML CLI requires Node.js 20+)
Stylelint v17+ required (for v16, use @spiracss/stylelint-plugin@0.3.x)
All tools are currently in Beta. Feedback is welcome on GitHub Issues
ESM format required for stylelint.config.js (export default) when using this import style. Use .mjs extension or set "type": "module" in package.json
Exclude global-layer SCSS: Set ignoreFiles to src/styles/partials/**/*.scss (don't exclude keyframes.scss)
Gradual adoption in existing projects is supported. Disable individual rules with null and expand coverage incrementally

Series Summary

This series discussed CSS architecture for the AI coding agent era in five parts.

Part 1: CSS architecture should shift from "rules to memorize" to "feedback systems"
Part 2: Preventing design drift requires "invariants," not conventions
Part 3: Leveraging invariants requires a feedback loop that returns "what to fix and how"
Part 4: SpiraCSS derives everything from a single principle: "parent handles layout, child handles internals"
Part 5: A Stylelint plugin, CLI, and VS Code extensions support this design in practice

The underlying idea is a system where the design converges to the same result regardless of who writes it. Whether it's a junior developer, a senior developer, or an AI agent — if it passes the same lint, at minimum, the structure, separation of responsibilities, and placement align to the same standard.

The challenge of CSS architecture has long focused on "how to create good rules and how to enforce them." But in an era where AI participates as an author, the "enforce rules" model itself needs rethinking.

What matters is not creating good rules, but designing an environment that resists breaking down.

Final Thoughts

This series comes down to one idea: in the AI era, CSS architecture should focus not on memorizing conventions, but on designing systems that converge to the same result.

SpiraCSS is one implementation of that idea, but the underlying approach applies more broadly. Make the structure machine-verifiable, and return feedback that both humans and AI can act on. Meet those conditions, and the design stays stable through real-world use.

If this perspective resonates, try applying it to just one existing component and see how it changes your review process.

SpiraCSS's design specs, tools, and source code are all open source.

SpiraCSS: https://spiracss.jp
GitHub: https://github.com/zetsubo-dev/spiracss

The CSS Fundamental You Won't Learn from BEM/SMACSS Alone — Property Responsibility

zetsubo — Tue, 10 Feb 2026 10:22:52 +0000

You've learned BEM. Your naming is correct. Your components are properly decomposed.
You think you "get" CSS, right?

Then answer this — should that CSS property go on the parent (the container) or the child (the item)? Can you explain why?

If you can't, what's missing isn't a naming convention. It's the fundamentals of CSS itself — something that comes before any design methodology.

This article lays out that foundation: the concept of property responsibility.

Why Correct Naming Still Leads to Broken Layouts

Look at these two patterns:

// Pattern A
.card-list {
  display: flex;
  flex-direction: column;
}

.card + .card {
  margin-top: 24px;
}

.card {
  padding: 16px;
}

// Pattern B
.card-list {
  display: flex;
  flex-direction: column;

  // Parent decides spacing between children
  > .card + .card {
    margin-top: 24px;
  }
}

.card {
  padding: 16px;
}

Here, .card-list is the parent (the container) and .card is the child (the item).

Assuming .card elements are direct children, both produce the same visual result.

But in Pattern A, .card knows about its own layout position (margin-top). Change the parent, and it breaks.

Pattern B separates responsibilities — placement (margin-top) is handled by the parent, internal styling (padding) by the child.

This difference has nothing to do with naming conventions. It's about understanding CSS's layout model itself.

In Flexbox, properties are split between Container (display: flex, etc.) and Item (align-self, flex, etc.). Since margin determines the outer spacing of a child element, specifying it via the parent's child selector tends to be more consistent in practice.

The Problem with Writing CSS That "Looks Right"

Here's a pattern I see all the time. BEM naming is correct, components are reasonably decomposed — but property placement is all over the place:

Some components write margin on themselves; others have it specified from the parent
Container and Item properties are mixed in the same block without distinguishing roles (An element serving as both Container and Item is perfectly normal — mixing them unconsciously is what makes code unreadable)
padding and margin are jumbled together with no apparent logic

This is what happens when you write without understanding property responsibility. The output looks correct. It passes code review. But change the parent component and the layout breaks.

This isn't an individual skill issue. It's a structural problem: CSS education is too heavily weighted toward naming and component decomposition.

You perfect your TypeScript types. You learn React patterns. But are you still placing CSS properties based on gut feeling?

Even when AI coding agents write CSS, the same problem occurs. Naming and component decomposition may look reasonable, but property placement tends to be inconsistent. When the human-side criteria for CSS design are ambiguous to begin with, this is likely to happen.

That's the fundamental both humans and AI struggle with: property responsibility.

The Three Property Categories

CSS properties can be classified into three categories by responsibility:

Category	Role	Examples	Where to Write
Container	Determines how children are arranged	`display`, `gap`, `justify-content`	On the element itself
Item	Position within parent's layout	`margin`, `flex`, `order`, `align-self`	In the parent's child selector (e.g., `> .child`)
Internal	The element's own appearance	`padding`, `font-size`, `color`, `background`	On the element itself

This classification reflects how CSS layout models (Flexbox, Grid) actually work. It's not specialized framework knowledge — it's CSS fundamentals (this article is an overview of the design principle; the lint rules mentioned later cover a subset of this).

Note that Item properties (align-self, flex, etc.) are applied to child elements per the CSS spec, but the key point of this approach is that the parent specifies them on the child (via > .child selectors). At boundaries where the parent can't directly select the child (slots, dynamic insertion, etc.), use a wrapper (e.g., .card-list__item) or utility class (e.g., .u-mt-24) to bridge the gap.

Just being aware of these three categories changes code structure significantly:

// Container properties → on the element itself
.card-list {
  display: flex;
  flex-wrap: wrap;
  gap: 24px;

  // Item properties → from parent to child
  > .feature-card {
    flex: 1 1 300px;
    align-self: flex-start;
  }
}

// Internal properties → on the element itself
.feature-card {
  padding: 16px;
  background: white;
  border-radius: 8px;
}

Once you can see this classification, you can tell whether property placement in someone else's code is intentional:

margin specified from the parent's child selector → understands responsibility
margin written on the child component itself → responsibility is unclear
Container and Item properties are separated → understands CSS layout models
display: flex and margin-top jumbled in the same selector → no distinction (Intentional dual-role cases are a different matter)

Writing margin with intent vs. gut feeling fundamentally changes how fragile your code is. Once you internalize this foundation and revisit your past code, you'll likely notice you were "matching the visual result without understanding the structure."

From "Memorize" to "Learn Through Feedback"

"Be mindful of property responsibility" is easy to say, but maintaining team-wide quality through awareness alone is difficult. This is the same problem as naming conventions — the limits of the "memorize and follow" model.

In SpiraCSS, which I develop, this approach is built into Stylelint rules. Write margin-top on a child component, and lint prompts you to specify it from the parent side. Whether a human writes it or AI generates it, you get the same feedback.

I've written in more detail about this shift from "memorize rules" to "converge through feedback" in a separate series:

CSS Architecture in the AI Agent Era

Naming organizes appearance. Responsibility organizes structure.

Next time you write CSS, check just one thing — "Is this property the parent's responsibility, or the child's?" That alone changes how your code breaks.

Parent Owns Layout — A New CSS Architecture for the AI Era — Drift-Resistant by Design

zetsubo — Mon, 09 Feb 2026 09:51:24 +0000

Parts 2–3 established the framework of "invariants" and "feedback loops." Part 3 focused on feedback message design; this part defines the concrete rule system those messages enforce — the principles and structure of SpiraCSS.

Single Principle: Parents Handle Layout, Children Handle Only Internals

Every rule in SpiraCSS derives from one principle:

The parent decides the child's layout; the child only writes its own internals.

CSS layout is fundamentally a "parent arranges children" mechanism. You set display: flex on the parent and align-self on the child. Since a child's margin also affects the parent's layout, it should be controlled by the parent.

All structural rules are derived from this principle.

Block and Element — Two Structural Units

SpiraCSS classifies all classes into Blocks and Elements.

Type	Naming Convention	Example	Role
Block	Two-word kebab-case	`.feature-card`, `.card-header`	Independent component unit
Element	Single-word	`.title`, `.body`, `.icon`	Constituent part within a Block

This naming convention corresponds to BEM's "Block__Element," but with a crucial difference: the naming pattern itself expresses the structure. Two words mean Block, one word means Element — no room for interpretation. (This naming rule is the default; case conventions can be customized in spiracss.config.js.)

The allowed parent-child relationships are also explicit:

Parent	Child	Allowed
Block	Block	✅
Block	Element	✅
Element	Block	❌
Element	Element	✅ (with depth limit)

Placing a Block under an Element is forbidden. Element-to-Element nesting is allowed but has a depth ceiling (default 4 levels, configurable via elementDepth). The fundamental structure is "Blocks own children." This doesn't restrict DOM nesting itself; it constrains only responsibility-bearing class relationships. This constraint automatically determines component boundaries.

"What if Element nesting gets too deep?" The answer is straightforward: if a unit has independent responsibility, promote it to a Block (e.g., .title → .title-box). Decorative elements are handled with tag selectors or pseudo-elements. Tag selectors are always scoped within a Block (e.g., .feature-card > .title > span), so there's no external leakage. This decision is also mechanical: if you need independent responsibility, promote to Block; otherwise, use Element or tag selectors.

Property Responsibility Separation

The "parent handles layout, child handles internals" principle directly maps to CSS property placement rules.

// Parent Block
.card-list {
  display: flex;           // Container property → on itself
  gap: 24px;               // Container property → on itself

  > .feature-card {
    margin-top: 16px;      // Item property → specified from parent
    flex: 1;               // Item property → specified from parent
  }
}

// Child Block (separate file)
.feature-card {
  padding: 16px;           // Internal property → on itself
  text-align: center;      // Internal property → on itself

  > .title {
    font-size: 18px;       // Internal property → on itself
  }
}

Properties fall into three categories:

Container properties (display, gap, justify-content, etc.) → Write on the Block itself
Item properties (margin, flex, order, align-self, etc.) → Write in the parent Block's > .child selector
Internal properties (padding, font-size, color, etc.) → Write on the selector itself

This three-way classification reflects how CSS layout models (Flexbox, Grid) work. Even before naming or file organization, this classification is the starting point of CSS architecture.

Writing margin-top on the child Block itself triggers a lint error. The error message says: "Specify margin-top from the parent Block using the > .child-name selector." No need to memorize — just write and the lint will tell you.

This rule meets the three criteria for invariants from Part 2. Binary evaluation: Whether margin-top is in the parent's > .child or on the child itself can be unambiguously determined. Syntax-verifiable: Determined by analyzing SCSS selector structure alone; no runtime needed. Locally verifiable: Only the target SCSS file needs to be examined. That's why automated lint verification works.

1 Block = 1 File

SpiraCSS separates files by Block.

feature-card/
├── feature-card.scss      ← Root Block
└── scss/
    ├── card-header.scss   ← Child Block
    ├── card-body.scss     ← Child Block
    └── index.scss         ← @use aggregation

The root Block file loads child Blocks:

@use "sass:meta";

.feature-card {
  @include meta.load-css("scss");

  > .card-header {
    // @rel/scss/card-header.scss
    margin-bottom: 16px;
  }

  > .card-body {
    // @rel/scss/card-body.scss
  }
}

This structure has three advantages:

Physical prevention of class name collisions: You can't create two files with the same name in the same folder. This is not just a rule; the structure makes collisions impossible
Forced responsibility separation: Child Blocks write only their own internals in their own files. There's no way to interfere with the parent's layout
Navigation without searching: @rel comments link between files, enabling one-click navigation to related files

Variant and State Separation

BEM modifiers used a single mechanism to express both visual variations and dynamic states. SpiraCSS separates these into two:

Type	Purpose	HTML	SCSS
Variant	Static variations (size, color scheme)	`data-variant="primary"`	`&[data-variant="primary"]`
State	Dynamic states (open/close, selection, loading)	`data-state="active"`	`&[data-state="active"]`

.feature-card {
  padding: 16px;
  background: white;

  &[data-variant="highlight"] {
    background: #f0f8ff;
  }

  // --interaction
  @at-root & {
    transition: box-shadow 0.3s ease;

    &[data-state="disabled"] {
      opacity: 0.5;
      pointer-events: none;
    }

    &:hover {
      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
    }
  }
}

Variants go in the base structure section; States go in the --interaction section. Stylelint also enforces this placement.

SCSS Section Structure

The internal file structure is also defined. A single Block file consists of up to three sections:

Base structure: Block layout, child placement, Variants
--shared (optional): Styles shared among descendants within the Block
--interaction (optional): States, hover, focus, ARIA, transitions, animations

"Where do I write hover?" "Where does transition go?" — these commonly ambiguous decisions in practice are resolved unambiguously by the section structure.

The Big Picture So Far

SpiraCSS's design can be summarized as follows:

Single principle (parent handles layout, child handles internals)
  ├── Naming: Block (two-word) / Element (single-word)
  ├── Structure: Element > Block forbidden, Element depth limit
  ├── Properties: Container / Item / Internal — 3 categories
  ├── Files: 1 Block = 1 file
  ├── State: Variant / State separation
  └── Sections: Base / --shared / --interaction

Every rule derives from the single principle, and every rule is verifiable by Stylelint. No need to memorize conventions — just write and the lint will tell you.

The next part covers the tools and procedures for adopting this design in practice. How do you integrate it into a real project, and how do humans and AI coexist?

SpiraCSS's design specs, tools, and source code are all open source.

SpiraCSS: https://spiracss.jp
GitHub: https://github.com/zetsubo-dev/spiracss

CSS Architecture Lint in the AI Era — TypeScript-Style Errors That Tell You How to Fix It

zetsubo — Thu, 05 Feb 2026 09:58:33 +0000

In Part 2, I introduced the idea of defining "invariants" to prevent design degradation (drift). A state in which all invariants are satisfied — that's architecture-compliant code, and it shows up as zero lint errors. But defining invariants alone isn't enough. Detecting violations, communicating how to fix them, and driving corrections — only when this loop runs does the design hold.

Two Approaches: Upfront Teaching vs. Post-Hoc Feedback

There are broadly two ways to maintain CSS architecture.

Upfront teaching: Write guidelines, educate the team, verify through reviews. For AI agents, communicate rules through instruction files (llms.txt, AGENTS.md).

Post-hoc feedback: Verify what's written, return errors with fix instructions. Humans see errors in the editor and fix them; AI parses lint output and self-corrects.

Part 1 covered the limits of upfront teaching. The more rules there are, the higher the memorization cost; decisions become subjective; AI accuracy drops as context grows.

Post-hoc feedback doesn't require the author to know the rules beforehand. Write, see the error, fix it. Starting from zero knowledge, the code converges on architecture compliance simply by running through the loop.

Learning from TypeScript's Feedback Design

TypeScript's type system is a successful example of post-hoc feedback.

// TypeScript error message
// Type 'string' is not assignable to type 'number'.
const count: number = "hello";

What makes this error effective is that it contains three pieces of information:

What's wrong: The types don't match
Where: Assignment to count
How to fix it: Pass a number value

Developers don't need to memorize all of TypeScript's type rules. The compiler tells them as they write code, so just following the feedback converges the code to type safety.

Architecture lint needs the same structure.

But here's the key distinction: traditional CSS lint checks what you wrote — naming patterns, property duplication. Architecture lint checks where you wrote it — whether the structure itself follows design rules. This is a fundamentally different level of verification.

Designing Error Messages for Architecture Lint

Traditional CSS lint tends to focus on surface-level checks.

// Traditional lint error (typical)
Expected indentation of 2 spaces (indentation)

The fix here is obvious — adjust the spaces. But this is surface-level formatting. It doesn't verify component structure or property placement — the architectural concerns that cause real design drift.

An error message that functions as feedback should look like this:

// Feedback-style lint error
"margin-top" is an item property — it must be specified
from the parent Block using the `> .child-name` selector,
not inside the child Block itself.

This message contains:

What's wrong: margin-top is in the wrong place
Why it's wrong: Item properties must be specified from the parent
How to fix it: Write it in the parent Block's > .child-name selector

Here's what the Stylelint output would look like:

src/components/feature-card/feature-card.scss
  4:3  ✖  "margin-top" is an item property — it must be    spiracss/property-placement
          specified from the parent Block using
          "> .child-name" selector, not inside the
          child Block itself.

File path, line number, error message, rule name — all the information an AI agent needs to parse and act on. The correction flow looks like this:

1. Extract from lint output: "feature-card.scss line 4, move margin-top to parent"
2. Remove the margin-top declaration from feature-card.scss
3. In each parent Block that uses feature-card, add under its selector (SCSS nesting):
   .parent-block {
     > .feature-card { margin-top: ... }
   }
4. Re-run lint → confirm zero errors

Note that violation detection is always local — lint spots margin-top in the wrong file. The fix may touch another file (the parent), but the error message tells you exactly where, with no project-wide scanning required.

Even humans with no CSS architecture experience can understand the fix from this message.

The Structure of a Feedback Loop

Whether the author is human or AI, the loop structure is the same:

Write → Run lint → Detect errors → Fix → Run lint → ... (until zero errors)

For humans:

Write SCSS
Stylelint shows errors in real-time in the editor
Read error messages and fix
Save → re-validate → fix complete

For AI agents:

Generate SCSS
Run stylelint
Parse output and fix according to error messages
Run stylelint again → repeat until zero errors

The key point is that this loop has the same exit condition. Zero errors — that's architecture-compliant code, and it converges to the same standard regardless of who wrote it.

Error Message Design Principles

For the feedback loop to function, error messages must meet these conditions:

Be specific: Not "invalid naming" but "Blocks must use a two-word kebab-case name (e.g., hero-container)"
Include fix instructions: Communicate not just what's wrong, but how to fix it
Be self-contained: Understandable without referencing external documentation
Be machine-readable: Structured so AI can parse and convert to actionable fixes

Error messages are both "documentation" and a "teacher." They must be comprehensible to a human encountering the rule for the first time and convertible to executable fixes when read by AI — that's the quality bar.

Feedback Effectiveness in Practice

Whether this design works hinges on one question: "Can you really fix issues just from lint errors?"

I've implemented and used this approach in production with SpiraCSS. Out of the box, traditional CSS lint mainly covers naming conventions and property duplication. SpiraCSS's Stylelint plugin goes further — architecture-aware lint that extends verification to component structure and property placement. As of 2025, when SpiraCSS was first released, I'm not aware of any other CSS architecture methodology that performs this level of structural verification through lint — integrated into an AI agent's autonomous correction loop.

This level of test coverage — over 650 patterns — would have been impractical to develop by hand. AI-assisted development made it possible.

From practical experience, I can say this: if invariants are properly designed, fixes are usually possible from error messages alone. Because invariants are "binary" and "locally verifiable," the location and method of correction are determined with little ambiguity.

With ambiguous conventions, you get hesitation: "Should I do this? Or that?" But an invariant violation almost always has one clear answer: "Fix it like this." That's why the feedback loop converges.

The next part looks at the concrete design principles and structure of SpiraCSS, which implements this approach. How many rules can be derived from a single principle?

SpiraCSS's design specs, tools, and source code are all open source.

SpiraCSS: https://spiracss.jp
GitHub: https://github.com/zetsubo-dev/spiracss

CSS Drift in the AI Era — Why Conventions Break Down and How Machine-Verifiable Rules Fix It

zetsubo — Tue, 03 Feb 2026 10:48:19 +0000

In Part 1, I argued that CSS architecture should shift from "rules to memorize and follow" to a "feedback system." But what exactly does "resilient" (drift-resistant) design mean? This part defines the phenomenon of design degradation as "drift" and introduces the concept of "invariants" to prevent it.

Drift — How Design Breaks Down

CSS design doesn't collapse all at once. Small decision inconsistencies accumulate, and by the time you notice, coherence is lost. I call this "drift."

In this series, "breaking down" refers specifically to three things:

Component boundary ambiguity: Where one component ends and another begins differs from person to person
Layout responsibility confusion: Whether margin belongs to parent or child varies file by file
Naming and structural inconsistency: Naming conventions and file organization vary across the project

For example, here are common forms of drift in BEM-based projects:

One team member writes margin on the child component itself; another specifies it from the parent
"Is this element an independent component or part of its parent?" — answers differ by person
Modifier granularity varies from file to file

None of these are "rule violations." The interpretive latitude in guidelines allows decision drift. And that latitude widens as teams grow.

Introducing AI coding agents doesn't change the structure. Even with guidelines packed into the context window, output varies where judgment is required. Human drift simply becomes AI drift.

Why Conventions Can't Prevent Drift

Convention-based designs share a structural weakness:

Memorization burden: The longer the guidelines, the harder it is for everyone to accurately remember and apply them
Subjective decisions: Questions like "where does one component end?" have no objective answer
Verification difficulty: Whether something violates a convention can't be determined mechanically — you can only rely on reviews

When all three of these are present, drift is inevitable. Reviews maintain quality only while the reviewer's judgment stays consistent. And reviewers are human — their judgment drifts too.

Invariants — Eliminating Interpretive Ambiguity

Programming has the concept of "invariants" — conditions that must hold at every point in a program. An array index staying within bounds, an account balance never going negative — these conditions are mechanically enforced through types and assertions.

The same idea applies to CSS architecture. Eliminate rules whose answers change based on interpretation, and adopt only conditions that can be mechanically evaluated as true or false.

Concrete examples:

Convention-based (requires interpretation)	Invariant (mechanically verifiable)
"Decompose components into appropriate granularity"	"A Block (component) can only contain Blocks or Elements as direct children" (details in Part 4)
"Parents manage layout"	"`margin-top` can only be specified from the parent's `> .child` selector"
"Keep naming consistent"	"Blocks use two-word kebab-case; Elements use a single word"
"Distinguish between state and variation"	"Variants use `data-variant`; States use `data-state`"

The left column requires human interpretation to judge correctness. The right column can be judged through pattern matching on class names and selector structure. Automated lint verification becomes possible.

The examples in the right column are actual invariants used in SpiraCSS, which I've developed and use in production. Part 4 covers them in detail.

Design Criteria for Invariants

Not every rule can become an invariant. To function as one, a rule needs these properties:

Binary evaluation: Violation or compliance is determined unambiguously (no gray zones)
Syntax-verifiable: Can be determined through source code syntax analysis alone (no runtime needed)
Locally verifiable: Can be determined by looking at the target file alone (no project-wide scanning needed)

If the design is composed entirely of rules meeting these criteria, a lint tool can serve as the "gatekeeper." Humans don't need to make judgment calls — just follow the tool's verdict. The same goes for AI agents.

"Isn't this just freezing preferences rather than defining 'correctness'?" That's a fair objection. "Write margin from the parent" isn't the only correct approach. But there's value in fixing design preferences to make all authors converge on the same output — especially in an era where the pool of authors includes both humans and AI. Having an unwavering standard itself supports team productivity.

Invariants Alone Aren't Enough

However, defining invariants alone won't preserve the design. Without detecting violations and communicating "what's wrong and how to fix it," corrections don't happen. Defining invariants, detecting violations, and presenting fix instructions — this concrete sequence is the "feedback loop" that turns the feedback system from Part 1 into something actionable.

The next part dives deeper into the design of this feedback loop. When lint returns not just "what's wrong" but "how to fix it," how should those error messages be designed?

SpiraCSS's design specs, tools, and source code are all open source.

SpiraCSS: https://spiracss.jp
GitHub: https://github.com/zetsubo-dev/spiracss

How Should CSS Architecture Evolve in the Age of AI Coding Agents?

zetsubo — Mon, 02 Feb 2026 00:05:56 +0000

CSS architecture has long been built around human-centered workflows. The naming conventions of BEM/SMACSS and the design philosophy of utility-first both assume authors who memorize rules, make judgment calls, and maintain consistency through review.

But that assumption is changing. AI coding agents like Claude Code, Cursor, and Windsurf are becoming a normal part of UI implementation. In the Tailwind ecosystem, llms.txt — a file that feeds project rules and usage patterns to AI — has emerged as one approach to guide AI output.

llms.txt represents a "teach the rules to AI" approach. But the real question is: can we design an architecture that doesn't break down even without that teaching?

For tech leads and technical directors responsible for maintaining CSS quality across a team — and for developers ready to move beyond "CSS that just works" toward professional-grade architecture — this is an unavoidable question.

The Limits of Convention-Based Design

Utility-first is often said to pair well with AI. Since class names directly represent styles, AI can reproduce designs more easily. But whether the output is "production quality" is a separate question. For example, should a card component's margin belong to the parent or the child? Should visually identical elements be shared or duplicated? These structural decisions remain even with utility-first.

Convention-based designs like BEM face the same challenge. The model of maintaining quality through conventions + reviews shares the same weaknesses whether the author is human or AI:

There's a cost to memorizing conventions (or teaching them to AI)
Decisions are subjective, and review standards tend to drift
Consistency erodes as teams grow

Even if you feed AI a long instruction document to enforce rules, accuracy drops as context grows. The same problem humans face reappears in a different form.

From "Rules to Follow" to "Feedback Systems"

CSS architecture should shift from "rules to memorize and follow" to "feedback systems."

TypeScript's type system is a useful reference. You don't need to memorize type rules — just write code and the compiler tells you "this is wrong" and "fix it like this." Developers simply follow the feedback, and the code converges to type safety.

CSS architecture needs the same structure. Instead of teaching rules upfront, the system should respond to what's written with "what's wrong" and "how to fix it." Humans read error messages and fix issues; AI agents parse lint output and self-correct — a feedback loop where the design converges regardless of who writes the code.

About This Series

This series uses SpiraCSS — a CSS architecture methodology I created and use in production — as a concrete example to explore what CSS architecture should look like in the AI era.

Existing CSS methodologies assume humans memorize and follow naming conventions and file structures. SpiraCSS takes a different approach. It makes component structure and property placement mechanically verifiable through Stylelint, with error messages that tell you exactly what to fix and how — going well beyond conventional CSS lint, which typically covers only naming and property duplication.

Part 2: CSS Drift in the AI Era — Why Conventions Break Down and How Machine-Verifiable Rules Fix It
Part 3: CSS Architecture Lint in the AI Era — TypeScript-Style Errors That Tell You How to Fix It
Part 4: Parent Owns Layout — A New CSS Architecture for the AI Era — Drift-Resistant by Design
Part 5: Same Lint, Same Result — A Stylelint Toolchain for Humans and AI Agents

If your AI agents keep producing inconsistent CSS, or your team keeps raising the same issues in review — this series may offer a useful perspective.

Next up, we start by defining what resilience (drift resistance) concretely means.

How does your team maintain CSS design consistency? Guidelines, reviews, lint — what's working and what's breaking down?

SpiraCSS's design specs, tools, and source code are all open source.

SpiraCSS: https://spiracss.jp
GitHub: https://github.com/zetsubo-dev/spiracss

DEV Community: zetsubo

Same Lint, Same Result — A Stylelint Toolchain for Humans and AI Agents

Tool Overview

Stylelint Plugin — The Design Guardian

Setup

Error Message Examples

HTML CLI — A Generation Tool for AI Agents

SCSS Generation (spiracss-html-to-scss)

HTML Structure Validation (spiracss-html-lint)

Placeholder Insertion (spiracss-html-format)

VS Code Extensions — Productivity Tools for Humans

Comment Links

HTML to SCSS

Shared Configuration (spiracss.config.js)

Getting Started

Setup Notes

Series Summary

Final Thoughts

The CSS Fundamental You Won't Learn from BEM/SMACSS Alone — Property Responsibility

Why Correct Naming Still Leads to Broken Layouts

The Problem with Writing CSS That "Looks Right"

The Three Property Categories

From "Memorize" to "Learn Through Feedback"

Parent Owns Layout — A New CSS Architecture for the AI Era — Drift-Resistant by Design

Single Principle: Parents Handle Layout, Children Handle Only Internals

Block and Element — Two Structural Units

Property Responsibility Separation

1 Block = 1 File

Variant and State Separation

SCSS Section Structure

The Big Picture So Far

CSS Architecture Lint in the AI Era — TypeScript-Style Errors That Tell You How to Fix It

Two Approaches: Upfront Teaching vs. Post-Hoc Feedback

Learning from TypeScript's Feedback Design

Designing Error Messages for Architecture Lint

The Structure of a Feedback Loop

Error Message Design Principles

Feedback Effectiveness in Practice

CSS Drift in the AI Era — Why Conventions Break Down and How Machine-Verifiable Rules Fix It

Drift — How Design Breaks Down

Why Conventions Can't Prevent Drift

Invariants — Eliminating Interpretive Ambiguity

Design Criteria for Invariants

Invariants Alone Aren't Enough

How Should CSS Architecture Evolve in the Age of AI Coding Agents?

The Limits of Convention-Based Design

From "Rules to Follow" to "Feedback Systems"

About This Series

SCSS Generation (`spiracss-html-to-scss`)

HTML Structure Validation (`spiracss-html-lint`)

Placeholder Insertion (`spiracss-html-format`)

Shared Configuration (`spiracss.config.js`)