asw-v01: drop OpenProps, native CSS tokens system
- Replace OpenProps (~25KB) with native src/tokens.css (~40 tokens) - Remove open-props, postcss-import from package.json + postcss.config - Update main.css: remove @import open-props/*, import ./tokens.css - Rewrite 01-tokens.css header to reference tokens.css - All raw OpenProps values (font stacks, sizes, weights, colors, easings, durations, shadows, radii, animations, media queries) now defined natively in tokens.css - Build uses cat concat + cssnano (no postcss-import needed) - Build output: 78KB minified (saved ~24KB from OpenProps removal)
This commit is contained in:
parent
e47a9f4401
commit
a433b935fa
GPG key ID:
D52E9C8491872206
16 changed files with 6644 additions and 120 deletions
2
openspec/changes/asw-v01-release/.openspec.yaml
Normal file
2
openspec/changes/asw-v01-release/.openspec.yaml
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
schema: spec-driven
|
||||
created: 2026-06-07
|
||||
115
openspec/changes/asw-v01-release/design.md
Normal file
115
openspec/changes/asw-v01-release/design.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
## 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. |
|
||||
45
openspec/changes/asw-v01-release/proposal.md
Normal file
45
openspec/changes/asw-v01-release/proposal.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
## Why
|
||||
|
||||
ASW has been in experimental development — a working CSS framework buried inside a Hugo documentation site, with 7 engine packs, lab experiments, a PostCSS build pipeline, and SSI-based examples that don't work standalone. The framework itself is solid (semantic HTML + data-attributes), but it's not publishable as `v0.1` because:
|
||||
|
||||
1. **Bloat**: It ships OpenProps (~25KB) while only using ~40 of 500+ tokens
|
||||
2. **No working templates**: The examples directory uses SSI (`<!--#include virtual=...-->`) — they don't open in a browser
|
||||
3. **Obscured core**: The framework lives in 13 CSS layers, buried under Hugo templates, packs, and experiments
|
||||
4. **No clear dev path**: A new developer lands and sees Hugo + PostCSS + packs and doesn't know what ASW *is*
|
||||
|
||||
0.1 is the "minimum viable framework" — just the CSS, a handful of working templates, and a clear README. Everything else stays in the repo for 0.2 (documentation site) and 0.3 (engine packs).
|
||||
|
||||
## What Changes
|
||||
|
||||
- **Drop OpenProps dependency** — replace with hand-authored native CSS token system using `oklch()` and relative color syntax. Removes `open-props` from `package.json`, removes `postcss-import` of OpenProps. Framework goes from ~25KB baseline to ~4KB.
|
||||
- **Prune repo surface** — move `packs/`, `src/lab/`, and `site/` into `archive/` directory. No deletion. Everything stays in git.
|
||||
- **Simplify build** — PostCSS stays for minification (`cssnano`), but no OpenProps import. `postcss-import` may become optional.
|
||||
- **5-6 working standalone HTML templates** — semantic HTML, flexbox via `data-layout` attributes. No SSI. No Hugo. Open in a browser and they work.
|
||||
- **New README + CHANGELOG** — "link this one CSS file" documentation. Roadmap forward.
|
||||
- **Vendor the used OpenProps values** — copy the ~40 tokens we actually use into our token file (MIT license, legally clean).
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `native-tokens`: The design token system — oklch-based colors, size scales, spacing, typography. Zero external dependencies. Powers all ASW styling.
|
||||
- `flexbox-layouts`: Layout system via `data-layout` attributes. Pure flexbox. `data-layout="row"`, `data-layout="col"`, `data-layout="spread"`, `data-layout="center"`, `data-layout="stack"`, etc.
|
||||
- `reference-templates`: Standalone HTML files that demonstrate the framework — landing page, docs page, prose/article, stats/dashboard, vault/tasks page.
|
||||
|
||||
### Modified Capabilities
|
||||
*(No existing spec-level requirements are changing — we're replacing the token foundation and adding new layout/template capabilities)*
|
||||
|
||||
## Impact
|
||||
|
||||
| File / Directory | Action |
|
||||
|---|---|
|
||||
| `package.json` | Remove `open-props` dependency |
|
||||
| `postcss.config.js` | Remove `postcss-import` (no longer needed) |
|
||||
| `src/main.css` | Remove OpenProps `@import` lines, update layer imports |
|
||||
| `src/layers/01-tokens.css` | Replace OpenProps primitives with native oklch values |
|
||||
| `dist/asw.css` | Rebuild — drops from ~28KB to ~6KB |
|
||||
| `packs/` | Move to `archive/packs/` |
|
||||
| `src/lab/` | Move to `archive/lab/` |
|
||||
| `site/` | Move to `archive/site/` |
|
||||
| `examples/` | Replace SSI-based examples with standalone templates |
|
||||
| `README.md` | Rewrite for 0.1 — "link this one file" |
|
||||
| `CHANGELOG.md` | New file |
|
||||
|
|
@ -0,0 +1,42 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Layouts are invoked via `data-layout` attributes
|
||||
All layout patterns SHALL be activated through `data-layout` attribute values on HTML elements. No CSS classes or inline styles SHALL be required to produce a layout.
|
||||
|
||||
#### Scenario: data-layout="row" creates horizontal flex container
|
||||
- **WHEN** an element has `data-layout="row"` (e.g., `<nav data-layout="row">`)
|
||||
- **THEN** the element MUST have `display: flex` and `flex-direction: row`
|
||||
|
||||
#### Scenario: data-layout="col" creates vertical flex container
|
||||
- **WHEN** an element has `data-layout="col"`
|
||||
- **THEN** the element MUST have `display: flex` and `flex-direction: column`
|
||||
|
||||
#### Scenario: data-layout="spread" distributes items across the main axis
|
||||
- **WHEN** an element has `data-layout="spread"`
|
||||
- **THEN** it MUST have `display: flex`, `justify-content: space-between`, and `align-items: center`
|
||||
|
||||
#### Scenario: data-layout="center" centers items on both axes
|
||||
- **WHEN** an element has `data-layout="center"`
|
||||
- **THEN** it MUST have `display: flex`, `align-items: center`, and `justify-content: center`
|
||||
|
||||
#### Scenario: data-layout="stack" creates a vertical column with gap
|
||||
- **WHEN** an element has `data-layout="stack"`
|
||||
- **THEN** it MUST have `display: flex`, `flex-direction: column`, and a `gap` value using the ASW spacing token
|
||||
|
||||
### Requirement: Existing grid layouts are preserved
|
||||
The existing `data-layout="grid-2"` and `data-layout="grid-3"` patterns from the current framework SHALL continue to work unchanged.
|
||||
|
||||
#### Scenario: grid-2 creates 2-column CSS grid
|
||||
- **WHEN** an element has `data-layout="grid-2"`
|
||||
- **THEN** it MUST have `display: grid` and `grid-template-columns: repeat(2, 1fr)`
|
||||
|
||||
#### Scenario: grid-3 creates 3-column CSS grid
|
||||
- **WHEN** an element has `data-layout="grid-3"`
|
||||
- **THEN** it MUST have `display: grid` and `grid-template-columns: repeat(3, 1fr)`
|
||||
|
||||
### Requirement: Flexbox layouts are responsive by default
|
||||
All flexbox layout patterns SHALL wrap on narrow viewports unless explicitly prevented.
|
||||
|
||||
#### Scenario: Row wraps on small screens
|
||||
- **WHEN** `data-layout="row"` is displayed on a viewport narrower than 640px
|
||||
- **THEN** its items MUST wrap to a new line (`flex-wrap: wrap`)
|
||||
36
openspec/changes/asw-v01-release/specs/native-tokens/spec.md
Normal file
36
openspec/changes/asw-v01-release/specs/native-tokens/spec.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Token system imports no external CSS
|
||||
The token file SHALL NOT use `@import` to pull in any external CSS library. All custom properties MUST be defined inline using native CSS functions.
|
||||
|
||||
#### Scenario: Zero external imports
|
||||
- **WHEN** the token CSS file is inspected
|
||||
- **THEN** it MUST contain zero `@import` statements
|
||||
|
||||
### Requirement: Color tokens use oklch color space
|
||||
All color custom properties SHALL use the `oklch()` color function. No hex, no rgb(), no hsl().
|
||||
|
||||
#### Scenario: All colors are oklch
|
||||
- **WHEN** any `--*-color` or `--*-bg` or `--*-surface` custom property is inspected
|
||||
- **THEN** its value MUST be a valid `oklch()` function
|
||||
|
||||
### Requirement: Token set covers all ASW layer references
|
||||
The token system MUST define every custom property referenced by CSS layers 02 through 12. No layer file SHALL reference an undefined custom property.
|
||||
|
||||
#### Scenario: Layer files compile without warnings
|
||||
- **WHEN** PostCSS compiles `src/main.css`
|
||||
- **THEN** the build MUST succeed with no warnings about undefined variables
|
||||
|
||||
### Requirement: Token values are semantically named
|
||||
Token names SHALL describe the semantic role, not the presentation value. E.g., `--surface-page` not `--gray-3`. `--text-body` not `--font-size-1`.
|
||||
|
||||
#### Scenario: No OpenProps primitive names in layer files
|
||||
- **WHEN** any CSS layer file (02-12) is searched for OpenProps-style names (e.g., `--size-`, `--gray-`, `--red-`, `--ease-`)
|
||||
- **THEN** no matches SHALL be found outside of the token file
|
||||
|
||||
### Requirement: Reduced baseline CSS size
|
||||
The token system SHALL produce a CSS output smaller than the current OpenProps baseline (currently ~25KB for OpenProps imports + ASW layers).
|
||||
|
||||
#### Scenario: Output size under 10KB minified
|
||||
- **WHEN** `dist/asw.min.css` is built
|
||||
- **THEN** its file size MUST be less than 10KB (vs ~28KB current baseline)
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
## ADDED Requirements
|
||||
|
||||
### Requirement: Templates are standalone HTML files
|
||||
Each template SHALL be a single `.html` file that opens correctly in a browser with no build step, no server, and no SSI includes. All CSS references SHALL be relative paths or absolute URLs.
|
||||
|
||||
#### Scenario: Template opens without errors
|
||||
- **WHEN** any template HTML file is opened in a browser
|
||||
- **THEN** it MUST display styled content with no JavaScript errors and no missing resource warnings
|
||||
|
||||
### Requirement: Templates use semantic HTML only
|
||||
Templates SHALL use semantic HTML elements (`<nav>`, `<main>`, `<article>`, `<section>`, `<header>`, `<footer>`, `<aside>`) for structure. No `<div class="...">` wrapper pattern.
|
||||
|
||||
#### Scenario: Templates contain zero class attributes for layout
|
||||
- **WHEN** any template is scanned for `class=` attributes
|
||||
- **THEN** any class attributes found MUST only be for Prism.js syntax highlighting or other non-layout purposes
|
||||
|
||||
### Requirement: Templates demonstrate flexbox layouts
|
||||
Each template SHALL use at least one `data-layout` flexbox attribute for its primary layout structure, demonstrating the flexbox layout system is functional.
|
||||
|
||||
#### Scenario: Each template uses data-layout for structure
|
||||
- **WHEN** any template is inspected
|
||||
- **THEN** it MUST contain at least one `data-layout` attribute on a structural element
|
||||
|
||||
### Requirement: Template set covers common page types
|
||||
The 0.1 release SHALL include at minimum the following templates:
|
||||
|
||||
| Template | Description |
|
||||
|---|---|
|
||||
| `index.html` | Landing/hero page — full-width hero, feature cards, CTA |
|
||||
| `docs.html` | Documentation layout — sidebar nav + main content area |
|
||||
| `article.html` | Long-form prose — reading-optimized width, blockquotes, code |
|
||||
| `dashboard.html` | Stats/dashboard — stats grid, data display, status indicators |
|
||||
| `tasks.html` | Vault/tasks page — task list with data-task attributes |
|
||||
|
||||
#### Scenario: All five template files exist
|
||||
- **WHEN** the `templates/` directory is listed
|
||||
- **THEN** all five template files SHALL be present as `.html` files
|
||||
38
openspec/changes/asw-v01-release/tasks.md
Normal file
38
openspec/changes/asw-v01-release/tasks.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
## 1. Token System — Replace OpenProps with Native CSS
|
||||
|
||||
- [ ] 1.1 Create `src/tokens.css` with all ~40 native oklch custom properties (colors, sizes, spacing, fonts, easings). Copy needed values from OpenProps under MIT license.
|
||||
- [ ] 1.2 Update `src/main.css` — remove `@import "open-props/..."` lines, add `@import "./tokens.css"` header.
|
||||
- [ ] 1.3 Audit all 13 layer files (02-12) — remove any remaining OpenProps primitive references (`--size-N`, `--gray-N`, `--ease-N`, etc.), replace with sem tokens from `tokens.css`.
|
||||
- [ ] 1.4 Remove `"open-props"` from `package.json`. Remove `postcss-import` from `postcss.config.js` and `package.json`.
|
||||
- [ ] 1.5 Build and verify: `postcss src/main.css -o dist/asw.css` succeeds, output under 10KB minified.
|
||||
|
||||
## 2. Archive Deferred Content
|
||||
|
||||
- [ ] 2.1 Create `archive/` directory. Move `packs/` → `archive/packs/`.
|
||||
- [ ] 2.2 Move `site/` → `archive/site/`.
|
||||
- [ ] 2.3 Move `src/lab/` → `archive/lab/`.
|
||||
- [ ] 2.4 Move legacy examples (SSI-based) → `archive/examples-legacy/`. Ensure nothing is deleted from git.
|
||||
|
||||
## 3. Flexbox Layout System
|
||||
|
||||
- [ ] 3.1 Add `data-layout="row"` CSS rule — flexbox horizontal with wrap.
|
||||
- [ ] 3.2 Add `data-layout="col"` and `data-layout="stack"` CSS rules — vertical flex with gap.
|
||||
- [ ] 3.3 Add `data-layout="spread"` and `data-layout="center"` CSS rules — justify-content/align-items patterns.
|
||||
- [ ] 3.4 Add responsive wrapping behavior for narrow viewports (breakpoint at 640px).
|
||||
|
||||
## 4. Build Working Templates
|
||||
|
||||
- [ ] 4.1 Create `templates/index.html` — landing/hero page with data-layout="col stack spread center", semantic nav, feature cards.
|
||||
- [ ] 4.2 Create `templates/docs.html` — documentation layout with sidebar nav + main content area using flexbox.
|
||||
- [ ] 4.3 Create `templates/article.html` — long-form prose layout with code blocks, blockquotes, footnotes.
|
||||
- [ ] 4.4 Create `templates/dashboard.html` — stats grid with data-layout="row spread", status indicators, charts.
|
||||
- [ ] 4.5 Create `templates/tasks.html` — vault-style task tracking page with data-task attributes.
|
||||
- [ ] 4.6 Verify each template opens in browser with no errors and no SSI includes.
|
||||
|
||||
## 5. Release Prep
|
||||
|
||||
- [ ] 5.1 Rewrite `README.md` for 0.1 — "link this one CSS file" instructions, quick start, vocabulary, roadmap.
|
||||
- [ ] 5.2 Create `CHANGELOG.md` with 0.1 entry — Breaking: dropped OpenProps, new token system, archive restructuring.
|
||||
- [ ] 5.3 Final build: `npm run build && npm run build:min`. Verify `dist/asw.css` and `dist/asw.min.css` exist and are under 10KB.
|
||||
- [ ] 5.4 Git commit all changes with message `asw-v01: framework core, native tokens, templates, archive deferral`.
|
||||
- [ ] 5.5 Tag `v0.1`: `git tag -a v0.1 -m "ASW 0.1 — Framework core with native tokens and reference templates"`.
|
||||
Loading…
Add table
Add a link
Reference in a new issue