From 0d1d75a22fbe855f63cc601f695da4a3c07ed0f9 Mon Sep 17 00:00:00 2001 From: Hannibal Smith Date: Sun, 7 Jun 2026 10:50:20 +0200 Subject: [PATCH] asw-v01: 5 reference templates using data-layout and semantic HTML MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - templates/index.html — landing/hero page with feature cards - templates/docs.html — docs layout with sidebar nav, content, and TOC - templates/article.html — long-form prose with code blocks and blockquotes - templates/dashboard.html — stats grid with system status panels - templates/tasks.html — vault-style task tracker with data-task attributes All templates use semantic HTML only, data-layout attributes for structure, zero class= for layout, and link to dist/asw.css. --- templates/article.html | 150 +++++++++++++++++++++++++++++++++ templates/dashboard.html | 124 ++++++++++++++++++++++++++++ templates/docs.html | 173 +++++++++++++++++++++++++++++++++++++++ templates/index.html | 83 +++++++++++++++++++ templates/tasks.html | 126 ++++++++++++++++++++++++++++ 5 files changed, 656 insertions(+) create mode 100644 templates/article.html create mode 100644 templates/dashboard.html create mode 100644 templates/docs.html create mode 100644 templates/index.html create mode 100644 templates/tasks.html diff --git a/templates/article.html b/templates/article.html new file mode 100644 index 0000000..3f7ba81 --- /dev/null +++ b/templates/article.html @@ -0,0 +1,150 @@ + + + + + + Understanding CSS Custom Properties — ASW Blog + + + + + + + + + +
+

+ + by ASW Team + — + 8 min read +

+

Understanding CSS Custom Properties

+

A deep dive into native CSS design tokens, the oklch colour space, and building a token system without preprocessors.

+
+ + +
+ +

Why Custom Properties?

+

CSS custom properties (often called CSS variables) let you store values and reuse them throughout your stylesheet. Unlike preprocessor variables ($ in Sass or Less), custom properties are live — they cascade, can be overridden at any level, and can be changed at runtime.

+ +
+

"Custom properties are to design tokens what functions are to programming — they give you a single source of truth that ripples through the entire system."

+
+ +

When you define a value once as a custom property, every reference to it updates automatically when the property changes. This is the foundation of a maintainable design system.

+ +

The oklch Colour Space

+

Traditional rgb and hsl colour spaces are device-dependent and perceptually uneven. The oklch colour space, introduced in CSS Color Level 4, is designed for human perception — a 10% lightness shift looks like a 10% lightness shift, regardless of the hue.

+ + 
/* Traditional RGB — hard to reason about */
+--accent: #4a6cf7;
+
+/* oklch — perceptually uniform, easy to tweak */
+--accent: oklch(65% 0.15 250);
+ +

The three components of oklch are:

+ + +

Why This Matters for Design Systems

+

Because oklch uses a polar coordinate system (like HSL), you can rotate hues while keeping perceptual lightness constant. This makes generating colour scales, accent colours, and dark mode variants straightforward.

+ + 
:root {
+  --palette-hue: 250;        /* blue-violet */
+  --palette-chroma: 0.15;
+
+  --accent: oklch(65% var(--palette-chroma) var(--palette-hue));
+  --accent-hover: oklch(72% var(--palette-chroma) var(--palette-hue));
+}
+ +

Building a Token System

+

A design token system organises custom properties into semantic layers:

+ +
    +
  1. Primitives — raw values (sizes, colours, fonts)
    2. +
  2. Aliases — semantic names mapped to primitives
    3. +
  3. Component tokens — role-specific values
    4. +
+ +

For example, a spacing scale starts with raw sizes:

+ + 
--size-1: 0.25rem;   /*  4px */
+--size-2: 0.5rem;     /*  8px */
+--size-3: 1rem;       /* 16px */
+ +

Then semantic aliases map those sizes to their roles:

+ + 
--space-1: var(--size-1);  /* tiny gap */
+--space-2: var(--size-2);  /* tight gap */
+--space-4: var(--size-3);  /* standard gap */
+ +

Live Reload in the Browser

+

One of the superpowers of custom properties is live editing. Open your browser's dev tools, change a token value in :root, and watch every element that uses it update in real time.

+ + 
/* Change this in dev tools and see the whole page shift */
+:root {
+  --palette-hue: 200;  /* shift from blue-violet to blue */
+}
+ +

Common Pitfalls

+

Custom properties are powerful, but they come with some gotchas:

+ + + +

Conclusion

+

CSS custom properties, combined with the oklch colour space, give you everything you need for a modern design token system — no preprocessor required. It's more verbose in places, but the trade-off is runtime flexibility, browser-native live editing, and zero build dependencies.

+ +
+

Footnotes

+
    +
  1. The oklch specification is part of CSS Color Module Level 4. Read the spec.
    2. +
  2. Browser support for oklch is excellent — all modern browsers support it as of 2024. Check CanIUse.
    3. +
+
+ +
+ + + + +
+ + + + + + diff --git a/templates/dashboard.html b/templates/dashboard.html new file mode 100644 index 0000000..d30a8da --- /dev/null +++ b/templates/dashboard.html @@ -0,0 +1,124 @@ + + + + + + Dashboard — ASW + + + + + + + + + +
+

Dashboard

+

Project overview for ASW v0.1

+
+ + +
+

Key Metrics

+
+
+ 24 + Commits +
+
+ 5 + Templates +
+
+ 143 + Stars +
+
+ 12 + Open Issues +
+
+ 97% + Uptime +
+
+
+ + +
+ + +
+

System Status

+ +
+ + Build Pipeline + Operational + +
+ +
+ + CDN Distribution + Operational + +
+ +
+ + Documentation + Operational + +
+ +
+ + Package Registry + Degraded + +
+
+ + +
+

Recent Activity

+ +
+

Token system — 2h ago

+

Replaced OpenProps with native oklch custom properties.

+
+ +
+

Flexbox layouts — 1h ago

+

Added data-layout flexbox primitives with responsive breakpoints.

+
+ +
+

Reference templates — now

+

Building 5 template pages demonstrating the framework.

+
+
+ +
+ + + + + + diff --git a/templates/docs.html b/templates/docs.html new file mode 100644 index 0000000..eb3f104 --- /dev/null +++ b/templates/docs.html @@ -0,0 +1,173 @@ + + + + + + Documentation — ASW + + + + + + + + + +
+ + + + + +
+

Documentation

+ +
+

Installation

+

Install ASW via npm:

+

npm install @agentic-semantic-web/asw

+

Or link the built CSS directly in your HTML:

+

<link rel="stylesheet" href="dist/asw.css">

+
+ +
+

Quick Start

+

ASW is built on two rules:

+
    +
  1. Use semantic HTML elements for structure.
    2. +
  2. Use data-layout attributes for layout.
    3. +
+

No classes. No utility frameworks. No naming conventions.

+
+ +
+

Semantic HTML

+

Every page is built from meaningful landmarks:

+
    +
  • <nav> — navigation blocks
    • +
  • <main> — primary content
    • +
  • <article> — self-contained content
    • +
  • <section> — grouped content
    • +
  • <header> — introductory content
    • +
  • <footer> — closing metadata
    • +
  • <aside> — complementary content
    • +
+
+ +
+

Data Layout

+

Apply layout with data-layout attributes on any element:

+
    +
  • data-layout="row" — horizontal flex with wrap
    • +
  • data-layout="col" — vertical flex
    • +
  • data-layout="stack" — vertical flex with larger gap
    • +
  • data-layout="spread" — space-between distribution
    • +
  • data-layout="center" — centred column
    • +
  • data-layout="card-grid" — responsive card grid
    • +
+
+ +
+

Token System

+

ASW uses native CSS custom properties (oklch color space) for all design tokens:

+ + + + + + + + + + + + + +
TokenPurpose
--surfacePage background
--textPrimary text colour
--accentInteractive accent
--space-4Standard spacing unit (1rem)
+
+ +
+

Flexbox Primitives

+

All flexbox layouts collapse to stacked at 640px viewport width via @media (--compact).

+

<div data-layout="spread">...</div>

+
+ +
+ + + +
+ + + + +
+ + + + + + diff --git a/templates/index.html b/templates/index.html new file mode 100644 index 0000000..2a6c2e8 --- /dev/null +++ b/templates/index.html @@ -0,0 +1,83 @@ + + + + + + ASW — Agentic Semantic Web + + + + + + + + + +
+

Agentic Semantic Web

+

A CSS framework for agent-generated web content.

+

Semantic HTML. Data attributes. Zero layout classes.

+ +

npm install @agentic-semantic-web/asw

+ + +
+ + +
+

Why ASW?

+ +
+
+

Semantic by Default

+

Use meaningful HTML elements — <nav>, <main>, <article>, <section> — instead of generic <div> soup.

+
+ +
+

Data Attributes for Layout

+

Style with data-layout attributes, not CSS classes. Your markup describes its own structure.

+
+ +
+

Zero Class Dependencies

+

No utility class soup. No grid frameworks. No naming conventions to memorise.

+
+ +
+

Built for Agents

+

Designed from the ground up for LLM-generated HTML — the rules are simple enough for any agent to follow.

+
+
+
+ + +
+

Ready to build?

+

Link one CSS file, use semantic HTML and data-layout attributes.

+ +
+ + + + + + diff --git a/templates/tasks.html b/templates/tasks.html new file mode 100644 index 0000000..4925baf --- /dev/null +++ b/templates/tasks.html @@ -0,0 +1,126 @@ + + + + + + Tasks — ASW + + + + + + + + + +
+

Tasks

+ +
+ + +
+ + +
+
+

Token System — Replace OpenProps with Native CSS

+ Done +
+

Replace OpenProps imports with native CSS custom properties using the oklch colour space. All ~40 tokens converted.

+
+ Assigned to: Vigo + Completed June 7, 2026 +
+
+ + +
+
+

Archive Deferred Content

+ Done +
+

Move packs/, site/, lab/ and legacy SSI examples into archive/ directory. Nothing deleted from git.

+
+ Assigned to: Vigo + Completed June 7, 2026 +
+
+ + +
+
+

Flexbox Layout System

+ Done +
+

Add data-layout="row/col/stack/spread/center" flexbox rules with responsive wrapping at 640px.

+
+ Assigned to: Vigo + Completed June 7, 2026 +
+
+ + +
+
+

Build 5 Working Templates

+ In Progress +
+

Create index, docs, article, dashboard, and tasks templates using semantic HTML and data-layout attributes.

+
+ Assigned to: Hannibal + Updated June 7, 2026 +
+
+ + +
+
+

Release v0.1 Preparation

+ Pending +
+

Rewrite README for 0.1, create CHANGELOG.md, final build, tag v0.1.

+
+ Assigned to: Vigo + Depends on: T4 +
+
+ + +
+
+

Documentation Review

+ In Review +
+

Peer review of all template documentation and usage guides.

+
+ Assigned to: Team + Needs 2 approvals +
+
+ +
+ + + + + +