feat: add OpenSpec specs and changes for ASW restructure

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>

openspec/specs/framework/charts/spec.md

@@ -0,0 +1,32 @@
+# Spec: Charts (Layer 09)
+
+File: `src/layers/09-charts.css`
+
+## Purpose
+
+Data visualization using pure CSS and HTML tables. Inspired by Charts.css — uses `data-*` attributes to transform tables into visual charts.
+
+## Scope
+
+### In scope
+- Bar charts (horizontal and vertical)
+- Line charts
+- Area charts
+- Radial/gauge charts
+- Chart axes, labels, legends
+- Responsive chart sizing
+- Chart color schemes using design tokens
+
+### Out of scope
+- JavaScript-powered charts
+- Interactive chart features (tooltips on hover are CSS-only)
+
+## Lineage
+
+Inspired by Charts.css `data-*` attribute pattern. Not a port — reimplemented for ASW's token system and semantic approach.
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- Charts must be readable without CSS (the underlying table has the data)
+- Color choices must work for colorblind users

openspec/specs/framework/components/spec.md

@@ -0,0 +1,26 @@
+# Spec: Components (Layer 05)
+
+File: `src/layers/05-components.css`
+
+## Purpose
+
+Compound UI patterns that go beyond single-element semantics. These are patterns that require specific HTML structures.
+
+## Scope
+
+### In scope
+- `dialog` — modal dialogs
+- `details` / `summary` — accordion pattern
+- Breadcrumb navigation (`[data-role="breadcrumb"]`)
+- Step indicators (`[data-role="steps"]`)
+
+### Out of scope
+- Single HTML elements with default styling (→ landmarks, typography, forms)
+- Sidebar navigation (→ navigation layer)
+- Charts (→ charts layer)
+- Data-attribute vocabulary (→ data-attributes layer)
+
+## Constraints
+
+- This layer should be small — if a pattern can be expressed by a semantic HTML element alone, it belongs in landmarks or typography, not here
+- References only semantic aliases from `01-tokens.css`

openspec/specs/framework/data-attributes/spec.md

@@ -0,0 +1,42 @@
+# Spec: Data Attributes (Layer 07)
+
+File: `src/layers/07-data-attrs.css`
+
+## Purpose
+
+The ASW vocabulary extension layer. `data-*` attributes express concepts that HTML has no native element for. This is the core differentiator — the semantic vocabulary agents use.
+
+## Vocabulary
+
+### Task states
+- `data-task="done|todo|blocked|wip"` — task status indicators
+
+### Callouts
+- `data-callout="note|tip|warning|error"` — admonition blocks
+
+### Status
+- `data-status="active|sleeping|blocked"` — entity status
+
+### Links
+- `data-wikilink` — vault/wiki-style note links
+
+### Layout
+- `data-layout="docs|grid-2|grid-3|console"` — page layout selection
+
+### Table of contents
+- `data-toc` — marks an element as an in-page TOC
+
+### Roles
+- `data-role="breadcrumb|steps|accordion|card"` — component role disambiguation
+
+## Design Principle
+
+Every `data-*` attribute added to the vocabulary is cognitive load on every agent using the framework. Add only what cannot be expressed by existing semantic HTML.
+
+**The bar for addition:** "Can this be expressed with an existing HTML element?" If yes, don't add a data attribute.
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- Each attribute must have a clear semantic meaning (not stylistic)
+- Attribute values should be exhaustive and documented

openspec/specs/framework/forms/spec.md

@@ -0,0 +1,30 @@
+# Spec: Forms (Layer 04)
+
+File: `src/layers/04-forms.css`
+
+## Purpose
+
+Form element styling. Inputs, selects, textareas, buttons, checkboxes, radios, fieldsets, labels. Accessible by default.
+
+## Scope
+
+### In scope
+- `button`, `input[type="button"]`, `input[type="submit"]`, `input[type="reset"]`
+- `input[type="text|email|password|number|search|url|tel|date|time|datetime-local"]`
+- `select`, `textarea`
+- `fieldset`, `legend`, `label`
+- `input[type="checkbox"]`, `input[type="radio"]`
+- `progress`, `meter`
+- `:focus-visible` ring styling
+- `aria-invalid`, `aria-busy` states
+- `[disabled]` styling
+
+### Out of scope
+- Form layout/grid (→ layouts layer)
+- Custom form components built with data-attributes (→ data-attributes layer)
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- All interactive elements must have visible focus indicators
+- Respects `prefers-color-scheme` and `prefers-contrast`

openspec/specs/framework/landmarks/spec.md

@@ -0,0 +1,29 @@
+# Spec: Landmarks (Layer 03)
+
+File: `src/layers/03-landmarks.css`
+
+## Purpose
+
+Styling for HTML landmark elements — the structural bones of a page. These elements convey document structure to both browsers and screen readers.
+
+## Scope
+
+### In scope
+- `body > nav` — global navigation bar
+- `article` — content card or post
+- `aside` — sidebar panels
+- `section` — content grouping
+- `body > footer` — global footer
+- `hgroup` — heading groups
+- `header` within landmarks
+- `dt`, `dd` — definition lists (structural, not component)
+
+### Out of scope
+- Navigation menus and dropdowns (→ navigation layer)
+- Sidebar nav behavior `nav[data-nav="sidebar"]` (→ navigation layer)
+- Article styling within specific layouts (→ layouts layer)
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- Landmark styling should be layout-independent — works in any `data-layout`

openspec/specs/framework/layouts/spec.md

@@ -0,0 +1,42 @@
+# Spec: Layouts (Layer 11)
+
+File: `src/layers/11-layout.css`
+
+## Purpose
+
+Page-level layout systems. Controls how landmarks arrange on the page. Selected via `data-layout` attribute.
+
+## Layout Types
+
+### `data-layout="docs"` — Documentation
+Three-column layout: sidebar navigation, main content, table of contents. The standard documentation pattern.
+
+### `data-layout="console"` — Console
+Docs variant: sidebar flush to viewport edge. Prototype — not yet used in production.
+
+### `data-layout="grid-2"` / `data-layout="grid-3"` — Grids
+Multi-column content grids for cards, galleries, dashboards.
+
+### Essay layout
+Long-form prose with table of contents. Wider reading measure, typographic refinements.
+
+### Prose width
+`--width-prose` constrains content to readable line length within any layout.
+
+## Scope
+
+### In scope
+- `data-layout` attribute styling
+- Prose width constraints
+- Responsive layout breakpoints
+- Essay/long-form layout variant
+
+### Out of scope
+- Landmark styling within layouts (→ landmarks layer)
+- Navigation behavior within layouts (→ navigation layer)
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- Layouts must degrade gracefully on mobile (single column)
+- No layout should require JavaScript

openspec/specs/framework/navigation/spec.md

@@ -0,0 +1,27 @@
+# Spec: Navigation (Layer 06)
+
+File: `src/layers/06-navigation.css`
+
+## Purpose
+
+Navigation patterns that go beyond the basic `nav` landmark. Sidebar navigation, table of contents, dropdown menus, navigation state management.
+
+## Scope
+
+### In scope
+- `nav[data-nav="sidebar"]` — sidebar navigation tree
+- `aside[data-toc]` — in-page table of contents
+- Dropdown menus within navigation
+- Active/current page indicators (`aria-current`)
+- Mobile navigation patterns
+- Navigation collapse/expand behavior
+
+### Out of scope
+- The `body > nav` landmark itself (→ landmarks layer)
+- Breadcrumbs (→ components layer)
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- Navigation must be keyboard-accessible
+- Active states use `aria-current`, not classes

openspec/specs/framework/tokens/spec.md

@@ -0,0 +1,77 @@
+# Spec: Tokens (Layer 01)
+
+File: `src/layers/01-tokens.css`
+
+## Purpose
+
+Pure design token definitions. Aliases Open Props primitives to semantic names. Contains only `:root {}` variable declarations — no rules, no selectors, no styling.
+
+## Open Props Dependency
+
+ASW builds on Open Props as its primitive token source. Open Props provides:
+- Color scales: `--color-0` through `--color-16`
+- Size scale: `--size-1` through `--size-15`, `--size-px-1` through `--size-px-12`
+- Font sizes: `--font-size-0` through `--font-size-8`
+- Font weights: `--font-weight-1` through `--font-weight-9`
+- Shadows: `--shadow-1` through `--shadow-6`
+- Border sizes: `--border-size-1` through `--border-size-5`
+- Animations, easings, gradients, and more
+
+**Version:** tracked in `vendor/open-props/VERSION`
+
+## Aliasing Contract
+
+Every Open Props primitive used in the framework MUST be aliased through this file. Downstream layers (02+) MUST reference semantic aliases, never primitives.
+
+```css
+/* YES — downstream layers use this */
+color: var(--text);
+font-weight: var(--weight-bold);
+padding: var(--space-4);
+
+/* NO — never in layers 02+ */
+color: var(--color-6);
+font-weight: var(--font-weight-7);
+padding: var(--size-3);
+```
+
+## Token Categories
+
+### Colors
+- `--surface`, `--surface-alt` — background colors
+- `--text`, `--text-muted` — foreground colors
+- `--accent`, `--accent-hover` — interactive/brand color
+- `--border`, `--border-muted` — border colors
+- `--code-bg`, `--code-text` — code block colors
+
+### Spacing
+- `--space-1` through `--space-7` — spacing scale
+- Maps to Open Props `--size-N` scale
+
+### Typography
+- `--weight-normal`, `--weight-medium`, `--weight-semibold`, `--weight-bold`
+- `--font-body`, `--font-mono` — font stacks
+- `--line-height-body`, `--line-height-heading`
+- `--width-prose` — max-width for readable text
+
+### Shadows
+- `--shadow-dropdown`, `--shadow-modal` — purpose-named shadows
+
+### Focus / Interaction
+- `--focus-ring-width` — keyboard focus ring width
+
+## Scenarios
+
+### Given a new primitive reference needed
+- **When** a downstream layer needs an Open Props value
+- **Then** add a semantic alias to this file first
+- **And** reference only the alias in the downstream layer
+
+### Given an unused token
+- **When** auditing finds a token alias with zero references in layers 02+
+- **Then** it may be removed from this file
+
+### Given this file
+- **When** inspected
+- **Then** it contains only `:root {}` with `--custom-property: value;` declarations
+- **And** no element selectors, no class selectors, no rules

openspec/specs/framework/typography/spec.md

@@ -0,0 +1,30 @@
+# Spec: Typography (Layer 02)
+
+File: `src/layers/02-typography.css`
+
+## Purpose
+
+Prose and heading defaults. Responsive typography scale, font stacks, line heights, heading hierarchy, inline elements (code, mark, links, abbreviations).
+
+## Scope
+
+### In scope
+- `body` font defaults
+- `h1`–`h6` sizing and weight hierarchy
+- `p`, `blockquote`, `ul`, `ol`, `li` prose rhythm
+- `a` link styling
+- `code`, `kbd`, `pre` inline/block code
+- `mark`, `abbr`, `small`, `sub`, `sup` inline semantics
+- `hr` horizontal rules
+- Responsive font-size scaling
+
+### Out of scope
+- Syntax highlighting colors (→ chroma layer)
+- Navigation typography (→ navigation layer)
+- Component-specific text styling (→ components layer)
+
+## Constraints
+
+- References only semantic aliases from `01-tokens.css`
+- No Open Props primitives directly
+- No element selectors that belong to landmarks (nav, footer, header)

openspec/specs/framework/utilities/spec.md

@@ -0,0 +1,27 @@
+# Spec: Utilities (Layer 08)
+
+File: `src/layers/08-utilities.css`
+
+## Purpose
+
+Small, single-purpose helpers for text, visibility, and accessibility. The escape hatch for edge cases that don't warrant a data-attribute.
+
+## Scope
+
+### In scope
+- Text alignment helpers
+- Visually-hidden (screen reader only)
+- Visibility toggles
+- Print styles
+- `prefers-reduced-motion` resets
+- `prefers-contrast` adjustments
+
+### Out of scope
+- Layout utilities (→ layouts layer)
+- Spacing/sizing utilities (use tokens directly)
+- Color utilities (use tokens directly)
+
+## Constraints
+
+- This layer should be minimal — most needs should be met by semantic elements + data attributes
+- References only semantic aliases from `01-tokens.css`

openspec/specs/packs/spec.md

@@ -0,0 +1,46 @@
+# Spec: Packs
+
+Directory: `packs/`
+
+## Purpose
+
+Engine integration bundles. Each pack adapts ASW for a specific web server or static site generator. A pack is a self-contained directory that someone can copy into their project.
+
+## Current Packs
+
+| Pack | Purpose | Source |
+|------|---------|--------|
+| `hugo/` | Hugo theme: layouts, partials, archetypes, static assets | Legacy repo |
+| `apache/` | Autoindex styling, error pages, Apache conf snippets | Legacy repo |
+| `caddy/` | Browse template, error pages, Caddyfile snippets | Legacy repo |
+| `flask/` | Python error handler, Flask integration | Legacy repo |
+| `nginx/` | Autoindex header, error pages, Nginx conf snippets | Legacy repo |
+| `pandoc/` | HTML5 template, Lua filter for ASW output | Legacy repo |
+| `python/` | Simple Python HTTP server with ASW styling | Legacy repo |
+
+## Pack Contract
+
+Each pack directory MUST contain:
+- `README.md` — what the pack does, how to install/use it
+- All files needed for integration (conf snippets, templates, static assets)
+
+Each pack SHOULD:
+- Reference `dist/asw.css` for the framework CSS (not `src/layers/`)
+- Be self-contained — no dependencies outside the pack directory and `dist/`
+- Include example configuration
+
+## Scenarios
+
+### Given a new engine integration
+- **When** someone wants ASW support for a new engine
+- **Then** they create `packs/<engine>/` with a README and integration files
+- **And** the pack references `dist/asw.css`
+
+### Given the Hugo pack
+- **When** the ASW website is built
+- **Then** it uses `packs/hugo/` for layouts, partials, and configuration
+- **And** `site/` contains Hugo-specific overrides on top of the pack
+
+## Note
+
+The Hugo pack is special: the ASW website (`site/`) is built with it. The pack provides the base; `site/` adds content and any site-specific customization. This is both a real integration and a living example.

openspec/specs/repo-structure/spec.md

@@ -0,0 +1,96 @@
+# Spec: Repository Structure
+
+The directory layout contract for ASW. Defines what lives where and the boundary rules.
+
+## Directory Map
+
+```
+asw/
+  src/                  Framework CSS source
+    layers/             Numbered CSS layer files (00-reset through 12-landing)
+    main.css            Entry point — @import chain for all layers
+    lab/                Experiments and test pages (not published)
+  dist/                 Built output (committed to repo)
+    asw.css             Single concatenated file
+    asw.min.css         Minified
+  vendor/               Explicit external dependencies
+    open-props/         Open Props CSS (with VERSION file)
+    README.md           What's vendored, why, how to update
+  packs/                Engine integration bundles
+    hugo/               Hugo theme/partial integration
+    apache/             Apache autoindex + error pages
+    caddy/              Caddy browse + error pages
+    flask/              Flask error handlers
+    nginx/              Nginx autoindex + error pages
+    pandoc/             Pandoc HTML5 template + Lua filter
+    python/             Python HTTP server with ASW styling
+  docs/                 Framework documentation (markdown only)
+  examples/             Static HTML showcases (no build step needed)
+  site/                 The ASW website (currently uses Hugo pack)
+    content/            Site-specific content (articles, essays, notes)
+    layouts/            Hugo templates
+    hugo.toml           Hugo config (mounts docs/ as content/docs/)
+    static/             Site static assets
+  openspec/             Specs and changes
+```
+
+## Boundary Rules
+
+### src/ — framework only
+- Contains only CSS source files and lab experiments
+- No Hugo-specific files, no content, no templates
+- `main.css` imports from `layers/` using relative paths
+- `lab/` contains HTML files that reference layers directly — never published
+
+### dist/ — build artifacts, committed
+- Built by PostCSS from `src/main.css`
+- Committed to repo so consumers can grab without a build step
+- Regenerated on deploy, not manually edited
+
+### vendor/ — visible dependencies
+- Open Props source files copied from npm, with version tracking
+- `VERSION` file records package version and date of last update
+- Updated manually when bumping Open Props
+
+### packs/ — engine-agnostic integrations
+- Each subdirectory is a self-contained integration for one engine
+- A pack may reference `dist/asw.css` or `src/layers/` depending on its needs
+- Packs ship their own README
+
+### docs/ — markdown only
+- No HTML, no engine-specific markup
+- The site consumes these as content source (Hugo module mount)
+- GitHub/Forgejo renders these directly — no build step to read docs
+
+### examples/ — static HTML
+- Each file is a standalone demo that loads ASW
+- Can be opened in a browser by cloning the repo — no build step
+- The site may link to these but they exist independently
+
+### site/ — website concerns
+- All Hugo-specific files live here
+- `content/docs/` is mounted from `../docs/`, not duplicated
+- Site-specific content (articles, essays, notes) lives in `content/`
+- Changes to the site do not affect the framework; changes to the framework may affect the site
+
+## Scenarios
+
+### Given a new CSS layer
+- **When** an agent creates it
+- **Then** it goes in `src/layers/` with the next number
+- **And** `src/main.css` gets an @import line
+
+### Given a new framework doc
+- **When** an agent writes documentation
+- **Then** it goes in `docs/` as a .md file
+- **And** the site picks it up automatically via Hugo mount
+
+### Given a new engine integration
+- **When** someone adds support for a new engine (e.g., Eleventy)
+- **Then** it goes in `packs/<engine>/` with its own README
+
+### Given a lab experiment
+- **When** an agent wants to test a CSS pattern
+- **Then** it creates a file in `src/lab/`
+- **And** it references layers via relative paths
+- **And** it is never published to the site

openspec/specs/site/spec.md

@@ -0,0 +1,52 @@
+# Spec: Site
+
+Directory: `site/`
+
+## Purpose
+
+The ASW framework's own website. Serves as documentation site, demo platform, and living proof that the framework works. Currently built with the Hugo pack.
+
+## Content Types
+
+### Docs (from `../docs/`)
+Framework documentation, mounted as Hugo content via module mount. Not duplicated — sourced from the engine-agnostic `docs/` directory.
+
+### Articles (`content/articles/`)
+Short-form writing about ASW concepts, patterns, and techniques. No TOC.
+
+### Essays (`content/essays/`)
+Long-form writing. TOC, description, wider reading measure.
+
+### Notes (`content/notes/`)
+Exported PKM vault notes. Session logs, diffs, status, tasks, wikilinks.
+
+### Pages (`content/pages/`)
+Static pages: about, etc.
+
+## Engine
+
+Currently Hugo. The site uses `packs/hugo/` as its base and adds:
+- Site-specific layouts and overrides
+- `hugo.toml` with module mounts
+- Site-specific static assets
+
+## Principle
+
+The site is a consumer of the framework, not part of it. A different site could be built with `packs/flask/` or `packs/caddy/` using the same `docs/` and `dist/asw.css`. The framework does not depend on the site. The site depends on the framework.
+
+## Scenarios
+
+### Given a framework docs change
+- **When** a markdown file in `docs/` is modified
+- **Then** the site picks it up automatically via Hugo mount
+- **And** no file in `site/` needs to change
+
+### Given a CSS framework change
+- **When** `src/layers/` is modified
+- **Then** `dist/asw.css` is rebuilt
+- **And** the site serves the updated CSS
+
+### Given a site-only change (new article, essay)
+- **When** content is added to `site/content/`
+- **Then** only the site is affected
+- **And** `src/`, `dist/`, `docs/` are untouched