Ludo
5bf233348d
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>
42 lines
2 KiB
Markdown
42 lines
2 KiB
Markdown
# 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/`
|