refactor: rename content types to semantic taxonomy
- vault → notes (PKM-exported content) - posts → articles (short-form, no TOC) - papers → essays (long-form, with TOC) - type: post → type: article (posts are just short articles) - layouts/paper → layouts/essay - 08a-paper.css → 08a-essay.css - CSS: fix redundant li resets, remove role="main" from article, replace <small> prev/next labels, add console layout - Update hugo.toml menus, internal URLs, front matter throughout - Add docs/context.md, docs/css-refactor-plan.md
This commit is contained in:
parent
1408a52e8b
commit
15a6db9c0e
GPG key ID:
F6E479DEFAB84D6E
31 changed files with 788 additions and 70 deletions
221
docs/css-refactor-plan.md
Normal file
221
docs/css-refactor-plan.md
Normal file
|
|
@ -0,0 +1,221 @@
|
|||
# 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue