refactor: rename content types to semantic taxonomy
- 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
This commit is contained in:
parent
1408a52e8b
commit
15a6db9c0e
GPG key ID:
F6E479DEFAB84D6E
31 changed files with 788 additions and 70 deletions
149
docs/context.md
Normal file
149
docs/context.md
Normal file
|
|
@ -0,0 +1,149 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue