asw/docs/lineage.md

# ASW Lineage

## Origins

ASW was born from a practical problem: agents generating HTML needed a CSS framework that matched how they think. Class-based frameworks (Bootstrap, Tailwind) require the agent to know presentation vocabulary. Semantic frameworks (Pico, Water) get closer, but still leave gaps — no agent-specific data vocabulary, no task states, no wikilinks, no callout types.

The original impulse was to take Pico CSS (the best classless framework) and extend it with data-attributes for agent-specific patterns. The result shipped as two files: `pico.min.css` + `agentic.css`. That architecture was honest about what it was — a patch on top of Pico — but it was the wrong long-term shape.

The overhaul mission (2026-03-29, executed by Vigilio Desto) transformed ASW into what it actually is: a standalone CSS framework where the semantic HTML layer, the token system, and the data-attribute vocabulary are all first-party. Pico is credited as donor material, not listed as a dependency.

---

## Pico CSS — The Foundation

Pico CSS (~84KB unminified) proved the core thesis: you can style semantic HTML meaningfully without requiring any classes. Its one concession — the `.container` class — was even that too far.

**What ASW absorbed from Pico:**
- Document resets and box-sizing
- Responsive typography scale
- Semantic element styling: headings, blockquotes, lists, `<hr>`
- Form element styling: inputs, selects, textareas, checkboxes, radios
- Table, button, code/pre, details/summary, dialog, progress, meter styling
- Focus and accessibility patterns (`prefers-reduced-motion`, `:focus-visible`, ARIA)

**What ASW pruned:**
- The `.container` class — replaced by detecting `<main>` directly
- `.grid` and other layout classes — replaced by `data-layout`
- Pico's color scheme system — ASW owns its design tokens
- Embedded SVG data URIs (~15KB of inline icons)
- Class-based link variants (`a.secondary`, `a.contrast`)

**The structural decision:** rather than Pico as a dependency, absorb it into a proper `@layer` hierarchy — `reset, base, semantic, components, data-attrs, utilities` — so ASW's data-attribute extensions always win over base semantics without specificity hacks. This is the difference between a patch and a framework.

Post-absorption: `--pico-*` references in dist went from 319 → 0. `--asw-*` references: 0 → 547.

---

## Open Props — The Token System

Open Props is a variables-only library (~30KB): no style rules, just a complete scale system — colors (0–12 per palette), spacing, font sizes, radii, easing functions. Its naming convention (`--{category}-{scale}`) is the right pattern for base tokens.

**The lesson ASW adopted:** a two-tier variable system.

**Tier 1 — base scales** (raw values, named by category and step):
```css
--asw-gray-0 through --asw-gray-12
--asw-space-1 through --asw-space-7
--asw-text-xs through --asw-text-4xl
```

**Tier 2 — semantic aliases** (what things mean, referencing base tokens):
```css
--asw-bg: var(--asw-gray-12);
--asw-accent: var(--asw-green-5);
--asw-border: var(--asw-gray-9);
```

**The customization contract this enables:** theme authors override only Tier 2 aliases (swap accent color, change background). A full rebrand overrides Tier 1 palettes. Dark/light mode swaps Tier 2 at `@media (prefers-color-scheme)` level. Tier 1 stays constant throughout — it's the scale, not the meaning.

Pico's flat variable naming (`--pico-font-family`, `--pico-border-radius`) was simple but not scalable for theming. Open Props showed what the right primitive looks like.

---

## Charts.css — The Data Attribute Pattern

Charts.css (MIT, 58.4KB min / 5.9KB gzip) turns `<table>` elements into charts using CSS classes. It already used semantic HTML — proper `<table>`, `<caption>`, `<thead>`, `<tbody>`, `scope` attributes. The only gap: it used classes instead of data-attributes.

**The insight that mattered:** Charts.css proved the data-attribute pattern scales to complex, multi-dimensional presentation. It uses CSS custom properties set directly on elements as the data input mechanism — `<td style="--size: 0.8;">` — and the chart CSS reads `calc(var(--size) * 100%)` to size bars. Data flows into CSS without JavaScript.

This is exactly ASW's philosophy extended to visualization. The conversion is mechanical:

| Charts.css | ASW |
|-----------|-----|
| `class="charts-css bar"` | `data-chart="bar"` |
| `class="multiple"` | `data-chart-datasets="multiple"` |
| `class="show-labels"` | `data-chart-axis-labels` (boolean presence) |
| `class="data-spacing-3"` | `data-chart-spacing="3"` |

The `--size` custom property pattern (element-scoped data injection, no JS) became a model for how ASW handles other data-driven components.

Charts.css absorption was scoped as a separate change from the Pico absorption, building on the established layer structure. At the time of the overhaul, ASW dist was ~49KB with 40% of that budget available for charts.

---

## Evolution

**Stage 1 — Pico extension (pre-2026)**
Two files: `pico.min.css` (external) + `agentic.css` (~15KB extensions). The data-attribute vocabulary existed but was a thin layer over Pico. Architecture: honest about what it was, wrong for the long term.

**Stage 2 — Standalone framework (2026-03-29)**
The overhaul mission absorbed Pico, adopted the Open Props two-tier token pattern, established the 9-layer `@layer` hierarchy, and dogfooded a real docs layout via `data-layout="docs"`. Single file. Zero dependencies. `agentic.css` is the framework.

**Stage 3 — Engine-agnostic with packs (current)**
The framework moved to a build pipeline (PostCSS), introduced the pack system for optional capability layers (charts, syntax highlighting, etc.), and separated concerns so ASW can serve any static site generator — not just Hugo, not just Trentuna's stack.

The through-line: semantic HTML as the contract, data-attributes as the extension vocabulary, CSS custom properties as the data injection mechanism. Agents write HTML that any browser can read; ASW makes it look right.