## Context

ASW is a classless CSS framework for AI agents. The framework itself is working — semantic HTML + data-attributes are styled correctly across 13 CSS layers. But it's bundled with OpenProps (~25KB overhead, ~40 of 500+ tokens actually used), wrapped in a Hugo documentation site, and has no publishable templates (current examples use SSI `<!--#include-->`).

The repo has three unshipped development concerns (engine packs, lab experiments, Hugo site) mixed into the root alongside the framework source. For 0.1, these are deferred — moved to `archive/` but never deleted.

## Goals / Non-Goals

**Goals:**
- Replace OpenProps with a hand-authored native CSS token system (~4KB)
- Remove `open-props` npm dependency and PostCSS import
- Move non-0.1 content into `archive/` directory
- Create 5-6 standalone working HTML templates
- Rewrite README for 0.1 publication
- Tag `v0.1` on git

**Non-Goals:**
- Documentation site (0.2)
- Engine packs (0.3)
- CSS layer refactoring (cosmetic renames can happen but aren't required)
- New CSS features beyond the token replacement
- Backward compatibility with OpenProps-based custom themes

## Decisions

### D1: Native CSS token system over OpenProps

**Decision:** Replace `@import "open-props/open-props.min.css"` with a single `src/tokens.css` file defining ~40 CSS custom properties using `oklch()` and relative color syntax. Remove `open-props` from `package.json`. Remove `postcss-import` from the build chain.

```
BEFORE:                     AFTER:
@import "open-props/..."    →  (removed)
var(--size-3)               →  1rem
var(--gray-0)               →  oklch(0.95 0.01 250)
var(--ease-3)               →  var(--ease-out-quad) [or concrete cubic-bezier]
var(--font-mono)            →  'Fira Code', 'Cascadia Code', monospace
```

**Rationale:**
- ASW uses ~40 of 500+ OpenProps tokens — 85% dead weight shipped to every page
- Native CSS (`oklch()`, `light-dark()`, `color-mix()`, relative color syntax) now covers every use case OpenProps was providing
- Eliminates an external dependency and the `postcss-import` build step
- The ~40 values are trivially derivable — font stacks, size scales, and gray steps are design constants, not secrets
- MIT license on OpenProps allows verbatim value copying where useful

**Alternatives considered:**
- **Keep OpenProps**: Still works, but 25KB tax for no marginal benefit
- **Terrazzo/DTCG**: Full design-token toolchain is overkill for a project that needs ~40 values
- **Style Dictionary v4**: Enterprise-grade, too heavy for a CSS-only framework

### D2: In-place archive pattern for deferred content

**Decision:** Move `packs/`, `site/`, and `src/lab/` into `archive/` at repo root. No files deleted. No orphan branches. Everything remains in git history.

```
asw/
├── src/                  # Framework CSS (active)
├── templates/            # Standalone HTML templates (new)
├── dist/                 # Built CSS
├── docs/                 # Engine-agnostic docs
├── archive/              # Deferred for 0.2/0.3
│   ├── packs/            # Engine integrations
│   ├── site/             # Hugo documentation website
│   └── lab/              # Experiments
├── openspec/
├── README.md
└── CHANGELOG.md
```

**Rationale:**
- Single repo, single URL, single git history
- `archive/` is a clear signal: "these exist but are not 0.1"
- Easy to restore when 0.2/0.3 come: `git mv archive/packs/ ./`
- No git history surgery, no divergence between branches

### D3: Flexbox layout system via data-attributes

**Decision:** The 0.1 template system uses semantic HTML + `data-layout` attributes for flexbox layouts. No grid. No classes. No wrappers.

```
data-layout="row"       →  display: flex; flex-direction: row
data-layout="col"       →  display: flex; flex-direction: column
data-layout="spread"    →  display: flex; justify-content: space-between
data-layout="center"    →  display: flex; align-items: center; justify-content: center
data-layout="stack"     →  display: flex; flex-direction: column; gap: var(--space-4)
data-layout="grid-2"    →  display: grid; grid-template-columns: repeat(2, 1fr)  (kept from existing)
data-layout="grid-3"    →  display: grid; grid-template-columns: repeat(3, 1fr)  (kept from existing)
```

**Rationale:**
- Flexbox over grid for the 0.1 layouts (simpler, better for content-flow patterns like nav, hero, footer, sidebar+content)
- Keeps the existing `data-layout="grid-2/3"` patterns from the current framework (they work, no need to change)
- Self-documenting: `data-layout="spread"` is readable by both humans and agents

### D4: PostCSS stays for minification only

**Decision:** Keep PostCSS + `cssnano` for minification. Remove `postcss-import` and `open-props`. Build script becomes:
```
postcss src/main.css -o dist/asw.css --no-import
```
Or, if all imports are removed from `src/main.css`, simplify to just `cssnano` on the single file.

**Rationale:**
- Minification is still valuable for distribution
- No more build-time dependency on OpenProps or CSS import resolution
- Future: could eliminate PostCSS entirely and use `lightningcss` or just ship unminified

## Risks / Trade-offs

| Risk | Mitigation |
|---|---|
| **oklch values don't match OpenProps grays exactly** | OpenProps uses sRGB hex. oklch gray values are perceptually different. Visual regression acceptable — 0.1 is a new baseline, not a patch. |
| **Users who customized ASW via OpenProps overrides will break** | 0.1 is a new baseline. Document breaking change in CHANGELOG. There are no known external users yet. |
| **archive/ dir grows stale and confusing** | Each future release (0.2, 0.3) explicitly pulls from archive/. If stuff remains archived two releases, evaluate deletion. |
| **PostCSS removal may need re-evaluation** | If `cssnano` is the only plugin, consider swapping to `lightningcss` (Rust-based) or just shipping unminified with a gzip note. Defer to 0.2. |