Why AI Agents Can't Write Clean CSS

#css #webdev #frontend #ai

You tell an AI coding agent: "Build this card component." The code it generates works. But the margin placement doesn't match your project's conventions. You point it out. It rewrites — with a different pattern. Three iterations later, you get three different structures — none of them consistent with what your team agreed on. The problem isn't the AI's capability. It's that convention-dependent design models break down the moment the author isn't human.

CSS architecture has long been designed with the assumption that humans write the code. The naming conventions of BEM/SMACSS and the design philosophy of utility-first both implicitly assume a human author.

But that assumption has changed. 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 is 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?

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."

If you've used TypeScript, you know this feeling. No developer memorizes every type rule. You don't need to. 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. You don't need to know everything upfront — the feedback loop converges you to correct code.

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.

The key insight: in this model, knowing the rules doesn't determine output quality. Convention-based design ties quality directly to knowledge — the more rules you know, the better your code. But in a feedback-driven design, you converge on the right answer just by running the loop, starting from zero knowledge. The same applies to humans and AI alike.

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. SpiraCSS verifies component structure and property placement through Stylelint, with error messages that include fix instructions — implementing the feedback loop described above.

Part 2: What Does "Resilient" Mean? — Defining Drift and Invariants
Part 3: The Feedback Loop — Designing Lint That Tells You What to Fix and How
Part 4: SpiraCSS Core Principles and Structure — Parent-Child Responsibilities and Block Decomposition
Part 5: Practical Adoption — Toolchain Integration and Setup

Next up, we define what "resilient" — drift-resistant — concretely means.

When you have AI agents write CSS, how do you maintain structural consistency? What's working, and what's falling apart?

→ Next: Part 2 — What Does "Resilient" Mean? — Defining Drift and Invariants

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