feat: add OpenSpec specs and changes for ASW restructure

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>
2026-04-11 14:58:39 +02:00 · 2026-04-11 14:58:39 +02:00 · 5bf233348d
commit 5bf233348d
parent ecfbed0374
21 changed files with 1110 additions and 0 deletions
--- a/openspec/specs/repo-structure/spec.md
+++ b/openspec/specs/repo-structure/spec.md
@ -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