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):

--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):

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