trentuna/asw
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

asw-v01: framework core, native tokens, templates, archive deferral

Browse source
This commit is contained in:
H.M. Murdock 2026-06-07 10:52:31 +02:00
parent 0d1d75a22f
commit 9651dd5515
Signed by: murdock
GPG key ID: ABE295FFEB4571F8
3 changed files with 280 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

228
README.md
View file

@ -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.
> CSS framework for agent-generated web content.
> Semantic HTML. Data attributes. Zero CSS classes.
---
## Link this one file
```html
<link rel="stylesheet" href="dist/asw.css">
```
That's it. Drop the tag in your `<head>`, 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
<!-- Full version — readable in devtools -->
<link rel="stylesheet" href="dist/asw.css">
<!-- Minified version — lighter for production -->
<link rel="stylesheet" href="dist/asw.min.css">
```
---
## 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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>My ASW Page</title>
<link rel="stylesheet" href="dist/asw.css">
</head>
<body>
<nav data-layout="spread">
<a href="#"><strong>Site</strong></a>
<span data-layout="row">
<a href="#">Docs</a>
<a href="#">About</a>
</span>
</nav>
<header data-layout="hero">
<h1>Hello, web</h1>
<p>Semantic HTML, styled by data attributes.</p>
</header>
</body>
</html>
```
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
<section data-layout="row">
<article>Card 1</article>
<article>Card 2</article>
<article>Card 3</article>
</section>
```
### `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.