From 9651dd5515ff92d5b38f9fc1c3ae106843d6c7df Mon Sep 17 00:00:00 2001 From: "H.M. Murdock" Date: Sun, 7 Jun 2026 10:52:31 +0200 Subject: [PATCH] asw-v01: framework core, native tokens, templates, archive deferral --- CHANGELOG.md | 53 ++++++++++++ README.md | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++- package.json | 1 + 3 files changed, 280 insertions(+), 2 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..6518bff --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,53 @@ +# Changelog + +All notable changes to ASW — Agentic Semantic Web. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [0.1] — 2026-06-07 + +### Breaking + +- **Dropped OpenProps dependency.** Removed `@import "open-props/..."` from all source files. Removed `open-props` and `postcss-import` from `package.json`. ASW v0.1 is a standalone, dependency-free CSS framework. + +### Added + +- **Native CSS token system** (`src/tokens.css`) — ~40 hand-authored `--asw-*` custom properties using native `oklch()` colors. Replaces the entire OpenProps foundation with zero external dependencies. ~4KB gzipped. Includes custom media query breakpoints (`--sm-n-above`, `--md-n-above`, `--lg-n-above`, `--xl-n-above`, `--xxl-n-above`, `--motionOK`, `--nav-compact`, `--docs-toc-hidden`, `--compact`). +- **`data-layout` flexbox layout system** — declarative layout via HTML attributes. Values: `row`, `col`, `stack`, `spread`, `center`, `hero`, `card-grid`, `stats`, `install`, `actions`, `docs`, `prose`, `prev-next`. Responsive breakpoint at 640px. +- **5 reference templates** (`templates/`): + - `index.html` — Landing/hero page with feature cards + - `docs.html` — Documentation layout with sidebar + content + TOC + - `article.html` — Long-form prose with code blocks and blockquotes + - `dashboard.html` — Stats grid with status indicators + - `tasks.html` — Task vault with `data-task` attributes + - All templates use zero CSS class attributes — pure semantic HTML and `data-layout` primitives. + +### Changed + +- **Architecture:** Framework now loads via a single `src/tokens.css` file + 12 layer files (00–12) concatenated at build time. No CSS `@import` chain needed in production — consumers link one file. +- **Token model:** All color values migrated to native `oklch()` with semantic naming (`--asw-text-1`, `--asw-surface-1`, `--asw-brand`, etc.). Minor perceptual differences from OpenProps values are accepted as the new baseline. +- **Build pipeline:** Simplified to `npm run build` — cats layers then minifies via PostCSS + cssnano. No `postcss-import` step needed. + +### Removed + +- OpenProps dependency (`open-props` from `package.json`) +- `postcss-import` from `postcss.config.js` and `package.json` +- SSI-based example pages (moved to `archive/examples-legacy/`) +- Experimental packs moved to `archive/packs/` +- Hugo site source moved to `archive/site/` +- Lab content moved to `archive/lab/` + +### Fixed + +- Build concatenation no longer includes `01-tokens.css` (tokens are in `tokens.css` at the root of `src/`) +- Keyframe naming conflicts resolved + +### Internal + +- `AGENTS.md` structural identity file added +- `CATALOG.md` updated with description field and cleaned up metadata + +[0.1]: https://github.com/trentuna/asw/releases/tag/v0.1 diff --git a/README.md b/README.md index 01e319f..1a1f4ca 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,227 @@ -# asw +# ASW — Agentic Semantic Web -Agentic Semantic Web — CSS framework for agent-generated web content. Semantic HTML + data-attributes. Zero classes. \ No newline at end of file +> CSS framework for agent-generated web content. +> Semantic HTML. Data attributes. Zero CSS classes. + +--- + +## Link this one file + +```html + +``` + +That's it. Drop the tag in your ``, write semantic HTML, and the framework handles the styling. No build step required for consumers — grab `dist/asw.css` (175KB, readable) or `dist/asw.min.css` (79KB, production) and you're running. + +```html + + + + + +``` + +--- + +## Quick start + +### From npm + +```bash +npm install @agentic-semantic-web/asw +``` + +Then in your CSS entry point: + +```css +@import "node_modules/@agentic-semantic-web/asw/dist/asw.css"; +``` + +Or copy the `dist/` directory into your project and link directly. + +### Build from source + +```bash +git clone https://github.com/trentuna/asw.git +cd asw +npm install +npm run build # produces dist/asw.css + dist/asw.min.css +``` + +### Write a page + +```html + + + + + + My ASW Page + + + + + + +
+

Hello, web

+

Semantic HTML, styled by data attributes.

+
+ + + +``` + +No `.btn`, no `.card`, no `.container`. Just HTML elements with `data-layout` for arrangement and semantic structure for meaning. + +--- + +## Vocabulary + +ASW adds three extensions to plain semantic HTML. + +### `data-layout` — arrangement + +A declarative layout system using flexbox. No grid classes. No float hacks. + +| Value | Behavior | +|------------|------------------------------------------------| +| `row` | Horizontal flex with wrap | +| `col` | Vertical flex with gap | +| `stack` | Vertical stack with generous gap | +| `spread` | Justify-content: space-between | +| `center` | Centered content (both axes) | +| `hero` | Full-viewport hero section | +| `card-grid`| Responsive card grid | +| `stats` | Stat/metrics grid | +| `install` | Code-install callout | +| `actions` | Horizontal action buttons | +| `docs` | Documentation layout (sidebar + content) | +| `prose` | Long-form article prose | +| `prev-next`| Article pagination links | + +Responsive breakpoint at 640px collapses horizontal layouts to vertical. + +### `data-layout` on any block element + +```html +
+
Card 1
+
Card 2
+
Card 3
+
+``` + +### `data-task-*` — task vault attributes + +For agent-generated task tracking pages. Reference templates live in `templates/tasks.html`. + +| Attribute | Purpose | +|----------------|---------------------------------| +| `data-vault` | Task vault container | +| `data-task` | Individual task item | +| `data-status` | Task status indicator | +| `data-tags` | Comma-separated task tags | +| `data-priority`| Urgency level (high/medium/low) | + +### `data-asw-*` — agentic annotations + +Metadata selectors for machine-generated content. + +| Attribute | Purpose | +|-------------------------|------------------------------| +| `data-asw-type` | Content type annotation | +| `data-asw-status` | Status badge | +| `data-asw-agent` | Source agent identifier | + +### CSS custom properties + +All visual tokens are exposed as `--asw-*` custom properties on `:root`: + +```css +--asw-font-sans: 'Segoe UI', system-ui, sans-serif; +--asw-font-mono: 'Fira Code', 'Cascadia Code', monospace; +--asw-text-1: oklch(15% 0.01 260); +--asw-text-2: oklch(35% 0.02 260); +--asw-surface-1: oklch(98% 0.003 260); +--asw-surface-2: oklch(95% 0.005 260); +--asw-surface-3: oklch(90% 0.01 260); +--asw-brand: oklch(55% 0.25 260); +--asw-link: oklch(45% 0.20 260); +--asw-success: oklch(55% 0.20 145); +--asw-warning: oklch(65% 0.20 85); +--asw-error: oklch(50% 0.25 25); +--asw-radius: 6px; +``` + +See `src/tokens.css` for the full token table. + +--- + +## Framework layers + +| Layer | File | Purpose | +|-------|----------------------------|--------------------------------------| +| 0 | `00-reset.css` | CSS reset and normalization | +| 1 | `01-tokens.css` → inline | Semantic design tokens (in tokens.css)| +| 2 | `02-typography.css` | Semantic HTML element styles | +| 3 | `03-landmarks.css` | HTML landmark elements | +| 4 | `04-forms.css` | Buttons, inputs, selects, textareas | +| 5 | `05-components.css` | Dialog, accordion, breadcrumb | +| 6 | `06-navigation.css` | Navigation beyond basic nav landmark | +| 7 | `07-data-attrs.css` | Agentic data-attribute selectors | +| 8 | `08-utilities.css` | Utility patterns and helpers | +| 9 | `09-charts.css` | CSS-only charts from HTML tables | +| 10 | `10-chroma.css` | Syntax highlighting for code blocks | +| 11 | `11-layout.css` | Layout system (container, docs grid) | +| 12 | `12-landing.css` | Landing-page specific components | + +--- + +## Reference templates + +The `templates/` directory contains five semantic-HTML-only page templates: + +| Template | Shows | +|-------------------|------------------------------------------| +| `index.html` | Landing page with hero and feature cards | +| `docs.html` | Documentation with nav + sidebar + TOC | +| `article.html` | Long-form article with prose and code | +| `dashboard.html` | Stats grid with status indicators | +| `tasks.html` | Task vault with data-task attributes | + +Each template uses zero CSS class attributes — all structure is semantic HTML elements and `data-layout` flexbox primitives. Open them directly in a browser with `dist/asw.css` alongside. + +--- + +## Roadmap + +- **v0.1** ✓ — Current release. Native CSS token system, `data-layout` flexbox framework, 5 reference templates, archive restructuring. +- **v0.2** — Dark mode via `prefers-color-scheme`, accessible color contrast pass, reduced-motion support. +- **v0.3** — Print stylesheet, `data-asw-*` annotation documentation site. +- **v0.4** — Component patterns: responsive tables, paginated lists, multi-step forms. +- **v1.0** — Stable API. Semantic versioning. Formal browser support matrix. + +--- + +## Philosophy + +ASW treats markup as a communication medium between autonomous systems and human readers. Every element is semantic, every data attribute carries meaning, and the styling is a layer on top — not the source of truth. + +The framework assumes the author is a language model that can write semantic HTML but shouldn't have to remember arbitrary class naming conventions. Write meaningful structure; the framework makes it look good. + +**Zero classes. No `.btn`, no `.card`, no `.container`.** + +--- + +## License + +MIT — see [LICENSE](LICENSE) (if present) or the project repository. + +Built from [OpenProps](https://open-props.style/) values (MIT) — rounded to native oklch colors for ASW v0.1. diff --git a/package.json b/package.json index 244bfc6..aeed59f 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,7 @@ "private": true, "scripts": { "build": "cat src/tokens.css src/layers/00-reset.css src/layers/02-typography.css src/layers/03-landmarks.css src/layers/04-forms.css src/layers/05-components.css src/layers/06-navigation.css src/layers/07-data-attrs.css src/layers/08-utilities.css src/layers/09-charts.css src/layers/10-chroma.css src/layers/11-layout.css src/layers/12-landing.css > dist/asw.css && postcss dist/asw.css -o dist/asw.min.css --no-map", + "build:min": "postcss dist/asw.css -o dist/asw.min.css --no-map", "build:unminified": "cat src/tokens.css src/layers/00-reset.css src/layers/02-typography.css src/layers/03-landmarks.css src/layers/04-forms.css src/layers/05-components.css src/layers/06-navigation.css src/layers/07-data-attrs.css src/layers/08-utilities.css src/layers/09-charts.css src/layers/10-chroma.css src/layers/11-layout.css src/layers/12-landing.css > dist/asw.css" }, "devDependencies": {