asw/docs/css-refactor-plan.md

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 {}:

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

# 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