# CSS Layer Refactor Plan

**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