asw/docs/context.md

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:

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

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:

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