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>
223 lines
8.6 KiB
Markdown
223 lines
8.6 KiB
Markdown
# CSS Layer Refactor Plan
|
||
|
||
> **Superseded by:** `openspec/changes/css-refactor/` — this document is kept as historical reference. Agents should read the OpenSpec change tasks, not this file.
|
||
|
||
**Project:** ASW — Agentic Semantic Web
|
||
**Goal:** Restructure CSS layers to clean architecture, alias all Open Props primitives through `01-tokens.css`, redistribute misplaced content, remove unused values.
|
||
**Method:** One atomic step per agent session. Build check after every step. No step touches more than two files.
|
||
|
||
---
|
||
|
||
## Current state
|
||
|
||
```
|
||
assets/css/
|
||
main.css ← entry point, @import chain
|
||
layers/
|
||
00-reset.css
|
||
01-asw.css ← tokens + editorial rules (mixed)
|
||
02-semantic.css ← typography + prose styles
|
||
03-components.css ← landmarks + forms + components (mixed)
|
||
04-data-attrs.css ← data-* attribute patterns
|
||
05-utilities.css ← utility helpers
|
||
06-charts.css ← charts (uses --size-N primitives directly)
|
||
07-chroma.css ← syntax highlighting
|
||
08-layout.css ← layout systems
|
||
08a-essay.css ← paper layout variant
|
||
09-landing.css ← landing page styles
|
||
```
|
||
|
||
## Target state
|
||
|
||
```
|
||
assets/css/
|
||
main.css ← updated import chain
|
||
layers/
|
||
00-reset.css (unchanged)
|
||
01-tokens.css ← renamed from 01-asw.css, pure :root only, no rules
|
||
02-typography.css ← renamed from 02-semantic.css, prose + heading defaults
|
||
03-landmarks.css ← NEW: nav, article, aside, section, footer, hgroup
|
||
04-forms.css ← NEW: input, select, textarea, button
|
||
05-components.css ← slimmed 03-components.css: dialog, accordion, breadcrumb, steps
|
||
06-navigation.css ← NEW: sidebar nav, TOC (aside[data-toc])
|
||
07-data-attrs.css ← renamed from 04-data-attrs.css
|
||
08-utilities.css ← renamed from 05-utilities.css
|
||
09-charts.css ← renamed from 06-charts.css, primitives fixed
|
||
10-chroma.css ← renamed from 07-chroma.css
|
||
11-layout.css ← renamed from 08-layout.css + 08a-essay.css merged
|
||
12-landing.css ← renamed from 09-landing.css
|
||
```
|
||
|
||
---
|
||
|
||
## Primitive leak inventory
|
||
|
||
All Open Props primitives used directly in layers (must be aliased through 01-tokens.css):
|
||
|
||
### `--font-weight-N` (most common leak)
|
||
| Primitive | Semantic alias to add | Used in |
|
||
|---|---|---|
|
||
| `--font-weight-4` | `--weight-normal` | 03, 02, 08 |
|
||
| `--font-weight-5` | `--weight-medium` | 03, 02, 08 |
|
||
| `--font-weight-6` | `--weight-semibold` | 03 |
|
||
| `--font-weight-7` | `--weight-bold` | 02, 08, 09 |
|
||
|
||
### `--size-N` / `--size-px-N`
|
||
| Primitive | Alias | Notes |
|
||
|---|---|---|
|
||
| `--size-1` | `--space-1` (exists) | 06-charts |
|
||
| `--size-2` | `--space-2` (exists) | 06-charts |
|
||
| `--size-3` | `--space-4` (exists) | 03, 06-charts, 07-chroma |
|
||
| `--size-4` | needs `--space-5a: 1.25rem` | 03-components article padding |
|
||
| `--size-px-12` | `--dropdown-min-width` | 03-components nav dropdown |
|
||
|
||
### `--shadow-N`
|
||
| Primitive | Alias to add |
|
||
|---|---|
|
||
| `--shadow-2` | `--shadow-dropdown` |
|
||
| `--shadow-4` | `--shadow-modal` |
|
||
|
||
### `--border-size-2`
|
||
| Primitive | Alias to add |
|
||
|---|---|
|
||
| `--border-size-2` | `--focus-ring-width` |
|
||
|
||
---
|
||
|
||
## Step-by-step tasks
|
||
|
||
Each step = one agent session. Read only the files listed. Build after every step.
|
||
|
||
### STEP 1 — Add missing aliases to `01-asw.css` ✅ prerequisites: none
|
||
**Files:** `layers/01-asw.css` only
|
||
**Action:** Add to `:root {}`:
|
||
```css
|
||
/* Font weights */
|
||
--weight-normal: var(--font-weight-4);
|
||
--weight-medium: var(--font-weight-5);
|
||
--weight-semibold: var(--font-weight-6);
|
||
--weight-bold: var(--font-weight-7);
|
||
|
||
/* Shadows */
|
||
--shadow-dropdown: var(--shadow-2);
|
||
--shadow-modal: var(--shadow-4);
|
||
|
||
/* Focus ring */
|
||
--focus-ring-width: var(--border-size-2);
|
||
|
||
/* Dropdown */
|
||
--dropdown-min-width: var(--size-px-12);
|
||
|
||
/* Gap in spacing scale */
|
||
--space-5a: 1.25rem; /* between --space-4 (1rem) and --space-5 (1.5rem) */
|
||
```
|
||
**Verify:** `hugo server` builds without error. No visual change.
|
||
|
||
---
|
||
|
||
### STEP 2 — Extract editorial rules out of `01-asw.css` ✅ prerequisites: Step 1
|
||
**Files:** `layers/01-asw.css`, `layers/08-layout.css`
|
||
**Action:**
|
||
- Remove from `01-asw.css` the EDITORIAL DEFAULTS section (last ~10 lines: `body > nav` padding rule + `[data-layout="docs"] > article` max-width rule)
|
||
- Move `body > nav { padding-inline: ... }` to `03-components.css` under the Navigation section
|
||
- Move `[data-layout="docs"] > article { max-width: var(--width-prose) }` to `08-layout.css` under the docs layout section
|
||
**Verify:** Build passes. Nav centering and docs prose width unchanged visually.
|
||
|
||
---
|
||
|
||
### STEP 3 — Rename `01-asw.css` → `01-tokens.css` ✅ prerequisites: Step 2
|
||
**Files:** `layers/01-asw.css`, `main.css`
|
||
**Action:** Rename file, update `@import` in `main.css`.
|
||
**Verify:** Build passes.
|
||
|
||
---
|
||
|
||
### STEP 4 — Fix primitive leaks in `03-components.css` ✅ prerequisites: Step 1
|
||
**Files:** `layers/03-components.css` only
|
||
**Action:** Replace all primitive references with aliases:
|
||
- `var(--font-weight-4)` → `var(--weight-normal)`
|
||
- `var(--font-weight-5)` → `var(--weight-medium)` (including the fallback `, 500` variant)
|
||
- `var(--font-weight-6)` → `var(--weight-semibold)`
|
||
- `var(--size-3) var(--size-4)` → `var(--space-4) var(--space-5a)` (article padding, line 455)
|
||
- `var(--size-px-12)` → `var(--dropdown-min-width)`
|
||
- `var(--shadow-2)` → `var(--shadow-dropdown)`
|
||
- `var(--shadow-4)` → `var(--shadow-modal)`
|
||
- `var(--border-size-2)` → `var(--focus-ring-width)` (both occurrences)
|
||
**Verify:** Build passes. No visual change.
|
||
|
||
---
|
||
|
||
### STEP 5 — Fix primitive leaks in `06-charts.css` ✅ prerequisites: Step 1
|
||
**Files:** `layers/06-charts.css` only
|
||
**Action:** Replace all `--size-1/2/3` with `--space-1/2/4` respectively.
|
||
**Verify:** Build passes. Charts render unchanged.
|
||
|
||
---
|
||
|
||
### STEP 6 — Fix primitive leaks in remaining files ✅ prerequisites: Step 1
|
||
**Files:** `layers/02-semantic.css`, `layers/07-chroma.css`, `layers/08-layout.css`, `layers/09-landing.css` — one at a time
|
||
**Action:** Same find-replace for `--font-weight-N`, `--size-N` primitives.
|
||
**Verify:** Build passes after each file.
|
||
|
||
---
|
||
|
||
### STEP 7 — Create `03-landmarks.css` and extract from `03-components.css` ✅ prerequisites: Step 4
|
||
**Files:** `layers/03-components.css`, new `layers/03-landmarks.css`, `main.css`
|
||
**Action:** Move these sections out of `03-components.css` into `03-landmarks.css`:
|
||
- `body > nav` (the global nav landmark, lines ~259–442)
|
||
- `article` (lines ~444–506)
|
||
- `dt`, `dd` (lines ~508–529)
|
||
- `section + section`, `hgroup` (lines ~531–559)
|
||
- `body > footer` (lines ~561–572)
|
||
Add `@import "./layers/03-landmarks.css"` to `main.css` before `03-components.css`.
|
||
**Verify:** Build passes. All landmark styles render unchanged.
|
||
|
||
---
|
||
|
||
### STEP 8 — Create `04-forms.css` and extract from `03-components.css` ✅ prerequisites: Step 7
|
||
**Files:** `layers/03-components.css`, new `layers/04-forms.css`, `main.css`
|
||
**Action:** Move out of `03-components.css`:
|
||
- Buttons (lines ~14–75)
|
||
- Form Elements (lines ~77–258)
|
||
**Verify:** Build passes.
|
||
|
||
---
|
||
|
||
### STEP 9 — Create `06-navigation.css` and extract from `03-components.css` ✅ prerequisites: Step 8
|
||
**Files:** `layers/03-components.css`, new `layers/06-navigation.css`, `main.css`
|
||
**Action:** Move out of `03-components.css`:
|
||
- `nav[data-nav="sidebar"]` section
|
||
- `aside[data-toc]` section
|
||
**Verify:** Build passes. Sidebar and TOC render unchanged.
|
||
|
||
---
|
||
|
||
### STEP 10 — Rename remaining files + update `main.css` ✅ prerequisites: Steps 7–9
|
||
**Files:** all layer files + `main.css`
|
||
**Action:** Rename files to final numbers, merge `08a-essay.css` into `11-layout.css`, update all `@import` statements.
|
||
**Verify:** Build passes.
|
||
|
||
---
|
||
|
||
### STEP 11 — Audit unused tokens ✅ prerequisites: Step 10
|
||
**Method:** Tooling only — do not guess.
|
||
```bash
|
||
# Build the CSS, then grep for each token name
|
||
hugo --minify
|
||
grep -o 'var(--[^)]+)' public/**/*.css | sort | uniq > /tmp/used-tokens.txt
|
||
grep -o '\-\-[a-z][^:]*:' assets/css/layers/01-tokens.css | sort > /tmp/defined-tokens.txt
|
||
diff /tmp/defined-tokens.txt /tmp/used-tokens.txt
|
||
```
|
||
Review diff. Remove confirmed unused tokens from `01-tokens.css`.
|
||
**Verify:** Build passes. Spot-check 3–4 pages visually.
|
||
|
||
---
|
||
|
||
## Rules for all agents
|
||
|
||
1. Read only the files listed for your step — nothing else
|
||
2. Run build after every step before reporting done
|
||
3. Do not rename variables not listed in this plan
|
||
4. Do not touch `main.css` unless the step explicitly says to
|
||
5. Do not combine two steps in one session
|
||
6. If a primitive is found that isn't in the inventory above, add it to the plan doc and stop — do not fix it unilaterally
|