trentuna/asw
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

refactor: rename content types to semantic taxonomy

Browse source 
- 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:
Ludo 2026-04-11 13:36:58 +02:00
parent 1408a52e8b
commit 15a6db9c0e
Signed by: ludo
GPG key ID: F6E479DEFAB84D6E
31 changed files with 788 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

149
docs/context.md Normal file
View 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.

221
docs/css-refactor-plan.md Normal file
View file

@ -0,0 +1,221 @@
# CSS Layer Refactor Plan
**Project:** ASW — Agentic Semantic Web
**Goal:** Restructure CSS layers to clean architecture, alias all Open Props primitives through `01-tokens.css`, redistribute misplaced content, remove unused values.
**Method:** One atomic step per agent session. Build check after every step. No step touches more than two files.
---
## Current state
```
assets/css/
main.css ← entry point, @import chain
layers/
00-reset.css
01-asw.css ← tokens + editorial rules (mixed)
02-semantic.css ← typography + prose styles
03-components.css ← landmarks + forms + components (mixed)
04-data-attrs.css ← data-* attribute patterns
05-utilities.css ← utility helpers
06-charts.css ← charts (uses --size-N primitives directly)
07-chroma.css ← syntax highlighting
08-layout.css ← layout systems
08a-essay.css ← paper layout variant
09-landing.css ← landing page styles
```
## Target state
```
assets/css/
main.css ← updated import chain
layers/
00-reset.css (unchanged)
01-tokens.css ← renamed from 01-asw.css, pure :root only, no rules
02-typography.css ← renamed from 02-semantic.css, prose + heading defaults
03-landmarks.css ← NEW: nav, article, aside, section, footer, hgroup
04-forms.css ← NEW: input, select, textarea, button
05-components.css ← slimmed 03-components.css: dialog, accordion, breadcrumb, steps
06-navigation.css ← NEW: sidebar nav, TOC (aside[data-toc])
07-data-attrs.css ← renamed from 04-data-attrs.css
08-utilities.css ← renamed from 05-utilities.css
09-charts.css ← renamed from 06-charts.css, primitives fixed
10-chroma.css ← renamed from 07-chroma.css
11-layout.css ← renamed from 08-layout.css + 08a-essay.css merged
12-landing.css ← renamed from 09-landing.css
```
---
## Primitive leak inventory
All Open Props primitives used directly in layers (must be aliased through 01-tokens.css):
### `--font-weight-N` (most common leak)
| Primitive | Semantic alias to add | Used in |
|---|---|---|
| `--font-weight-4` | `--weight-normal` | 03, 02, 08 |
| `--font-weight-5` | `--weight-medium` | 03, 02, 08 |
| `--font-weight-6` | `--weight-semibold` | 03 |
| `--font-weight-7` | `--weight-bold` | 02, 08, 09 |
### `--size-N` / `--size-px-N`
| Primitive | Alias | Notes |
|---|---|---|
| `--size-1` | `--space-1` (exists) | 06-charts |
| `--size-2` | `--space-2` (exists) | 06-charts |
| `--size-3` | `--space-4` (exists) | 03, 06-charts, 07-chroma |
| `--size-4` | needs `--space-5a: 1.25rem` | 03-components article padding |
| `--size-px-12` | `--dropdown-min-width` | 03-components nav dropdown |
### `--shadow-N`
| Primitive | Alias to add |
|---|---|
| `--shadow-2` | `--shadow-dropdown` |
| `--shadow-4` | `--shadow-modal` |
### `--border-size-2`
| Primitive | Alias to add |
|---|---|
| `--border-size-2` | `--focus-ring-width` |
---
## Step-by-step tasks
Each step = one agent session. Read only the files listed. Build after every step.
### STEP 1 — Add missing aliases to `01-asw.css` ✅ prerequisites: none
**Files:** `layers/01-asw.css` only
**Action:** Add to `:root {}`:
```css
/* Font weights */
--weight-normal: var(--font-weight-4);
--weight-medium: var(--font-weight-5);
--weight-semibold: var(--font-weight-6);
--weight-bold: var(--font-weight-7);
/* Shadows */
--shadow-dropdown: var(--shadow-2);
--shadow-modal: var(--shadow-4);
/* Focus ring */
--focus-ring-width: var(--border-size-2);
/* Dropdown */
--dropdown-min-width: var(--size-px-12);
/* Gap in spacing scale */
--space-5a: 1.25rem; /* between --space-4 (1rem) and --space-5 (1.5rem) */
```
**Verify:** `hugo server` builds without error. No visual change.
---
### STEP 2 — Extract editorial rules out of `01-asw.css` ✅ prerequisites: Step 1
**Files:** `layers/01-asw.css`, `layers/08-layout.css`
**Action:**
- Remove from `01-asw.css` the EDITORIAL DEFAULTS section (last ~10 lines: `body > nav` padding rule + `[data-layout="docs"] > article` max-width rule)
- Move `body > nav { padding-inline: ... }` to `03-components.css` under the Navigation section
- Move `[data-layout="docs"] > article { max-width: var(--width-prose) }` to `08-layout.css` under the docs layout section
**Verify:** Build passes. Nav centering and docs prose width unchanged visually.
---
### STEP 3 — Rename `01-asw.css` → `01-tokens.css` ✅ prerequisites: Step 2
**Files:** `layers/01-asw.css`, `main.css`
**Action:** Rename file, update `@import` in `main.css`.
**Verify:** Build passes.
---
### STEP 4 — Fix primitive leaks in `03-components.css` ✅ prerequisites: Step 1
**Files:** `layers/03-components.css` only
**Action:** Replace all primitive references with aliases:
- `var(--font-weight-4)` → `var(--weight-normal)`
- `var(--font-weight-5)` → `var(--weight-medium)` (including the fallback `, 500` variant)
- `var(--font-weight-6)` → `var(--weight-semibold)`
- `var(--size-3) var(--size-4)` → `var(--space-4) var(--space-5a)` (article padding, line 455)
- `var(--size-px-12)` → `var(--dropdown-min-width)`
- `var(--shadow-2)` → `var(--shadow-dropdown)`
- `var(--shadow-4)` → `var(--shadow-modal)`
- `var(--border-size-2)` → `var(--focus-ring-width)` (both occurrences)
**Verify:** Build passes. No visual change.
---
### STEP 5 — Fix primitive leaks in `06-charts.css` ✅ prerequisites: Step 1
**Files:** `layers/06-charts.css` only
**Action:** Replace all `--size-1/2/3` with `--space-1/2/4` respectively.
**Verify:** Build passes. Charts render unchanged.
---
### STEP 6 — Fix primitive leaks in remaining files ✅ prerequisites: Step 1
**Files:** `layers/02-semantic.css`, `layers/07-chroma.css`, `layers/08-layout.css`, `layers/09-landing.css` — one at a time
**Action:** Same find-replace for `--font-weight-N`, `--size-N` primitives.
**Verify:** Build passes after each file.
---
### STEP 7 — Create `03-landmarks.css` and extract from `03-components.css` ✅ prerequisites: Step 4
**Files:** `layers/03-components.css`, new `layers/03-landmarks.css`, `main.css`
**Action:** Move these sections out of `03-components.css` into `03-landmarks.css`:
- `body > nav` (the global nav landmark, lines ~259–442)
- `article` (lines ~444–506)
- `dt`, `dd` (lines ~508–529)
- `section + section`, `hgroup` (lines ~531–559)
- `body > footer` (lines ~561–572)
Add `@import "./layers/03-landmarks.css"` to `main.css` before `03-components.css`.
**Verify:** Build passes. All landmark styles render unchanged.
---
### STEP 8 — Create `04-forms.css` and extract from `03-components.css` ✅ prerequisites: Step 7
**Files:** `layers/03-components.css`, new `layers/04-forms.css`, `main.css`
**Action:** Move out of `03-components.css`:
- Buttons (lines ~14–75)
- Form Elements (lines ~77–258)
**Verify:** Build passes.
---
### STEP 9 — Create `06-navigation.css` and extract from `03-components.css` ✅ prerequisites: Step 8
**Files:** `layers/03-components.css`, new `layers/06-navigation.css`, `main.css`
**Action:** Move out of `03-components.css`:
- `nav[data-nav="sidebar"]` section
- `aside[data-toc]` section
**Verify:** Build passes. Sidebar and TOC render unchanged.
---
### STEP 10 — Rename remaining files + update `main.css` ✅ prerequisites: Steps 7–9
**Files:** all layer files + `main.css`
**Action:** Rename files to final numbers, merge `08a-essay.css` into `11-layout.css`, update all `@import` statements.
**Verify:** Build passes.
---
### STEP 11 — Audit unused tokens ✅ prerequisites: Step 10
**Method:** Tooling only — do not guess.
```bash
# Build the CSS, then grep for each token name
hugo --minify
grep -o 'var(--[^)]+)' public/**/*.css | sort | uniq > /tmp/used-tokens.txt
grep -o '\-\-[a-z][^:]*:' assets/css/layers/01-tokens.css | sort > /tmp/defined-tokens.txt
diff /tmp/defined-tokens.txt /tmp/used-tokens.txt
```
Review diff. Remove confirmed unused tokens from `01-tokens.css`.
**Verify:** Build passes. Spot-check 3–4 pages visually.
---
## Rules for all agents
1. Read only the files listed for your step — nothing else
2. Run build after every step before reporting done
3. Do not rename variables not listed in this plan
4. Do not touch `main.css` unless the step explicitly says to
5. Do not combine two steps in one session
6. If a primitive is found that isn't in the inventory above, add it to the plan doc and stop — do not fix it unilaterally

73
docs/template-h1-title.md Normal file
View file

@ -0,0 +1,73 @@
# Template Design: Handling the Markdown H1 / Front Matter Title Conflict
## The Problem
Standard markdown convention — Obsidian, agent-written files, generic `.md` — opens
with a level-1 heading as the document title:
```markdown
# My Note Title
Body text...
```
Hugo templates also render a title from front matter:
```html
<h1>{{ .Title }}</h1>
```
When both exist, the page gets two `<h1>` elements: one from the template,
one from the rendered markdown content. The content one also carries an
auto-generated `id` attribute from Hugo's heading anchor renderer.
## The Two Template Contracts
**Default (`_default/single.html`)** — bare markdown, minimal or no front matter.
The `# Title` in content IS the h1. The template header renders only metadata
(type, date, author, tags). No title rendered from front matter.
**Vault (`vault/single.html`)** — enriched front matter (`title`, `type`, `date`,
`author`, `tags`). Front matter `title` is authoritative. The `# Title` in content
is still present (markdown convention) but must be suppressed.
## The Fix: Engine-Agnostic Regex Strip
When a template owns the title (renders `<h1>{{ .Title }}</h1>` from front matter),
strip the first h1 from the rendered content before outputting it.
**Hugo:**
```
{{ replaceRE "<h1[^>]*>.*?</h1>" "" .Content 1 | safeHTML }}
```
**Jinja2 / Flask:**
```python
import re
content = re.sub(r'<h1[^>]*>.*?</h1>', '', content, count=1, flags=re.DOTALL)
```
**Nunjucks / Liquid / any engine:** equivalent string replace on the rendered HTML.
This is a string operation on already-rendered HTML, not a template-engine concept.
It ports to any engine without modification.
## Why Not Other Approaches
- **Author convention** (don't write `# Title` in vault files): breaks compatibility
with the entire markdown ecosystem.
- **Hugo render hooks** (`layouts/vault/_markup/render-heading.html`): Hugo-specific,
not portable.
- **CSS `display: none`**: h1 still exists in DOM — screen readers read it,
search engines index it. Semantically wrong.
## Engine-Agnostic Principle
ASW templates are prototyped in Hugo but must be portable to Flask/Jinja2 or
any other engine. Template logic should express *what*, not *how*:
- What: "strip h1 from content if front matter title is present"
- How: engine-specific implementation of the same string operation
Hugo-specific features (render hooks, shortcodes) are acceptable as prototyping
tools but should not become load-bearing parts of the template design.