asw/openspec/specs/repo-structure/spec.md

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