Ludo
15a6db9c0e
- vault → notes (PKM-exported content) - posts → articles (short-form, no TOC) - papers → essays (long-form, with TOC) - type: post → type: article (posts are just short articles) - layouts/paper → layouts/essay - 08a-paper.css → 08a-essay.css - CSS: fix redundant li resets, remove role="main" from article, replace <small> prev/next labels, add console layout - Update hugo.toml menus, internal URLs, front matter throughout - Add docs/context.md, docs/css-refactor-plan.md
149 lines
6.3 KiB
Markdown
149 lines
6.3 KiB
Markdown
# 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.
|