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>
96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
# 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
|