Philosophy

Why semantic HTML + data-attributes works better for agents than class-based frameworks.

The Problem

Every time an LLM generates a web page, it invents CSS.

Inline styles appear with arbitrary hex values (#3a7bd5, #f4f4f4, #1a1a1a), inconsistent spacing (margin: 12px vs margin: 1rem vs margin: 0.75em), random font stacks. Over multiple sessions — and worse, across multiple agents — this produces visual chaos.

The traditional solution is a CSS framework. But frameworks create a different problem.

Class-Based Frameworks

Bootstrap, Tailwind, and friends shift the burden from inventing CSS to memorizing class names:

For humans with autocomplete and years of muscle memory, this is tolerable. For LLMs operating across sessions with no persistent state, it's a different kind of chaos.

Semantic HTML as API

The insight behind ASW: HTML already has a rich vocabulary of meaning. <article>, <aside>, <nav>, <figure>, <blockquote>, <details>, <mark> — these elements carry intent that CSS can style reliably.

What's missing is a way to signal variation without classes. That's what data-* attributes provide:

<!-- A callout — no class names, meaning is self-evident -->
<div data-callout="warning">
  <span data-callout-title>Before you proceed</span>
  <p>This action cannot be undone.</p>
</div>

The data-attribute vocabulary is the API. An agent doesn't need to remember Bootstrap utility classes — it needs to know that data-callout="warning" produces a warning callout.

Why This Works for Agents

Predictability. The same semantic HTML + data-attribute combination produces the same visual output across every session, every agent, every tool.

Learnability. The vocabulary fits in a single prompt. Agents can be given llms.txt and immediately produce correct markup.

Legibility. <article data-callout="note"> is self-documenting. A human reviewing agent output can read the intent without decoding class soups.

Robustness. Semantic HTML degrades gracefully. Remove the stylesheet and the structure remains readable. That's not true of <div class="flex-col-gap-4-sm-hidden">.

The Agent Directive Pattern

ASW ships with a machine-readable directive block for embedding in system prompts:

<meta name="agent-directive" content="Use semantic HTML only. No inline styles. No custom CSS classes. Use data-attributes from agentic.css vocabulary.">

This single line makes the constraint explicit in a form agents can parse and enforce.

The Zero-Class Proof

The ultimate test of the framework: can it build its own homepage without a single custom CSS class? That question drives issue #64 — the homepage rebuild. If ASW can't dogfood its own vocabulary on its most visible page, the vocabulary is incomplete.

Every gap is a roadmap entry.