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
60
openspec/changes/css-refactor/proposal.md
Normal file
60
openspec/changes/css-refactor/proposal.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
# Proposal: CSS Layer Refactor
|
||||
|
||||
## Intent
|
||||
|
||||
Restructure CSS layers to clean architecture: alias all Open Props primitives through `01-tokens.css`, split the monolithic `03-components.css` into purpose-specific files, redistribute misplaced content, and rename files to match their actual responsibilities.
|
||||
|
||||
**Goal: each CSS file has a single clear purpose, and no file references Open Props primitives directly.**
|
||||
|
||||
This plan was originally documented in `docs/css-refactor-plan.md` and is imported here as an OpenSpec change for tracking and execution.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
- Add missing semantic aliases to token file (~10 new aliases)
|
||||
- Extract editorial rules out of token file into their proper layers
|
||||
- Rename `01-asw.css` → `01-tokens.css` (pure tokens, no rules)
|
||||
- Fix all Open Props primitive leaks across all layers
|
||||
- Split `03-components.css` into: `03-landmarks.css`, `04-forms.css`, slimmed `05-components.css`, `06-navigation.css`
|
||||
- Rename all files to final numbering scheme
|
||||
- Merge `08a-essay.css` into layout layer
|
||||
- Audit and remove unused tokens
|
||||
|
||||
### Out of Scope
|
||||
- New CSS features or components
|
||||
- Layout changes
|
||||
- Content changes
|
||||
- Repo restructure (separate change, happens first)
|
||||
|
||||
### Current → Target Layer Map
|
||||
|
||||
```
|
||||
CURRENT TARGET
|
||||
═══════ ══════
|
||||
00-reset.css 00-reset.css (unchanged)
|
||||
01-asw.css ──▶ 01-tokens.css (pure :root, no rules)
|
||||
02-semantic.css ──▶ 02-typography.css
|
||||
03-components.css ──▶ 03-landmarks.css (nav, article, footer, hgroup)
|
||||
──▶ 04-forms.css (inputs, buttons, selects)
|
||||
──▶ 05-components.css (dialog, accordion, breadcrumb)
|
||||
──▶ 06-navigation.css (sidebar, TOC)
|
||||
04-data-attrs.css ──▶ 07-data-attrs.css
|
||||
05-utilities.css ──▶ 08-utilities.css
|
||||
06-charts.css ──▶ 09-charts.css
|
||||
07-chroma.css ──▶ 10-chroma.css
|
||||
08-layout.css + 08a-essay ──▶ 11-layout.css (merged)
|
||||
09-landing.css ──▶ 12-landing.css
|
||||
```
|
||||
|
||||
## Approach
|
||||
|
||||
One atomic step per session. Build check after every step. No step touches more than two files. Full plan in `docs/css-refactor-plan.md`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Depends on:** `repo-restructure` (files must be in `src/layers/` first)
|
||||
|
||||
## Risks
|
||||
|
||||
- **Visual regression** — mitigated by build + visual check after each step
|
||||
- **Specificity changes** — layer reordering could affect cascade. Mitigated by keeping relative order.
|
||||
94
openspec/changes/css-refactor/tasks.md
Normal file
94
openspec/changes/css-refactor/tasks.md
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
# Tasks: CSS Layer Refactor
|
||||
|
||||
Imported from `docs/css-refactor-plan.md`. Each step = one agent session.
|
||||
|
||||
**Prerequisite:** `repo-restructure` change must be complete. All files in `src/layers/`.
|
||||
|
||||
---
|
||||
|
||||
## Task 1 — Add missing aliases to token file
|
||||
**Files:** `src/layers/01-asw.css` (pre-rename)
|
||||
**Action:** Add semantic aliases for `--font-weight-N`, `--shadow-N`, `--border-size-2`, `--size-px-12`, and `--space-5a` gap.
|
||||
**Acceptance:** Build passes. No visual change. New aliases exist in `:root`.
|
||||
|
||||
---
|
||||
|
||||
## Task 2 — Extract editorial rules from token file
|
||||
**Files:** `src/layers/01-asw.css`, `src/layers/08-layout.css`
|
||||
**Action:** Move `body > nav` padding rule to `03-components.css`. Move `[data-layout="docs"] > article` max-width to `08-layout.css`. Token file becomes pure `:root` only.
|
||||
**Acceptance:** Build passes. Nav centering and docs prose width unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Task 3 — Rename `01-asw.css` → `01-tokens.css`
|
||||
**Files:** `src/layers/01-asw.css`, `src/main.css`
|
||||
**Action:** Rename file, update `@import`.
|
||||
**Acceptance:** Build passes.
|
||||
|
||||
---
|
||||
|
||||
## Task 4 — Fix primitive leaks in `03-components.css`
|
||||
**Files:** `src/layers/03-components.css`
|
||||
**Action:** Replace all `--font-weight-N`, `--size-N`, `--shadow-N`, `--border-size-N` with semantic aliases.
|
||||
**Acceptance:** Build passes. No visual change.
|
||||
|
||||
---
|
||||
|
||||
## Task 5 — Fix primitive leaks in `06-charts.css`
|
||||
**Files:** `src/layers/06-charts.css`
|
||||
**Action:** Replace `--size-1/2/3` with `--space-1/2/4`.
|
||||
**Acceptance:** Build passes. Charts render unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Task 6 — Fix primitive leaks in remaining files
|
||||
**Files:** `src/layers/02-semantic.css`, `src/layers/07-chroma.css`, `src/layers/08-layout.css`, `src/layers/09-landing.css`
|
||||
**Action:** Replace all remaining `--font-weight-N`, `--size-N` primitives with semantic aliases.
|
||||
**Acceptance:** Build passes after each file.
|
||||
|
||||
---
|
||||
|
||||
## Task 7 — Create `03-landmarks.css`, extract from `03-components.css`
|
||||
**Files:** `src/layers/03-components.css`, new `src/layers/03-landmarks.css`, `src/main.css`
|
||||
**Action:** Move landmark sections (nav, article, dt/dd, section, hgroup, footer) to new file.
|
||||
**Acceptance:** Build passes. All landmark styles render unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Task 8 — Create `04-forms.css`, extract from `03-components.css`
|
||||
**Files:** `src/layers/03-components.css`, new `src/layers/04-forms.css`, `src/main.css`
|
||||
**Action:** Move buttons and form elements to new file.
|
||||
**Acceptance:** Build passes.
|
||||
|
||||
---
|
||||
|
||||
## Task 9 — Create `06-navigation.css`, extract from `03-components.css`
|
||||
**Files:** `src/layers/03-components.css`, new `src/layers/06-navigation.css`, `src/main.css`
|
||||
**Action:** Move sidebar nav and TOC sections to new file.
|
||||
**Acceptance:** Build passes. Sidebar and TOC render unchanged.
|
||||
|
||||
---
|
||||
|
||||
## Task 10 — Rename files to final numbering + merge essay
|
||||
**Files:** All layer files, `src/main.css`
|
||||
**Action:** Rename to final numbers (see proposal layer map). Merge `08a-essay.css` into `11-layout.css`. Update all `@import` statements.
|
||||
**Acceptance:** Build passes.
|
||||
|
||||
---
|
||||
|
||||
## Task 11 — Audit unused tokens
|
||||
**Files:** `src/layers/01-tokens.css`
|
||||
**Action:** Build CSS, grep for token usage, diff defined vs used. Remove confirmed unused.
|
||||
**Acceptance:** Build passes. Spot-check 3-4 pages visually.
|
||||
|
||||
---
|
||||
|
||||
## Task 12 — Fix HTML template issues from sidebar/TOC refactor
|
||||
**Files:** `site/layouts/docs/single.html`, `site/layouts/notes/single.html` (post-restructure paths)
|
||||
**Action:** From `docs/css-html-cleanup-todo.md`:
|
||||
- Remove redundant `nav[data-nav="sidebar"] ul li { margin: 0; padding: 0 }` resets (if not already caught in Tasks 7/9)
|
||||
- Remove redundant `aside[data-toc] nav ul li { margin: 0; padding: 0 }` resets (if not already caught in Tasks 7/9)
|
||||
- Replace `<small>← Previous</small>` / `<small>Next →</small>` with appropriate element in prev/next footer
|
||||
- Remove `role="main"` from `<article>` in docs single layout
|
||||
- Move hardcoded `"On this page"` string to Hugo i18n or site param
|
||||
**Acceptance:** Build passes. Prev/next links render correctly. TOC heading uses i18n string. No `role="main"` on `<article>`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue