# 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.