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>
This commit is contained in:
parent
ecfbed0374
commit
5bf233348d
GPG key ID:
F6E479DEFAB84D6E
21 changed files with 1110 additions and 0 deletions
115
openspec/changes/repo-restructure/design.md
Normal file
115
openspec/changes/repo-restructure/design.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
# Design: Repository Restructure
|
||||
|
||||
## Current → Target Mapping
|
||||
|
||||
```
|
||||
CURRENT TARGET
|
||||
═══════ ══════
|
||||
assets/css/layers/*.css ──▶ src/layers/*.css
|
||||
assets/css/main.css ──▶ src/main.css
|
||||
(new) ──▶ src/lab/
|
||||
static/asw.css ──▶ dist/asw.css
|
||||
(new) ──▶ dist/asw.min.css
|
||||
static/vendor/ ──▶ vendor/open-props/
|
||||
(new) ──▶ vendor/open-props/VERSION
|
||||
(new) ──▶ vendor/README.md
|
||||
content/ ──▶ site/content/
|
||||
layouts/ ──▶ site/layouts/
|
||||
archetypes/ ──▶ site/archetypes/
|
||||
hugo.toml ──▶ site/hugo.toml
|
||||
static/ (non-vendor) ──▶ site/static/
|
||||
docs/ ──▶ docs/ (stays, add new docs)
|
||||
(new) ──▶ examples/
|
||||
postcss.config.js ──▶ postcss.config.js (updated paths)
|
||||
package.json ──▶ package.json (stays at root)
|
||||
node_modules/ ──▶ node_modules/ (stays at root)
|
||||
```
|
||||
|
||||
## Key Design Decisions
|
||||
|
||||
### Hugo assets resolution
|
||||
|
||||
Hugo looks for `assets/` relative to the site root. With Hugo files in `site/`, we need either:
|
||||
- **Option A:** `site/assets/css/main.css` that imports from `../../src/layers/` — fragile
|
||||
- **Option B:** Hugo module mount maps `src/` into Hugo's asset pipeline — clean
|
||||
|
||||
**Decision: Option B.** Hugo config in `site/hugo.toml`:
|
||||
```toml
|
||||
[[module.mounts]]
|
||||
source = "static"
|
||||
target = "static"
|
||||
|
||||
[[module.mounts]]
|
||||
source = "../src"
|
||||
target = "assets/css"
|
||||
|
||||
[[module.mounts]]
|
||||
source = "../docs"
|
||||
target = "content/docs"
|
||||
|
||||
[[module.mounts]]
|
||||
source = "../vendor/open-props"
|
||||
target = "assets/css/open-props"
|
||||
```
|
||||
|
||||
This way Hugo sees `src/layers/` as `assets/css/layers/` and `src/main.css` as `assets/css/main.css` — zero path changes in the CSS files themselves.
|
||||
|
||||
### Vendor directory
|
||||
|
||||
```
|
||||
vendor/
|
||||
open-props/
|
||||
open-props.min.css
|
||||
media.min.css
|
||||
VERSION ← "1.7.x (npm open-props@1.7.x, vendored 2025-xx-xx)"
|
||||
README.md ← "How to update: npm update open-props && cp ..."
|
||||
```
|
||||
|
||||
`npm install` still works for the build toolchain. `vendor/` is the inspectable, committed copy with version tracking. The build reads from `node_modules/` (PostCSS import resolution), but agents and humans can read `vendor/` to understand what Open Props provides.
|
||||
|
||||
### dist/ generation
|
||||
|
||||
`dist/asw.css` is built by PostCSS from `src/main.css`:
|
||||
```bash
|
||||
npx postcss src/main.css -o dist/asw.css
|
||||
npx postcss src/main.css -o dist/asw.min.css # with cssnano
|
||||
```
|
||||
|
||||
Committed to repo. Consumers grab `dist/asw.css` without needing npm/PostCSS.
|
||||
|
||||
### examples/ structure
|
||||
|
||||
```
|
||||
examples/
|
||||
components/ ← buttons, forms, callouts, dialogs
|
||||
layout/ ← docs layout, grid, prose, timeline
|
||||
charts/ ← chart showcases
|
||||
vault/ ← vault note rendering examples
|
||||
```
|
||||
|
||||
Each HTML file is standalone: `<link rel="stylesheet" href="../dist/asw.css">`. Open in browser, no build step.
|
||||
|
||||
### dev workflow
|
||||
|
||||
`dev.sh` (or its successor) runs from project root:
|
||||
1. Watches `src/layers/` for changes
|
||||
2. Processes individual layers → somewhere Hugo can serve them (for devtools visibility)
|
||||
3. Runs `hugo server` with working directory `site/`
|
||||
|
||||
The key change: Hugo is invoked as `hugo server --source site/` or from within `site/`.
|
||||
|
||||
## What Stays at Root
|
||||
|
||||
```
|
||||
asw/
|
||||
package.json ← build tooling (PostCSS, Open Props)
|
||||
postcss.config.js ← production PostCSS config
|
||||
postcss.dev.config.js ← dev PostCSS config
|
||||
node_modules/ ← npm packages (gitignored)
|
||||
.gitignore
|
||||
README.md
|
||||
LICENSE
|
||||
openspec/
|
||||
```
|
||||
|
||||
Build tooling stays at root because it serves both `dist/` (framework build) and `site/` (dev server). It's a project-level concern, not framework or site.
|
||||
42
openspec/changes/repo-restructure/proposal.md
Normal file
42
openspec/changes/repo-restructure/proposal.md
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
# 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/`
|
||||
115
openspec/changes/repo-restructure/tasks.md
Normal file
115
openspec/changes/repo-restructure/tasks.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
# Tasks: Repository Restructure
|
||||
|
||||
## Task 1 — Create directory skeleton
|
||||
**Files:** (new directories only)
|
||||
**Action:**
|
||||
- Create `src/`, `src/layers/`, `src/lab/`
|
||||
- Create `dist/`
|
||||
- Create `vendor/open-props/`
|
||||
- Create `site/`
|
||||
- Create `examples/`
|
||||
**Acceptance:** Directories exist. No files moved yet. Build still passes from current layout.
|
||||
|
||||
---
|
||||
|
||||
## Task 2 — Move CSS source to src/
|
||||
**Files:** `assets/css/layers/*.css` → `src/layers/`, `assets/css/main.css` → `src/main.css`
|
||||
**Action:**
|
||||
- `git mv assets/css/layers/ src/layers/`
|
||||
- `git mv assets/css/main.css src/main.css`
|
||||
- Update `@import` paths in `src/main.css` if needed (should be relative, likely unchanged)
|
||||
**Acceptance:** `src/layers/` contains all 11 CSS files. `src/main.css` imports them. `assets/css/` is gone.
|
||||
**Note:** Site will be temporarily broken until Hugo mounts are configured (Task 5).
|
||||
|
||||
---
|
||||
|
||||
## Task 3 — Set up vendor/
|
||||
**Files:** `vendor/open-props/`, `vendor/README.md`
|
||||
**Action:**
|
||||
- Copy `node_modules/open-props/open-props.min.css` → `vendor/open-props/`
|
||||
- Copy `node_modules/open-props/media.min.css` → `vendor/open-props/`
|
||||
- Create `vendor/open-props/VERSION` with package version and date
|
||||
- Create `vendor/README.md` explaining what's vendored and how to update
|
||||
- Remove `static/vendor/` (old location)
|
||||
**Acceptance:** `vendor/open-props/` contains the two CSS files + VERSION. `static/vendor/` is gone.
|
||||
|
||||
---
|
||||
|
||||
## Task 4 — Move Hugo files to site/
|
||||
**Files:** `content/`, `layouts/`, `archetypes/`, `hugo.toml`, `hugo_stats.json`
|
||||
**Action:**
|
||||
- `git mv content/ site/content/`
|
||||
- `git mv layouts/ site/layouts/`
|
||||
- `git mv archetypes/ site/archetypes/`
|
||||
- `git mv hugo.toml site/hugo.toml`
|
||||
- `git mv hugo_stats.json site/hugo_stats.json`
|
||||
- Move site-specific static files: `static/palette-test.html` → `site/static/`
|
||||
- Move `static/asw.css` → `dist/asw.css` (this is the built output)
|
||||
**Acceptance:** All Hugo content/layout/config files are in `site/`. Root has no Hugo files.
|
||||
|
||||
---
|
||||
|
||||
## Task 5 — Configure Hugo module mounts
|
||||
**Files:** `site/hugo.toml`
|
||||
**Action:** Add module mounts:
|
||||
- `../src` → `assets/css` (framework CSS in Hugo's asset pipeline)
|
||||
- `../docs` → `content/docs` (framework docs as site content)
|
||||
- `../vendor/open-props` → `assets/css/open-props` (Open Props in asset pipeline)
|
||||
- `static` → `static` (site's own static files)
|
||||
**Acceptance:** `hugo server --source site/` builds successfully. All pages render. CSS loads correctly.
|
||||
|
||||
---
|
||||
|
||||
## Task 6 — Build dist/asw.css from new paths
|
||||
**Files:** `postcss.config.js`, `package.json`
|
||||
**Action:**
|
||||
- Update PostCSS config if paths changed
|
||||
- Run: `npx postcss src/main.css -o dist/asw.css`
|
||||
- Run: `npx postcss src/main.css -o dist/asw.min.css`
|
||||
- Verify output matches previous `static/asw.css`
|
||||
- Add npm scripts to `package.json`: `"build": "postcss src/main.css -o dist/asw.css"`
|
||||
**Acceptance:** `dist/asw.css` exists and is equivalent to the previous build. `npm run build` works.
|
||||
|
||||
---
|
||||
|
||||
## Task 7 — Restructure docs/
|
||||
**Files:** `docs/`
|
||||
**Action:**
|
||||
- Existing docs stay: `context.md`, `css-refactor-plan.md`, `css-html-cleanup-todo.md`, `frontmatter.md`, `template-h1-title.md`
|
||||
- Verify Hugo mount serves them at `content/docs/`
|
||||
- Add `docs/llms.txt` (move from legacy or create)
|
||||
- Add `docs/lineage.md` placeholder (Pico absorption story, Open Props relationship)
|
||||
**Acceptance:** Framework docs are all in `docs/`. Hugo renders them as site pages via mount.
|
||||
|
||||
---
|
||||
|
||||
## Task 8 — Create examples/ from site content
|
||||
**Files:** `examples/`
|
||||
**Action:**
|
||||
- Identify existing pages that are pure component/layout demos
|
||||
- Create standalone HTML versions in `examples/` that load `dist/asw.css`
|
||||
- Organize into `examples/components/`, `examples/layout/`, `examples/charts/`, `examples/vault/`
|
||||
**Acceptance:** At least 3 example files exist, each standalone and openable in a browser.
|
||||
|
||||
---
|
||||
|
||||
## Task 9 — Update .gitignore and clean up
|
||||
**Files:** `.gitignore`, root directory
|
||||
**Action:**
|
||||
- Update `.gitignore` for new paths
|
||||
- Remove empty `assets/` directory if still present
|
||||
- Remove `static/css/layers/` (dev-mode output, will be regenerated)
|
||||
- Verify no orphaned files remain in old locations
|
||||
**Acceptance:** `git status` is clean. No files in old locations. `.gitignore` covers `node_modules/`, `site/public/`, `site/resources/`.
|
||||
|
||||
---
|
||||
|
||||
## Task 10 — Verify full build cycle
|
||||
**Files:** (none modified, verification only)
|
||||
**Action:**
|
||||
- `npm run build` → `dist/asw.css` generated
|
||||
- `hugo --source site/` → `site/public/` generated
|
||||
- Spot-check 3-4 pages visually
|
||||
- Verify `docs/` content appears in site
|
||||
- Verify CSS loads and renders correctly
|
||||
**Acceptance:** Full build passes. Site looks identical to pre-restructure. dist/ output is valid.
|
||||
Loading…
Add table
Add a link
Reference in a new issue