asw/openspec/changes/repo-restructure/proposal.md

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/