# ASW Positioning — Notes

Captured 2026-04-11 during explore session.

## The drift

ASW started as "agents write semantic HTML instead of class strings." But in practice it evolved: agents write markdown, packs handle everything, and the HTML output is itself agent-friendly.

## Three value layers

**1. Agent as author** — Write markdown + frontmatter. A pack (Hugo, Flask, Pandoc...) turns it into ASW-styled HTML. The agent never touches CSS or HTML.

**2. Agent as pack developer** — The semantic HTML contract. `<nav>`, `<article>`, `data-layout="docs"`, `data-task="blocked"` — a vocabulary for building templates that ASW styles automatically.

**3. Agent as reader** — ASW output is cheap to parse. Semantic HTML + data-attributes carry meaning in structure, not in class string noise. A downstream agent reading an ASW page consumes fewer tokens and understands more than reading a Tailwind/Bootstrap page.

## The round-trip story

```
Agent writes markdown
  → pack converts to semantic HTML
    → ASW styles it
      → another agent reads it back
        → structure IS meaning
```

Most CSS frameworks optimize for human visual output. ASW optimizes for round-trip agent legibility.

## Measurable claim (to verify)

"An ASW docs page uses ~40% fewer tokens to represent than the equivalent Tailwind page, while carrying more semantic information." Worth benchmarking.

## Where this should surface

- Homepage: update messaging to reflect all three layers, not just layer 2
- llms.txt: the agent-readable story
- Each pack: SKILLS.md specific to that pack's authoring workflow
- docs/lineage.md: how the framework evolved from "don't write CSS" to "write markdown"