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

2
docs/css-refactor-plan.md
View file

@ -1,5 +1,7 @@
# CSS Layer Refactor Plan # CSS Layer Refactor Plan
> **Superseded by:** `openspec/changes/css-refactor/` — this document is kept as historical reference. Agents should read the OpenSpec change tasks, not this file.
**Project:** ASW — Agentic Semantic Web **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. **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. **Method:** One atomic step per agent session. Build check after every step. No step touches more than two 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.

48
openspec/config.yaml Normal file
View file

@ -0,0 +1,48 @@
schema: spec-driven
context: |
Project: ASW — Agentic Semantic Web
Purpose: A CSS framework built for agents, not humans. Semantic HTML + data-* attributes.
Core idea: LLMs produce semantic HTML naturally. ASW makes that HTML look correct
without the agent touching CSS. No classes, no inline styles, no presentation vocabulary.
Stack: Pure CSS framework. PostCSS build (postcss-import, postcss-custom-media, cssnano).
Foundation: Open Props provides primitive token scales; ASW aliases them to semantic names.
Engine-agnostic: ASW ships as CSS + packs. Packs integrate with Hugo, Apache, Caddy,
Flask, Nginx, Pandoc, Python. The framework's own website currently uses the Hugo pack.
Repo structure (target):
src/ — framework CSS source (layers/) and lab experiments (lab/)
dist/ — built output: asw.css, asw.min.css
vendor/ — explicit dependencies (Open Props with version tracking)
packs/ — engine integration bundles
docs/ — framework documentation (markdown only, engine-agnostic)
examples/ — static HTML showcases of framework capabilities
site/ — the ASW website (currently Hugo, consumes docs/ as content)
openspec/ — specs and changes
Key constraint: layers 02+ must only reference semantic aliases from 01-tokens.css,
never Open Props primitives directly.
Lineage: Pico CSS (component patterns, absorbed), Open Props (token scales, foundation),
Charts.css (data-* attribute pattern, inspiration).
Forgejo: git.trentuna.com/trentuna/asw
Legacy repo: git.trentuna.com/trentuna/agentic-semantic-web (to be archived after import)
rules:
proposal:
- Keep scope tight — this is a CSS framework, not a JS library
- Name the files that will be touched
- Consider impact on existing deployed pages (trentuna.com)
specs:
- Use Given/When/Then for behavior scenarios
- Specs should be testable by visual inspection in a browser
- Map 1:1 to CSS layer files where applicable
tasks:
- Each task should be a standalone unit of work for a single agent session
- Include acceptance criteria
- No task should touch more than 3 files
- Build check after every task

32
openspec/specs/framework/charts/spec.md Normal file
View file

@ -0,0 +1,32 @@
# Spec: Charts (Layer 09)
File: `src/layers/09-charts.css`
## Purpose
Data visualization using pure CSS and HTML tables. Inspired by Charts.css — uses `data-*` attributes to transform tables into visual charts.
## Scope
### In scope
- Bar charts (horizontal and vertical)
- Line charts
- Area charts
- Radial/gauge charts
- Chart axes, labels, legends
- Responsive chart sizing
- Chart color schemes using design tokens
### Out of scope
- JavaScript-powered charts
- Interactive chart features (tooltips on hover are CSS-only)
## Lineage
Inspired by Charts.css `data-*` attribute pattern. Not a port — reimplemented for ASW's token system and semantic approach.
## Constraints
- References only semantic aliases from `01-tokens.css`
- Charts must be readable without CSS (the underlying table has the data)
- Color choices must work for colorblind users

26
openspec/specs/framework/components/spec.md Normal file
View file

@ -0,0 +1,26 @@
# Spec: Components (Layer 05)
File: `src/layers/05-components.css`
## Purpose
Compound UI patterns that go beyond single-element semantics. These are patterns that require specific HTML structures.
## Scope
### In scope
- `dialog` — modal dialogs
- `details` / `summary` — accordion pattern
- Breadcrumb navigation (`[data-role="breadcrumb"]`)
- Step indicators (`[data-role="steps"]`)
### Out of scope
- Single HTML elements with default styling (→ landmarks, typography, forms)
- Sidebar navigation (→ navigation layer)
- Charts (→ charts layer)
- Data-attribute vocabulary (→ data-attributes layer)
## Constraints
- This layer should be small — if a pattern can be expressed by a semantic HTML element alone, it belongs in landmarks or typography, not here
- References only semantic aliases from `01-tokens.css`

42
openspec/specs/framework/data-attributes/spec.md Normal file
View file

@ -0,0 +1,42 @@
# Spec: Data Attributes (Layer 07)
File: `src/layers/07-data-attrs.css`
## Purpose
The ASW vocabulary extension layer. `data-*` attributes express concepts that HTML has no native element for. This is the core differentiator — the semantic vocabulary agents use.
## Vocabulary
### Task states
- `data-task="done|todo|blocked|wip"` — task status indicators
### Callouts
- `data-callout="note|tip|warning|error"` — admonition blocks
### Status
- `data-status="active|sleeping|blocked"` — entity status
### Links
- `data-wikilink` — vault/wiki-style note links
### Layout
- `data-layout="docs|grid-2|grid-3|console"` — page layout selection
### Table of contents
- `data-toc` — marks an element as an in-page TOC
### Roles
- `data-role="breadcrumb|steps|accordion|card"` — component role disambiguation
## Design Principle
Every `data-*` attribute added to the vocabulary is cognitive load on every agent using the framework. Add only what cannot be expressed by existing semantic HTML.
**The bar for addition:** "Can this be expressed with an existing HTML element?" If yes, don't add a data attribute.
## Constraints
- References only semantic aliases from `01-tokens.css`
- Each attribute must have a clear semantic meaning (not stylistic)
- Attribute values should be exhaustive and documented

30
openspec/specs/framework/forms/spec.md Normal file
View file

@ -0,0 +1,30 @@
# Spec: Forms (Layer 04)
File: `src/layers/04-forms.css`
## Purpose
Form element styling. Inputs, selects, textareas, buttons, checkboxes, radios, fieldsets, labels. Accessible by default.
## Scope
### In scope
- `button`, `input[type="button"]`, `input[type="submit"]`, `input[type="reset"]`
- `input[type="text|email|password|number|search|url|tel|date|time|datetime-local"]`
- `select`, `textarea`
- `fieldset`, `legend`, `label`
- `input[type="checkbox"]`, `input[type="radio"]`
- `progress`, `meter`
- `:focus-visible` ring styling
- `aria-invalid`, `aria-busy` states
- `[disabled]` styling
### Out of scope
- Form layout/grid (→ layouts layer)
- Custom form components built with data-attributes (→ data-attributes layer)
## Constraints
- References only semantic aliases from `01-tokens.css`
- All interactive elements must have visible focus indicators
- Respects `prefers-color-scheme` and `prefers-contrast`

29
openspec/specs/framework/landmarks/spec.md Normal file
View file

@ -0,0 +1,29 @@
# Spec: Landmarks (Layer 03)
File: `src/layers/03-landmarks.css`
## Purpose
Styling for HTML landmark elements — the structural bones of a page. These elements convey document structure to both browsers and screen readers.
## Scope
### In scope
- `body > nav` — global navigation bar
- `article` — content card or post
- `aside` — sidebar panels
- `section` — content grouping
- `body > footer` — global footer
- `hgroup` — heading groups
- `header` within landmarks
- `dt`, `dd` — definition lists (structural, not component)
### Out of scope
- Navigation menus and dropdowns (→ navigation layer)
- Sidebar nav behavior `nav[data-nav="sidebar"]` (→ navigation layer)
- Article styling within specific layouts (→ layouts layer)
## Constraints
- References only semantic aliases from `01-tokens.css`
- Landmark styling should be layout-independent — works in any `data-layout`

42
openspec/specs/framework/layouts/spec.md Normal file
View file

@ -0,0 +1,42 @@
# Spec: Layouts (Layer 11)
File: `src/layers/11-layout.css`
## Purpose
Page-level layout systems. Controls how landmarks arrange on the page. Selected via `data-layout` attribute.
## Layout Types
### `data-layout="docs"` — Documentation
Three-column layout: sidebar navigation, main content, table of contents. The standard documentation pattern.
### `data-layout="console"` — Console
Docs variant: sidebar flush to viewport edge. Prototype — not yet used in production.
### `data-layout="grid-2"` / `data-layout="grid-3"` — Grids
Multi-column content grids for cards, galleries, dashboards.
### Essay layout
Long-form prose with table of contents. Wider reading measure, typographic refinements.
### Prose width
`--width-prose` constrains content to readable line length within any layout.
## Scope
### In scope
- `data-layout` attribute styling
- Prose width constraints
- Responsive layout breakpoints
- Essay/long-form layout variant
### Out of scope
- Landmark styling within layouts (→ landmarks layer)
- Navigation behavior within layouts (→ navigation layer)
## Constraints
- References only semantic aliases from `01-tokens.css`
- Layouts must degrade gracefully on mobile (single column)
- No layout should require JavaScript

27
openspec/specs/framework/navigation/spec.md Normal file
View file

@ -0,0 +1,27 @@
# Spec: Navigation (Layer 06)
File: `src/layers/06-navigation.css`
## Purpose
Navigation patterns that go beyond the basic `nav` landmark. Sidebar navigation, table of contents, dropdown menus, navigation state management.
## Scope
### In scope
- `nav[data-nav="sidebar"]` — sidebar navigation tree
- `aside[data-toc]` — in-page table of contents
- Dropdown menus within navigation
- Active/current page indicators (`aria-current`)
- Mobile navigation patterns
- Navigation collapse/expand behavior
### Out of scope
- The `body > nav` landmark itself (→ landmarks layer)
- Breadcrumbs (→ components layer)
## Constraints
- References only semantic aliases from `01-tokens.css`
- Navigation must be keyboard-accessible
- Active states use `aria-current`, not classes

77
openspec/specs/framework/tokens/spec.md Normal file
View file

@ -0,0 +1,77 @@
# Spec: Tokens (Layer 01)
File: `src/layers/01-tokens.css`
## Purpose
Pure design token definitions. Aliases Open Props primitives to semantic names. Contains only `:root {}` variable declarations — no rules, no selectors, no styling.
## Open Props Dependency
ASW builds on Open Props as its primitive token source. Open Props provides:
- Color scales: `--color-0` through `--color-16`
- Size scale: `--size-1` through `--size-15`, `--size-px-1` through `--size-px-12`
- Font sizes: `--font-size-0` through `--font-size-8`
- Font weights: `--font-weight-1` through `--font-weight-9`
- Shadows: `--shadow-1` through `--shadow-6`
- Border sizes: `--border-size-1` through `--border-size-5`
- Animations, easings, gradients, and more
**Version:** tracked in `vendor/open-props/VERSION`
## Aliasing Contract
Every Open Props primitive used in the framework MUST be aliased through this file. Downstream layers (02+) MUST reference semantic aliases, never primitives.
```css
/* YES — downstream layers use this */
color: var(--text);
font-weight: var(--weight-bold);
padding: var(--space-4);
/* NO — never in layers 02+ */
color: var(--color-6);
font-weight: var(--font-weight-7);
padding: var(--size-3);
```
## Token Categories
### Colors
- `--surface`, `--surface-alt` — background colors
- `--text`, `--text-muted` — foreground colors
- `--accent`, `--accent-hover` — interactive/brand color
- `--border`, `--border-muted` — border colors
- `--code-bg`, `--code-text` — code block colors
### Spacing
- `--space-1` through `--space-7` — spacing scale
- Maps to Open Props `--size-N` scale
### Typography
- `--weight-normal`, `--weight-medium`, `--weight-semibold`, `--weight-bold`
- `--font-body`, `--font-mono` — font stacks
- `--line-height-body`, `--line-height-heading`
- `--width-prose` — max-width for readable text
### Shadows
- `--shadow-dropdown`, `--shadow-modal` — purpose-named shadows
### Focus / Interaction
- `--focus-ring-width` — keyboard focus ring width
## Scenarios
### Given a new primitive reference needed
- **When** a downstream layer needs an Open Props value
- **Then** add a semantic alias to this file first
- **And** reference only the alias in the downstream layer
### Given an unused token
- **When** auditing finds a token alias with zero references in layers 02+
- **Then** it may be removed from this file
### Given this file
- **When** inspected
- **Then** it contains only `:root {}` with `--custom-property: value;` declarations
- **And** no element selectors, no class selectors, no rules

30
openspec/specs/framework/typography/spec.md Normal file
View file

@ -0,0 +1,30 @@
# Spec: Typography (Layer 02)
File: `src/layers/02-typography.css`
## Purpose
Prose and heading defaults. Responsive typography scale, font stacks, line heights, heading hierarchy, inline elements (code, mark, links, abbreviations).
## Scope
### In scope
- `body` font defaults
- `h1`–`h6` sizing and weight hierarchy
- `p`, `blockquote`, `ul`, `ol`, `li` prose rhythm
- `a` link styling
- `code`, `kbd`, `pre` inline/block code
- `mark`, `abbr`, `small`, `sub`, `sup` inline semantics
- `hr` horizontal rules
- Responsive font-size scaling
### Out of scope
- Syntax highlighting colors (→ chroma layer)
- Navigation typography (→ navigation layer)
- Component-specific text styling (→ components layer)
## Constraints
- References only semantic aliases from `01-tokens.css`
- No Open Props primitives directly
- No element selectors that belong to landmarks (nav, footer, header)

27
openspec/specs/framework/utilities/spec.md Normal file
View file

@ -0,0 +1,27 @@
# Spec: Utilities (Layer 08)
File: `src/layers/08-utilities.css`
## Purpose
Small, single-purpose helpers for text, visibility, and accessibility. The escape hatch for edge cases that don't warrant a data-attribute.
## Scope
### In scope
- Text alignment helpers
- Visually-hidden (screen reader only)
- Visibility toggles
- Print styles
- `prefers-reduced-motion` resets
- `prefers-contrast` adjustments
### Out of scope
- Layout utilities (→ layouts layer)
- Spacing/sizing utilities (use tokens directly)
- Color utilities (use tokens directly)
## Constraints
- This layer should be minimal — most needs should be met by semantic elements + data attributes
- References only semantic aliases from `01-tokens.css`

46
openspec/specs/packs/spec.md Normal file
View file

@ -0,0 +1,46 @@
# Spec: Packs
Directory: `packs/`
## Purpose
Engine integration bundles. Each pack adapts ASW for a specific web server or static site generator. A pack is a self-contained directory that someone can copy into their project.
## Current Packs
| Pack | Purpose | Source |
|------|---------|--------|
| `hugo/` | Hugo theme: layouts, partials, archetypes, static assets | Legacy repo |
| `apache/` | Autoindex styling, error pages, Apache conf snippets | Legacy repo |
| `caddy/` | Browse template, error pages, Caddyfile snippets | Legacy repo |
| `flask/` | Python error handler, Flask integration | Legacy repo |
| `nginx/` | Autoindex header, error pages, Nginx conf snippets | Legacy repo |
| `pandoc/` | HTML5 template, Lua filter for ASW output | Legacy repo |
| `python/` | Simple Python HTTP server with ASW styling | Legacy repo |
## Pack Contract
Each pack directory MUST contain:
- `README.md` — what the pack does, how to install/use it
- All files needed for integration (conf snippets, templates, static assets)
Each pack SHOULD:
- Reference `dist/asw.css` for the framework CSS (not `src/layers/`)
- Be self-contained — no dependencies outside the pack directory and `dist/`
- Include example configuration
## Scenarios
### Given a new engine integration
- **When** someone wants ASW support for a new engine
- **Then** they create `packs/<engine>/` with a README and integration files
- **And** the pack references `dist/asw.css`
### Given the Hugo pack
- **When** the ASW website is built
- **Then** it uses `packs/hugo/` for layouts, partials, and configuration
- **And** `site/` contains Hugo-specific overrides on top of the pack
## Note
The Hugo pack is special: the ASW website (`site/`) is built with it. The pack provides the base; `site/` adds content and any site-specific customization. This is both a real integration and a living example.

96
openspec/specs/repo-structure/spec.md Normal file
View file

@ -0,0 +1,96 @@
# Spec: Repository Structure
The directory layout contract for ASW. Defines what lives where and the boundary rules.
## Directory Map
```
asw/
src/ Framework CSS source
layers/ Numbered CSS layer files (00-reset through 12-landing)
main.css Entry point — @import chain for all layers
lab/ Experiments and test pages (not published)
dist/ Built output (committed to repo)
asw.css Single concatenated file
asw.min.css Minified
vendor/ Explicit external dependencies
open-props/ Open Props CSS (with VERSION file)
README.md What's vendored, why, how to update
packs/ Engine integration bundles
hugo/ Hugo theme/partial integration
apache/ Apache autoindex + error pages
caddy/ Caddy browse + error pages
flask/ Flask error handlers
nginx/ Nginx autoindex + error pages
pandoc/ Pandoc HTML5 template + Lua filter
python/ Python HTTP server with ASW styling
docs/ Framework documentation (markdown only)
examples/ Static HTML showcases (no build step needed)
site/ The ASW website (currently uses Hugo pack)
content/ Site-specific content (articles, essays, notes)
layouts/ Hugo templates
hugo.toml Hugo config (mounts docs/ as content/docs/)
static/ Site static assets
openspec/ Specs and changes
```
## Boundary Rules
### src/ — framework only
- Contains only CSS source files and lab experiments
- No Hugo-specific files, no content, no templates
- `main.css` imports from `layers/` using relative paths
- `lab/` contains HTML files that reference layers directly — never published
### dist/ — build artifacts, committed
- Built by PostCSS from `src/main.css`
- Committed to repo so consumers can grab without a build step
- Regenerated on deploy, not manually edited
### vendor/ — visible dependencies
- Open Props source files copied from npm, with version tracking
- `VERSION` file records package version and date of last update
- Updated manually when bumping Open Props
### packs/ — engine-agnostic integrations
- Each subdirectory is a self-contained integration for one engine
- A pack may reference `dist/asw.css` or `src/layers/` depending on its needs
- Packs ship their own README
### docs/ — markdown only
- No HTML, no engine-specific markup
- The site consumes these as content source (Hugo module mount)
- GitHub/Forgejo renders these directly — no build step to read docs
### examples/ — static HTML
- Each file is a standalone demo that loads ASW
- Can be opened in a browser by cloning the repo — no build step
- The site may link to these but they exist independently
### site/ — website concerns
- All Hugo-specific files live here
- `content/docs/` is mounted from `../docs/`, not duplicated
- Site-specific content (articles, essays, notes) lives in `content/`
- Changes to the site do not affect the framework; changes to the framework may affect the site
## Scenarios
### Given a new CSS layer
- **When** an agent creates it
- **Then** it goes in `src/layers/` with the next number
- **And** `src/main.css` gets an @import line
### Given a new framework doc
- **When** an agent writes documentation
- **Then** it goes in `docs/` as a .md file
- **And** the site picks it up automatically via Hugo mount
### Given a new engine integration
- **When** someone adds support for a new engine (e.g., Eleventy)
- **Then** it goes in `packs/<engine>/` with its own README
### Given a lab experiment
- **When** an agent wants to test a CSS pattern
- **Then** it creates a file in `src/lab/`
- **And** it references layers via relative paths
- **And** it is never published to the site

52
openspec/specs/site/spec.md Normal file
View file

@ -0,0 +1,52 @@
# Spec: Site
Directory: `site/`
## Purpose
The ASW framework's own website. Serves as documentation site, demo platform, and living proof that the framework works. Currently built with the Hugo pack.
## Content Types
### Docs (from `../docs/`)
Framework documentation, mounted as Hugo content via module mount. Not duplicated — sourced from the engine-agnostic `docs/` directory.
### Articles (`content/articles/`)
Short-form writing about ASW concepts, patterns, and techniques. No TOC.
### Essays (`content/essays/`)
Long-form writing. TOC, description, wider reading measure.
### Notes (`content/notes/`)
Exported PKM vault notes. Session logs, diffs, status, tasks, wikilinks.
### Pages (`content/pages/`)
Static pages: about, etc.
## Engine
Currently Hugo. The site uses `packs/hugo/` as its base and adds:
- Site-specific layouts and overrides
- `hugo.toml` with module mounts
- Site-specific static assets
## Principle
The site is a consumer of the framework, not part of it. A different site could be built with `packs/flask/` or `packs/caddy/` using the same `docs/` and `dist/asw.css`. The framework does not depend on the site. The site depends on the framework.
## Scenarios
### Given a framework docs change
- **When** a markdown file in `docs/` is modified
- **Then** the site picks it up automatically via Hugo mount
- **And** no file in `site/` needs to change
### Given a CSS framework change
- **When** `src/layers/` is modified
- **Then** `dist/asw.css` is rebuilt
- **And** the site serves the updated CSS
### Given a site-only change (new article, essay)
- **When** content is added to `site/content/`
- **Then** only the site is affected
- **And** `src/`, `dist/`, `docs/` are untouched