Reference on ASW — Agentic Semantic Web

Introduction

Thu, 09 Apr 2026 00:00:00 +0000

What is ASW?

Agentic Semantic Web (ASW) is a standalone CSS framework designed for content generated by AI agents. It makes semantic HTML look good without requiring class names, utility tokens, or build steps.

One <link> tag. That is the entire installation.

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

Why semantic HTML?

AI agents write HTML naturally — <article>, <section>, <nav>, <aside>, <figure>. They do not reliably reproduce class-based systems like Tailwind or Bootstrap without hallucinating class names or producing inconsistent output.

Token System

Thu, 09 Apr 2026 00:00:00 +0000

Overview

ASW uses a three-layer token hierarchy built on Open Props. Each layer is additive: base palette → semantic aliases → component-specific values.

Open Props palette   →   ASW semantic aliases   →   component tokens
--gray-5                  --text-2                    --input-border
--green-5                 --accent                    --callout-info
--blue-5                  --link                      --task-done

No layer can break the others. Override a semantic alias, and every component that references it updates.

Layer 1 — Open Props palette

ASW inlines the Open Props token set directly — no CDN dependency. The full color palette (--gray-0 through --gray-15, plus hue families), spacing scale, font stacks, and easing curves are all available.

Components

Thu, 09 Apr 2026 00:00:00 +0000

Callouts

Inline advisory blocks. The data-callout attribute sets the semantic type; the stylesheet handles colour, icon, and layout.

<div data-callout="tip">
  <span data-callout-title>Tip</span>
  <p>Use <code>data-callout</code> instead of inventing class names.</p>
</div>

<div data-callout="warning">
  <span data-callout-title>Warning</span>
  <p>Overriding Open Props palette tokens breaks theming.</p>
</div>

<div data-callout="error">
  <span data-callout-title>Error</span>
  <p>This file exceeds the token budget.</p>
</div>

<div data-callout="note">
  <span data-callout-title>Note</span>
  <p>Both <code>note</code> and <code>info</code> are valid values.</p>
</div>

In Hugo, use the callout shortcode:

…

Valid values: tip, note, info, warning, error.

Navigation

Thu, 09 Apr 2026 00:00:00 +0000

ASW provides two navigation components for orientation and workflow sequencing: breadcrumb for hierarchical location, and steps for pipeline progress.

Shows the current page’s position in a site hierarchy. Uses <nav data-role="breadcrumb"> with a plain <ol> — no classes needed.

<nav data-role="breadcrumb" aria-label="breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/docs/">Docs</a></li>
    <li aria-current="page">Token System</li>
  </ol>
</nav>

Separators (/) are drawn by CSS ::before — no markup needed.
The current page item gets aria-current="page". It renders as plain text (no link), full colour, slightly bolder.
Wraps on narrow viewports.

Longer trail

<nav data-role="breadcrumb" aria-label="breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/docs/">Docs</a></li>
    <li><a href="/docs/components/">Components</a></li>
    <li aria-current="page">Navigation</li>
  </ol>
</nav>

Steps

A horizontal workflow sequence. Apply data-role="steps" to an <ol>. Each <li> takes a data-status attribute.

Layouts

Thu, 09 Apr 2026 00:00:00 +0000

data-layout on any element activates a layout pattern. No classes needed.

Docs layout

Three-column scaffold: sidebar, content, TOC. Source order: left <aside> → content → right <aside data-toc>.

<div data-layout="docs">
  <aside>
    <nav data-nav="sidebar" aria-label="Docs">
      <small>Getting started</small>
      <ul>
        <li><a href="/docs/getting-started/introduction/" aria-current="page">Introduction</a></li>
        <li><a href="/docs/core/tokens/">Token System</a></li>
      </ul>
    </nav>
  </aside>

  <article>
    <h1>Page title</h1>
    <p>Content goes here.</p>
  </article>

  <aside data-toc>
    <small>On this page</small>
    <nav>
      <ul>
        <li><a href="#section">Section</a></li>
      </ul>
    </nav>
  </aside>
</div>

The right TOC hides below ~1280px. The left sidebar hides below ~768px.

Utilities

Sat, 11 Apr 2026 00:00:00 +0000

ASW provides a small set of utility attributes for inline adjustments. Rather than class names, these use data-* attributes to stay in the semantic-HTML spirit of the framework.

Inline Demo

data-text="mono" — monospace font

data-text="dim" — reduced opacity / muted

data-text="accent" — accent colour

data-text="small" — smaller font size

Vocabulary

Sat, 11 Apr 2026 00:00:00 +0000

Every data-* attribute that ASW recognises is listed here. This is the authoritative vocabulary — anything not on this list has no built-in style effect.

Inline Demo

Attribute	Values	Effect
`data-layout`	docs, prose, wide	Page layout variant
`data-callout`	note, tip, warning, error	Callout block style
`data-task`	done, todo, wip, blocked	Task list item state
`data-status`	active, sleeping, blocked	Status badge
`data-text`	mono, dim, accent, small	Inline text variant
`data-variant`	secondary, danger	Button style variant
`data-wikilink`	(any)	Internal wiki link styling

Accordion & Dialog

Thu, 09 Apr 2026 00:00:00 +0000

Accordion

Style native <details>/<summary> elements. No JS needed — the browser handles open/close state.

<details>
  <summary>What is agentic HTML?</summary>
  <p>Agentic HTML is structured markup generated by AI agents — semantic, predictable, and styled without classes.</p>
</details>

Live example:

What is agentic HTML?

Agentic HTML is structured markup generated by AI agents — semantic, predictable, and styled without classes.

Why no classes?

Language models reliably produce semantic HTML. Class names require memorisation and drift. Data-attributes are explicit and grep-friendly.

Data Attributes

Thu, 09 Apr 2026 00:00:00 +0000

ASW uses data-* attributes as its entire styling API. No class names are needed. Agents can write semantic HTML with intent expressed as data attributes; the stylesheet does the rest.

data-role

Semantic role indicator. Applied to the element that is the component.

Value	Element	Description
`primary`	`<a>`	Filled CTA button
`secondary`	`<a>`	Outlined CTA button
`card`	any	Card container
`command-box`	`<div>`	Install/command pill with prefix glyph
`status-card`	`<div>`	Bordered status block
`diff`	`<div>`	Inline diff viewer (legacy; prefer `data-diff`)
`log-entry`	any	Single log line, bottom border
`list-item`	any	Minimal padding list item
`prev-next`	`<div>`	Prev/next navigation pair
`tag-cloud`	`<div>`	Tag cluster
`timeline`	`<div>`	Simple left-spine timeline (legacy; prefer `data-layout="timeline"`)

<a href="/docs/" data-role="primary">Read docs →</a>
<a href="/github/" data-role="secondary">Source</a>

<div data-role="command-box">
  <span class="prefix">$</span><!-- .prefix is one of ASW's intentional class exceptions -->
  npm install agentic-css
</div>

data-status

Semantic status state. Renders with mono font and status-appropriate colour.

Reset

Thu, 09 Apr 2026 00:00:00 +0000

ASW’s reset is in src/layers/00-reset.css, ported from Pico CSS v2.1.1 (MIT). It’s an opinionated normalize, not a zero-baseline reset — it corrects browser inconsistencies without stripping all defaults.

What it does

Box-sizing

Every element uses border-box. Padding and border are included in the declared width.

*, *::before, *::after {
  box-sizing: border-box;
  background-repeat: no-repeat;
}

background-repeat: no-repeat prevents accidental tiling on elements that receive a background image.

Document baseline

:where(:root) {
  -webkit-tap-highlight-color: transparent;  /* remove tap flash on mobile */
  text-size-adjust: 100%;                    /* prevent font inflation on mobile */
  text-rendering: optimizeLegibility;
  overflow-wrap: break-word;                 /* wrap long URLs / tokens */
  tab-size: 4;
}

Semantic HTML

Thu, 09 Apr 2026 00:00:00 +0000

ASW’s 02-semantic.css layer styles native HTML elements directly. Write valid semantic HTML; it looks right without adding any attributes or classes.

Typography

Headings

All six heading levels are styled with distinct sizes, weights, and colours drawn from ASW tokens.

<h1>Page Title</h1>
<h2>Section Heading</h2>
<h3>Subsection</h3>
<h4>Group Header</h4>
<h5>LABEL</h5>        <!-- uppercase, spaced -->
<h6>MICRO LABEL</h6>  <!-- uppercase, spaced, smaller -->

h5 and h6 receive text-transform: uppercase and letter-spacing to serve as section labels rather than structural headings. Headings following content elements get extra top margin (--type-space-top) automatically.

Charts

Thu, 09 Apr 2026 00:00:00 +0000

ASW includes a chart layer (06-charts.css) absorbed from Charts.css (MIT), with the class-based API converted to data-attributes. Charts are pure CSS — no JavaScript, no Canvas, no SVG.

The data source is a standard <table>. CSS turns it into a chart.

How data binding works

Each <td> carries a --size CSS custom property via style attribute. This is the one place ASW permits inline styles — style="--size: 0.8" is data injection (a numeric value binding), not presentational styling.

Syntax Highlighting

Thu, 09 Apr 2026 00:00:00 +0000

ASW ships two syntax highlighting systems:

07-chroma.css — Hugo/Chroma class names mapped to Open Props tokens. For Hugo sites.
02-semantic.css (Prism section) — Token overrides for Prism.js. For non-Hugo sites.

Both render with the same token palette: Open Props perceptual colour scale, dark-first with light-mode overrides.

Hugo / Chroma

Hugo uses Chroma to highlight code fences. Chroma emits CSS classes (.k, .s, .c, etc.). 07-chroma.css maps those classes to ASW tokens.

HTML Landmark Elements

Sat, 11 Apr 2026 00:00:00 +0000

The full set: <header>, <nav>, <main>, <article>, <section>, <aside>, <footer>, plus the newer <search>.

Each maps to an implicit ARIA landmark role, which is what makes them meaningful to screen readers and search engines — not just visual styling hooks.

`<header>`

Introductory content for its nearest sectioning ancestor. At the top level of <body> it maps to the banner landmark — the site identity zone. Inside an <article> or <section> it’s just a local header with no landmark role.

Diff

Thu, 09 Apr 2026 00:00:00 +0000

Overview

Use data-diff on a <pre> block to render a structured diff. Child elements carry line-level semantics.

<pre data-diff>
  <span data-line="hunk">@@ -12,7 +12,9 @@</span>
  <span data-line="context"> function greet(name) {</span>
  <span data-line="removed">-  return "Hello " + name;</span>
  <span data-line="added">+  const greeting = `Hello, ${name}!`;</span>
  <span data-line="added">+  return greeting;</span>
  <span data-line="context"> }</span>
</pre>

Line Types

Value	Meaning
`hunk`	Hunk header (`@@ ... @@`) — muted, italic
`context`	Unchanged surrounding line — default text
`removed`	Deleted line — red background, `-` prefix
`added`	New line — green background, `+` prefix

Inline Diffs

For single-value changes in prose, use data-diff directly on <del> and <ins>:

Documentation

Thu, 09 Apr 2026 00:00:00 +0000

ASW is a single-file CSS framework for agent-generated web content. Semantic HTML is the only API. No classes, no build step, no JavaScript required.

Browse the sections in the sidebar, or start with Introduction.

Session Log

Thu, 09 Apr 2026 00:00:00 +0000

Overview

Use data-role="session-log" on an <ol> to render a structured activity or session log. Each <li> is one event.

<ol data-role="session-log">
  <li>
    <time datetime="2026-04-09T08:31:00Z">08:31</time>
    <span data-actor="vigilio">vigilio</span>
    <span data-event="wake">Session started — model claude-sonnet-4-6</span>
  </li>
  <li>
    <time datetime="2026-04-09T08:32:14Z">08:32</time>
    <span data-actor="vigilio">vigilio</span>
    <span data-event="read">Read vault overview and daily note</span>
  </li>
  <li>
    <time datetime="2026-04-09T08:47:00Z">08:47</time>
    <span data-actor="system">system</span>
    <span data-event="commit">Committed: feat(vault): add session-log pattern</span>
  </li>
</ol>

Attributes

Attribute	Element	Meaning
`data-role="session-log"`	`<ol>`	Activates session-log layout
`data-actor`	`<span>`	Who performed the action — styled by value
`data-event`	`<span>`	Event type — `wake`, `read`, `write`, `commit`, `sleep`

Actor Variants

<span data-actor="vigilio">vigilio</span>   <!-- agent — primary colour -->
<span data-actor="ludo">ludo</span>         <!-- operator — accent colour -->
<span data-actor="system">system</span>     <!-- system — muted -->

Compact Form

For dense logs, omit the actor and let timestamp + event carry the entry:

Status

Thu, 09 Apr 2026 00:00:00 +0000

Overview

Use data-status on any element to convey operational state. ASW renders a coloured indicator — no CSS classes required.

<span data-status="online">API Gateway</span>
<span data-status="degraded">Search Index</span>
<span data-status="offline">Legacy Auth</span>
<span data-status="unknown">Webhook Relay</span>

Values

Value	Meaning	Indicator
`online`	Fully operational	Green dot
`degraded`	Reduced capacity or elevated errors	Amber dot
`offline`	Not reachable or deliberately down	Red dot
`unknown`	State not yet determined	Grey dot

Status Dashboard Pattern

Combine with a <dl> for a compact service health panel:

Tasks

Thu, 09 Apr 2026 00:00:00 +0000

Overview

Use data-task on list items to convey task state without CSS classes.

<ul>
  <li data-task="done">Completed item</li>
  <li data-task="wip">Work in progress</li>
  <li data-task="blocked">Blocked item</li>
  <li data-task="todo">Not started</li>
</ul>

States

Value	Meaning
`done`	Completed — green check
`wip`	In progress — amber
`blocked`	Blocked — red
`todo`	Not started — muted

Vault

Thu, 09 Apr 2026 00:00:00 +0000

Wikilinks

Thu, 09 Apr 2026 00:00:00 +0000

Overview

Use data-wikilink on anchor tags to mark links as internal knowledge-graph references.

<a href="/notes/tasks/" data-wikilink>Tasks</a>

Renders with a dotted underline distinguishing it from a regular hyperlink.

ASW Data-Attribute Vocabulary

Wed, 08 Apr 2026 00:00:00 +0000

ASW Data-Attribute Vocabulary

The ASW-Hugo pack emits these data-* attributes in its HTML output.

Attribute	Element	Meaning
`data-callout="note"`	`<aside>`	Note callout block
`data-callout="warning"`	`<aside>`	Warning callout
`data-callout="tip"`	`<aside>`	Tip callout
`data-callout="info"`	`<aside>`	Info callout
`data-wikilink`	`<a>`	Internal vault-style link
`data-role="tag-cloud"`	`<nav>`	Tag navigation
`data-layout="grid"`	`<section>`	Grid layout for list pages
`data-tag`	`<a>`	Tag label on links

All styling comes from asw.css targeting these attributes — no CSS classes required.

Example: Full Page Skeleton

A complete ASW page emitted by the Hugo pack looks like this:

Reference on ASW — Agentic Semantic Web

Introduction

What is ASW?

Why semantic HTML?

Token System

Overview

Layer 1 — Open Props palette

Components

Callouts

Navigation

Breadcrumb

Longer trail

Steps

Layouts

Docs layout

Utilities

Inline Demo

Vocabulary

Inline Demo

Accordion & Dialog

Accordion

Data Attributes

data-role

data-status

Reset

What it does

Box-sizing

Document baseline

Font size

Semantic HTML

Typography

Headings

Charts

How data binding works

Syntax Highlighting

Hugo / Chroma

HTML Landmark Elements

<header>

Diff

Overview

Line Types

Inline Diffs

Documentation

Session Log

Overview

Attributes

Actor Variants

Compact Form

Status

Overview

Values

Status Dashboard Pattern

Tasks

Overview

States

Vault

Wikilinks

Overview

ASW Data-Attribute Vocabulary

ASW Data-Attribute Vocabulary

Example: Full Page Skeleton

`<header>`