# ASW — Agentic Semantic Web: Context Document

For agent sessions working in this repo. Read this before touching any CSS or layout file.

---

## What ASW is

A CSS framework built for agents, not humans.

LLMs generating web pages face a specific failure mode: given a class-based framework (Bootstrap, Tailwind), they must memorize presentation strings — `navbar-expand-lg`, `bg-gray-900`, `flex items-center justify-between`. These strings are arbitrary, version-dependent, and hallucination-prone. The agent spends cognition on presentation, not content.

ASW's answer: **don't give agents a presentation vocabulary. Give them a semantic one.**

Semantic HTML is what LLMs already produce naturally. `<nav>`, `<article>`, `<aside>`, `<details>` — these express structure through language. ASW makes that HTML look correct without the agent touching CSS.

**The agent directive:**
> Write semantic HTML. Use `data-*` attributes for vault-native concepts. Never write `style=`. Never invent classes. If ASW can't express it, document the gap.

---

## The core mechanism

Two layers of expressiveness:

**1. Semantic HTML elements** — styled directly, no classes needed:
```html
<nav>         →  top navigation bar
<article>     →  content card or post
<aside>       →  sidebar or TOC
<details>     →  accordion
<dialog>      →  modal
```

**2. `data-*` attributes** — for concepts HTML has no element for:
```html
data-task="done|todo|blocked|wip"
data-callout="note|tip|warning|error"
data-status="active|sleeping|blocked"
data-wikilink          →  vault note link
data-layout="docs|grid-2|grid-3|console"
data-toc               →  in-page table of contents
data-role="breadcrumb|steps|accordion|card"
```

The vocabulary is semantic, not stylistic. `data-task="blocked"` expresses meaning — the CSS handles appearance.

---

## Two repos, one framework

### `agentic-semantic-web/` (legacy)
The original standalone version. Single built file (`dist/agentic.css`), no dependencies, `--asw-*` prefixed variables. Proves the concept. Still deployed on Trentuna. Architecture doc and philosophy live here.

### `asw/` (current — this repo)
The Hugo-based rewrite. Same philosophy, rebuilt on Open Props as primitive token source. Multi-layer CSS architecture. Serves as both the framework source and its own documentation site.

The two diverge in:
- Variable naming: legacy uses `--asw-*` prefix, current uses unprefixed semantic aliases (`--text`, `--surface`, `--accent`)
- Token source: legacy has its own scale, current builds on Open Props
- Delivery: legacy is a single file, current is a Hugo site with PostCSS build

---

## Current architecture (`asw/`)

### Hugo site
```
content/
  docs/        →  framework documentation (type: docs)
  articles/    →  short-form writing — no TOC (type: article)
  essays/      →  long-form writing — TOC, description (type: essay)
  notes/       →  exported PKM vault notes (type: notes)
layouts/
  docs/        →  three-column docs layout
  console/     →  docs variant: sidebar flush to viewport edge
  notes/       →  notes/vault content layout
  essay/       →  long-form essay layout (TOC)
```

### CSS layer stack
```
assets/css/
  main.css              →  entry point, @import chain
  layers/
    00-reset.css        →  normalize + box-sizing
    01-asw.css          →  design tokens (Open Props aliases + ASW additions)
    02-semantic.css     →  typography, prose, syntax highlighting base
    03-components.css   →  landmarks + forms + components (being split — see refactor plan)
    04-data-attrs.css   →  all data-* attribute patterns
    05-utilities.css    →  text helpers, visibility, accessibility
    06-charts.css       →  Charts.css-inspired data visualization
    07-chroma.css       →  Hugo Chroma syntax highlighting
    08-layout.css       →  layout systems (docs, console, grids, prose)
    08a-essay.css       →  essay layout variant
    09-landing.css      →  landing page styles
```

### Token system
Open Props provides primitive scales (`--color-1..16`, `--size-1..15`, `--font-size-0..8`).
`01-asw.css` aliases these to semantic names:
```css
--surface:   var(--color-14)   /* not --color-14 directly */
--text:      var(--color-6)
--accent:    var(--color-8)
--space-4:   var(--size-3)
```
**Rule:** layers 02–08 must only reference semantic aliases, never Open Props primitives directly.

---

## Active work

### CSS layer refactor
`docs/css-refactor-plan.md` — full step-by-step plan.

The current `03-components.css` is a mixed bag: landmark styling (nav, article, footer), form elements, and true components (dialog, accordion) are all in one file. The plan splits it into purpose-specific files and fixes ~40 Open Props primitive leaks across the codebase.

**Do not start any CSS work without reading the refactor plan first.**

### Layout development
Two layouts exist: `docs` (standard three-column) and `console` (sidebar flush to viewport edge). The console layout is a prototype — no Hugo content type uses it in production yet.

### Pending CSS cleanup (`docs/css-html-cleanup-todo.md`)
- Hardcoded `"On this page"` strings need i18n before adding a second language

---

## Design principles

**Engine-agnostic** — Templates are prototyped in Hugo but must be portable to Flask/Jinja2. Hugo-specific features (render hooks, shortcodes) are acceptable prototyping tools, not load-bearing design. Template logic should express *what*, not *how*.

**No CSS classes on content** — The framework uses element selectors and `data-*` attributes. Class selectors (`[data-nav="sidebar"]`, `[data-role="breadcrumb"]`) are allowed for disambiguation but never for presentation.

**Semantic token naming** — Aliases express role, not value. `--surface` not `--gray-dark-3`. `--weight-medium` not `--font-weight-5`.

**Agent-first means sparse vocabulary** — Every `data-*` attribute added to the vocabulary is a cognitive load on every agent using the framework. Add only what cannot be expressed by existing semantic HTML.

---

## Lineage

| Source | What was taken |
|--------|----------------|
| Pico CSS | Component patterns (buttons, forms) — ported and modernized |
| Open Props | Primitive token scales — used as foundation, not bundled |
| Charts.css | `data-*` attribute pattern for extending HTML vocabulary |

ASW is not built on any of these. It learned from them.