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

feat: add OpenSpec specs and changes for ASW restructure

Browse source 
Specs: repo-structure, 10 framework layer specs, packs, site.
Changes: repo-restructure (10 tasks), css-refactor (12 tasks),
legacy-import (proposal + triage categories).

Supersede docs/css-refactor-plan.md in favor of OpenSpec change.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ludo 2026-04-11 14:58:39 +02:00
parent ecfbed0374
commit 5bf233348d
Signed by: ludo
GPG key ID: F6E479DEFAB84D6E
21 changed files with 1110 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

60
openspec/changes/css-refactor/proposal.md Normal file
View file

@ -0,0 +1,60 @@
# Proposal: CSS Layer Refactor
## Intent
Restructure CSS layers to clean architecture: alias all Open Props primitives through `01-tokens.css`, split the monolithic `03-components.css` into purpose-specific files, redistribute misplaced content, and rename files to match their actual responsibilities.
**Goal: each CSS file has a single clear purpose, and no file references Open Props primitives directly.**
This plan was originally documented in `docs/css-refactor-plan.md` and is imported here as an OpenSpec change for tracking and execution.
## Scope
### In Scope
- Add missing semantic aliases to token file (~10 new aliases)
- Extract editorial rules out of token file into their proper layers
- Rename `01-asw.css` → `01-tokens.css` (pure tokens, no rules)
- Fix all Open Props primitive leaks across all layers
- Split `03-components.css` into: `03-landmarks.css`, `04-forms.css`, slimmed `05-components.css`, `06-navigation.css`
- Rename all files to final numbering scheme
- Merge `08a-essay.css` into layout layer
- Audit and remove unused tokens
### Out of Scope
- New CSS features or components
- Layout changes
- Content changes
- Repo restructure (separate change, happens first)
### Current → Target Layer Map
```
CURRENT TARGET
═══════ ══════
00-reset.css 00-reset.css (unchanged)
01-asw.css ──▶ 01-tokens.css (pure :root, no rules)
02-semantic.css ──▶ 02-typography.css
03-components.css ──▶ 03-landmarks.css (nav, article, footer, hgroup)
──▶ 04-forms.css (inputs, buttons, selects)
──▶ 05-components.css (dialog, accordion, breadcrumb)
──▶ 06-navigation.css (sidebar, TOC)
04-data-attrs.css ──▶ 07-data-attrs.css
05-utilities.css ──▶ 08-utilities.css
06-charts.css ──▶ 09-charts.css
07-chroma.css ──▶ 10-chroma.css
08-layout.css + 08a-essay ──▶ 11-layout.css (merged)
09-landing.css ──▶ 12-landing.css
```
## Approach
One atomic step per session. Build check after every step. No step touches more than two files. Full plan in `docs/css-refactor-plan.md`.
## Prerequisites
- **Depends on:** `repo-restructure` (files must be in `src/layers/` first)
## Risks
- **Visual regression** — mitigated by build + visual check after each step
- **Specificity changes** — layer reordering could affect cascade. Mitigated by keeping relative order.

94
openspec/changes/css-refactor/tasks.md Normal file
View file

@ -0,0 +1,94 @@
# Tasks: CSS Layer Refactor
Imported from `docs/css-refactor-plan.md`. Each step = one agent session.
**Prerequisite:** `repo-restructure` change must be complete. All files in `src/layers/`.
---
## Task 1 — Add missing aliases to token file
**Files:** `src/layers/01-asw.css` (pre-rename)
**Action:** Add semantic aliases for `--font-weight-N`, `--shadow-N`, `--border-size-2`, `--size-px-12`, and `--space-5a` gap.
**Acceptance:** Build passes. No visual change. New aliases exist in `:root`.
---
## Task 2 — Extract editorial rules from token file
**Files:** `src/layers/01-asw.css`, `src/layers/08-layout.css`
**Action:** Move `body > nav` padding rule to `03-components.css`. Move `[data-layout="docs"] > article` max-width to `08-layout.css`. Token file becomes pure `:root` only.
**Acceptance:** Build passes. Nav centering and docs prose width unchanged.
---
## Task 3 — Rename `01-asw.css` → `01-tokens.css`
**Files:** `src/layers/01-asw.css`, `src/main.css`
**Action:** Rename file, update `@import`.
**Acceptance:** Build passes.
---
## Task 4 — Fix primitive leaks in `03-components.css`
**Files:** `src/layers/03-components.css`
**Action:** Replace all `--font-weight-N`, `--size-N`, `--shadow-N`, `--border-size-N` with semantic aliases.
**Acceptance:** Build passes. No visual change.
---
## Task 5 — Fix primitive leaks in `06-charts.css`
**Files:** `src/layers/06-charts.css`
**Action:** Replace `--size-1/2/3` with `--space-1/2/4`.
**Acceptance:** Build passes. Charts render unchanged.
---
## Task 6 — Fix primitive leaks in remaining files
**Files:** `src/layers/02-semantic.css`, `src/layers/07-chroma.css`, `src/layers/08-layout.css`, `src/layers/09-landing.css`
**Action:** Replace all remaining `--font-weight-N`, `--size-N` primitives with semantic aliases.
**Acceptance:** Build passes after each file.
---
## Task 7 — Create `03-landmarks.css`, extract from `03-components.css`
**Files:** `src/layers/03-components.css`, new `src/layers/03-landmarks.css`, `src/main.css`
**Action:** Move landmark sections (nav, article, dt/dd, section, hgroup, footer) to new file.
**Acceptance:** Build passes. All landmark styles render unchanged.
---
## Task 8 — Create `04-forms.css`, extract from `03-components.css`
**Files:** `src/layers/03-components.css`, new `src/layers/04-forms.css`, `src/main.css`
**Action:** Move buttons and form elements to new file.
**Acceptance:** Build passes.
---
## Task 9 — Create `06-navigation.css`, extract from `03-components.css`
**Files:** `src/layers/03-components.css`, new `src/layers/06-navigation.css`, `src/main.css`
**Action:** Move sidebar nav and TOC sections to new file.
**Acceptance:** Build passes. Sidebar and TOC render unchanged.
---
## Task 10 — Rename files to final numbering + merge essay
**Files:** All layer files, `src/main.css`
**Action:** Rename to final numbers (see proposal layer map). Merge `08a-essay.css` into `11-layout.css`. Update all `@import` statements.
**Acceptance:** Build passes.
---
## Task 11 — Audit unused tokens
**Files:** `src/layers/01-tokens.css`
**Action:** Build CSS, grep for token usage, diff defined vs used. Remove confirmed unused.
**Acceptance:** Build passes. Spot-check 3-4 pages visually.
---
## Task 12 — Fix HTML template issues from sidebar/TOC refactor
**Files:** `site/layouts/docs/single.html`, `site/layouts/notes/single.html` (post-restructure paths)
**Action:** From `docs/css-html-cleanup-todo.md`:
- Remove redundant `nav[data-nav="sidebar"] ul li { margin: 0; padding: 0 }` resets (if not already caught in Tasks 7/9)
- Remove redundant `aside[data-toc] nav ul li { margin: 0; padding: 0 }` resets (if not already caught in Tasks 7/9)
- Replace `<small>← Previous</small>` / `<small>Next →</small>` with appropriate element in prev/next footer
- Remove `role="main"` from `<article>` in docs single layout
- Move hardcoded `"On this page"` string to Hugo i18n or site param
**Acceptance:** Build passes. Prev/next links render correctly. TOC heading uses i18n string. No `role="main"` on `<article>`.

78
openspec/changes/legacy-import/proposal.md Normal file
View file

@ -0,0 +1,78 @@
# Proposal: Legacy Import
## Intent
Import valuable material from `agentic-semantic-web/` (legacy repo) into the restructured `asw/` repo. The legacy repo was the standalone single-file version of ASW. It contains packs, templates, examples, lab experiments, error pages, and documentation that belong in the current repo.
**Goal: everything worth keeping lives in `asw/`. Legacy repo is archived.**
## Scope
### Triage Categories
Material from `agentic-semantic-web/` falls into:
**Import as-is:**
- `packs/apache/` → `packs/apache/`
- `packs/caddy/` → `packs/caddy/`
- `packs/flask/` → `packs/flask/`
- `packs/nginx/` → `packs/nginx/`
- `packs/pandoc/` → `packs/pandoc/`
- `packs/python/` → `packs/python/`
- `packs/hugo/` → `packs/hugo/` (base Hugo pack)
- `errors/` → `packs/` (distributed to relevant packs, or shared errors dir)
- `LICENSE`
**Import and adapt:**
- `examples/` → `examples/` (update CSS paths to `dist/asw.css`)
- `templates/` → review, merge into packs or docs
- `llms.txt` → `docs/llms.txt` (update for current state)
- `content/vocabulary.md` → `docs/vocabulary.md`
- `content/philosophy.md` → `docs/` (may already exist)
- `content/agent-directive.md` → `docs/` or merge into existing docs
- `themes/` → `src/themes/` or `examples/themes/` (needs decision)
**Import as reference/lineage:**
- `openspec/changes/pico-absorption/` → content for `docs/lineage.md`
- `content/architecture.md`, `content/design-tokens.md` → inform specs, don't import verbatim
- `MISSION_REPORT.md`, `SIZE_AUDIT.md` → historical, extract lessons into lineage
**Do not import:**
- `dist/agentic.css` — superseded by `dist/asw.css`
- `agentic.css` (root) — old entry point
- `src/layers/` — superseded by current `src/layers/`
- `build.sh`, `migrate-tokens.sh` — legacy build tools
- `web-fonts.css` — evaluate if still needed
- `lib/open-props/` — replaced by `vendor/open-props/`
- `lab/hugo-demo/` — superseded by `site/`
- `.pi/` — agent config, not framework material
- `index.html` — legacy landing page
**Needs triage decision:**
- `lab/` (non-Hugo) — some experiments may be worth keeping in `src/lab/`
- `docs/missions/` — historical mission reports, lineage value?
- `content/charts-css-exploration.md` — inform charts spec?
- `content/architecture-research.md` — inform design decisions?
### Out of Scope
- Modifying imported CSS (that's the css-refactor change)
- Creating new content
- Archiving the legacy repo (separate operational task)
## Prerequisites
- **Depends on:** `repo-restructure` (directories must exist first)
## Approach
1. Triage: review each directory/file, confirm category
2. Import packs (bulk, low risk)
3. Import examples (need path updates)
4. Import docs (need review/merge)
5. Write `docs/lineage.md` from pico-absorption and historical material
6. Final audit: nothing valuable left behind
## Risks
- **Stale content** — legacy material references `agentic.css`, old paths, old URLs. All imported material needs path/name updates.
- **Duplication** — some legacy content already exists in ASW in evolved form. Need careful merge, not overwrite.

115
openspec/changes/repo-restructure/design.md Normal file
View file

@ -0,0 +1,115 @@
# Design: Repository Restructure
## Current → Target Mapping
```
CURRENT TARGET
═══════ ══════
assets/css/layers/*.css ──▶ src/layers/*.css
assets/css/main.css ──▶ src/main.css
(new) ──▶ src/lab/
static/asw.css ──▶ dist/asw.css
(new) ──▶ dist/asw.min.css
static/vendor/ ──▶ vendor/open-props/
(new) ──▶ vendor/open-props/VERSION
(new) ──▶ vendor/README.md
content/ ──▶ site/content/
layouts/ ──▶ site/layouts/
archetypes/ ──▶ site/archetypes/
hugo.toml ──▶ site/hugo.toml
static/ (non-vendor) ──▶ site/static/
docs/ ──▶ docs/ (stays, add new docs)
(new) ──▶ examples/
postcss.config.js ──▶ postcss.config.js (updated paths)
package.json ──▶ package.json (stays at root)
node_modules/ ──▶ node_modules/ (stays at root)
```
## Key Design Decisions
### Hugo assets resolution
Hugo looks for `assets/` relative to the site root. With Hugo files in `site/`, we need either:
- **Option A:** `site/assets/css/main.css` that imports from `../../src/layers/` — fragile
- **Option B:** Hugo module mount maps `src/` into Hugo's asset pipeline — clean
**Decision: Option B.** Hugo config in `site/hugo.toml`:
```toml
[[module.mounts]]
source = "static"
target = "static"
[[module.mounts]]
source = "../src"
target = "assets/css"
[[module.mounts]]
source = "../docs"
target = "content/docs"
[[module.mounts]]
source = "../vendor/open-props"
target = "assets/css/open-props"
```
This way Hugo sees `src/layers/` as `assets/css/layers/` and `src/main.css` as `assets/css/main.css` — zero path changes in the CSS files themselves.
### Vendor directory
```
vendor/
open-props/
open-props.min.css
media.min.css
VERSION ← "1.7.x (npm open-props@1.7.x, vendored 2025-xx-xx)"
README.md ← "How to update: npm update open-props && cp ..."
```
`npm install` still works for the build toolchain. `vendor/` is the inspectable, committed copy with version tracking. The build reads from `node_modules/` (PostCSS import resolution), but agents and humans can read `vendor/` to understand what Open Props provides.
### dist/ generation
`dist/asw.css` is built by PostCSS from `src/main.css`:
```bash
npx postcss src/main.css -o dist/asw.css
npx postcss src/main.css -o dist/asw.min.css # with cssnano
```
Committed to repo. Consumers grab `dist/asw.css` without needing npm/PostCSS.
### examples/ structure
```
examples/
components/ ← buttons, forms, callouts, dialogs
layout/ ← docs layout, grid, prose, timeline
charts/ ← chart showcases
vault/ ← vault note rendering examples
```
Each HTML file is standalone: `<link rel="stylesheet" href="../dist/asw.css">`. Open in browser, no build step.
### dev workflow
`dev.sh` (or its successor) runs from project root:
1. Watches `src/layers/` for changes
2. Processes individual layers → somewhere Hugo can serve them (for devtools visibility)
3. Runs `hugo server` with working directory `site/`
The key change: Hugo is invoked as `hugo server --source site/` or from within `site/`.
## What Stays at Root
```
asw/
package.json ← build tooling (PostCSS, Open Props)
postcss.config.js ← production PostCSS config
postcss.dev.config.js ← dev PostCSS config
node_modules/ ← npm packages (gitignored)
.gitignore
README.md
LICENSE
openspec/
```
Build tooling stays at root because it serves both `dist/` (framework build) and `site/` (dev server). It's a project-level concern, not framework or site.

42
openspec/changes/repo-restructure/proposal.md Normal file
View file

@ -0,0 +1,42 @@
# Proposal: Repository Restructure
## Intent
The ASW repo currently has a flat Hugo-centric layout where framework source, website content, and build tooling are interleaved. This restructure separates the framework (`src/`), its documentation (`docs/`), its engine integrations (`packs/`), its built output (`dist/`), its dependencies (`vendor/`), and its website (`site/`) into clearly bounded directories.
**Goal: anyone landing on this repo immediately understands what ASW is and where things live.**
## Scope
### In Scope
- Move `assets/css/layers/` → `src/layers/`
- Move `assets/css/main.css` → `src/main.css`
- Create `dist/` at root for built output (`asw.css`, `asw.min.css`)
- Create `vendor/open-props/` with vendored copies + VERSION file
- Move Hugo files (`content/`, `layouts/`, `hugo.toml`, `archetypes/`) → `site/`
- Configure Hugo module mount: `docs/` → `site/content/docs/`
- Restructure `docs/` as engine-agnostic markdown (already mostly there)
- Create `src/lab/` for experiments
- Create `examples/` at root for static HTML showcases
- Update build paths in `postcss.config.js` and `package.json`
### Out of Scope
- CSS refactor (separate change, works on `src/layers/` after this)
- Legacy repo import (separate change, lands material after this)
- Content writing or new docs
- New pack creation
## Approach
Incremental moves with build verification after each step. The site must remain buildable and deployable throughout.
## Risks
- **Hugo path breakage** — Hugo has opinions about where `assets/` lives. Module mounts should handle this but need testing.
- **Deploy script breakage** — `deploy.sh` hardcodes paths. Will need updating (or removal if temporary).
- **Symlink/mount complexity** — `docs/` → `site/content/docs/` via Hugo mount is clean but adds config complexity.
## Files Touched
Primary: `assets/css/`, `content/`, `layouts/`, `hugo.toml`, `postcss.config.js`, `package.json`
Created: `src/`, `dist/`, `vendor/`, `site/`, `examples/`, `src/lab/`

115
openspec/changes/repo-restructure/tasks.md Normal file
View file

@ -0,0 +1,115 @@
# Tasks: Repository Restructure
## Task 1 — Create directory skeleton
**Files:** (new directories only)
**Action:**
- Create `src/`, `src/layers/`, `src/lab/`
- Create `dist/`
- Create `vendor/open-props/`
- Create `site/`
- Create `examples/`
**Acceptance:** Directories exist. No files moved yet. Build still passes from current layout.
---
## Task 2 — Move CSS source to src/
**Files:** `assets/css/layers/*.css` → `src/layers/`, `assets/css/main.css` → `src/main.css`
**Action:**
- `git mv assets/css/layers/ src/layers/`
- `git mv assets/css/main.css src/main.css`
- Update `@import` paths in `src/main.css` if needed (should be relative, likely unchanged)
**Acceptance:** `src/layers/` contains all 11 CSS files. `src/main.css` imports them. `assets/css/` is gone.
**Note:** Site will be temporarily broken until Hugo mounts are configured (Task 5).
---
## Task 3 — Set up vendor/
**Files:** `vendor/open-props/`, `vendor/README.md`
**Action:**
- Copy `node_modules/open-props/open-props.min.css` → `vendor/open-props/`
- Copy `node_modules/open-props/media.min.css` → `vendor/open-props/`
- Create `vendor/open-props/VERSION` with package version and date
- Create `vendor/README.md` explaining what's vendored and how to update
- Remove `static/vendor/` (old location)
**Acceptance:** `vendor/open-props/` contains the two CSS files + VERSION. `static/vendor/` is gone.
---
## Task 4 — Move Hugo files to site/
**Files:** `content/`, `layouts/`, `archetypes/`, `hugo.toml`, `hugo_stats.json`
**Action:**
- `git mv content/ site/content/`
- `git mv layouts/ site/layouts/`
- `git mv archetypes/ site/archetypes/`
- `git mv hugo.toml site/hugo.toml`
- `git mv hugo_stats.json site/hugo_stats.json`
- Move site-specific static files: `static/palette-test.html` → `site/static/`
- Move `static/asw.css` → `dist/asw.css` (this is the built output)
**Acceptance:** All Hugo content/layout/config files are in `site/`. Root has no Hugo files.
---
## Task 5 — Configure Hugo module mounts
**Files:** `site/hugo.toml`
**Action:** Add module mounts:
- `../src` → `assets/css` (framework CSS in Hugo's asset pipeline)
- `../docs` → `content/docs` (framework docs as site content)
- `../vendor/open-props` → `assets/css/open-props` (Open Props in asset pipeline)
- `static` → `static` (site's own static files)
**Acceptance:** `hugo server --source site/` builds successfully. All pages render. CSS loads correctly.
---
## Task 6 — Build dist/asw.css from new paths
**Files:** `postcss.config.js`, `package.json`
**Action:**
- Update PostCSS config if paths changed
- Run: `npx postcss src/main.css -o dist/asw.css`
- Run: `npx postcss src/main.css -o dist/asw.min.css`
- Verify output matches previous `static/asw.css`
- Add npm scripts to `package.json`: `"build": "postcss src/main.css -o dist/asw.css"`
**Acceptance:** `dist/asw.css` exists and is equivalent to the previous build. `npm run build` works.
---
## Task 7 — Restructure docs/
**Files:** `docs/`
**Action:**
- Existing docs stay: `context.md`, `css-refactor-plan.md`, `css-html-cleanup-todo.md`, `frontmatter.md`, `template-h1-title.md`
- Verify Hugo mount serves them at `content/docs/`
- Add `docs/llms.txt` (move from legacy or create)
- Add `docs/lineage.md` placeholder (Pico absorption story, Open Props relationship)
**Acceptance:** Framework docs are all in `docs/`. Hugo renders them as site pages via mount.
---
## Task 8 — Create examples/ from site content
**Files:** `examples/`
**Action:**
- Identify existing pages that are pure component/layout demos
- Create standalone HTML versions in `examples/` that load `dist/asw.css`
- Organize into `examples/components/`, `examples/layout/`, `examples/charts/`, `examples/vault/`
**Acceptance:** At least 3 example files exist, each standalone and openable in a browser.
---
## Task 9 — Update .gitignore and clean up
**Files:** `.gitignore`, root directory
**Action:**
- Update `.gitignore` for new paths
- Remove empty `assets/` directory if still present
- Remove `static/css/layers/` (dev-mode output, will be regenerated)
- Verify no orphaned files remain in old locations
**Acceptance:** `git status` is clean. No files in old locations. `.gitignore` covers `node_modules/`, `site/public/`, `site/resources/`.
---
## Task 10 — Verify full build cycle
**Files:** (none modified, verification only)
**Action:**
- `npm run build` → `dist/asw.css` generated
- `hugo --source site/` → `site/public/` generated
- Spot-check 3-4 pages visually
- Verify `docs/` content appears in site
- Verify CSS loads and renders correctly
**Acceptance:** Full build passes. Site looks identical to pre-restructure. dist/ output is valid.