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

Port vault section (5 pages) and docs section (11 pages)

Browse source 
- content/vault/: _index.md, diff.md, session.md, status.md, tasks.md, wikilinks.md
- content/docs/: _index.md, introduction, tokens, reset, semantic-html,
  components, data-attributes, navigation, layouts, charts, chroma, accordion-dialog

96 pages build clean (was 36). Docs use sidebar nav + TOC layout.
Vault uses sidebar with section fallback (no vault menu configured yet).
URLs fixed: playground refs → asw.trentuna.com.

Closes: asw#12, asw#9
This commit is contained in:
Vigilio Desto 2026-04-10 18:40:50 +02:00
parent cbe44d845c
commit da1d02ccd1
Signed by: vigilio
GPG key ID: 159D6AD58C8E55E9
19 changed files with 2462 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

11
content/docs/_index.md Normal file
View file

@ -0,0 +1,11 @@
---
title: "Documentation"
description: "Reference documentation for the Agentic Semantic Web framework."
date: 2026-04-09
tags: ["reference", "documentation"]
---
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](/docs/introduction/).

117
content/docs/accordion-dialog.md Normal file
View file

@ -0,0 +1,117 @@
---
title: "Accordion & Dialog"
description: "Native disclosure and modal patterns. No JavaScript required for accordion; dialog uses the native showModal() API."
layout: docs
weight: 45
type: docs
date: 2026-04-09
tags: ["components", "interactive", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Accordion
Style native `<details>`/`<summary>` elements. No JS needed — the browser handles open/close state.
```html
<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:**
<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>
<details>
<summary>Why no classes?</summary>
<p>Language models reliably produce semantic HTML. Class names require memorisation and drift. Data-attributes are explicit and grep-friendly.</p>
</details>
---
## Grouped Accordion
Wrap in `<div data-role="accordion">` for flush connected borders.
```html
<div data-role="accordion">
<details>
<summary>Reset layer</summary>
<p>Normalises browser defaults without imposing opinions.</p>
</details>
<details>
<summary>Token layer</summary>
<p>Open Props foundation plus ASW semantic aliases.</p>
</details>
<details open>
<summary>Components layer</summary>
<p>Buttons, forms, accordion, dialog — all zero-class.</p>
</details>
</div>
```
**Live example:**
<div data-role="accordion">
<details>
<summary>Reset layer</summary>
<p>Normalises browser defaults without imposing opinions.</p>
</details>
<details>
<summary>Token layer</summary>
<p>Open Props foundation plus ASW semantic aliases.</p>
</details>
<details open>
<summary>Components layer</summary>
<p>Buttons, forms, accordion, dialog — all zero-class.</p>
</details>
</div>
---
## Dialog
Native `<dialog>` element. Use `dialog.showModal()` for a modal with backdrop, or `dialog.show()` for a non-modal popover.
```html
<dialog id="demo-dialog">
<header><h2>Confirm action</h2></header>
<p>Are you sure you want to proceed? This cannot be undone.</p>
<footer>
<button onclick="document.getElementById('demo-dialog').close()">Cancel</button>
<button onclick="document.getElementById('demo-dialog').close()">Confirm</button>
</footer>
</dialog>
<button onclick="document.getElementById('demo-dialog').showModal()">Open dialog</button>
```
**Live example:**
<dialog id="demo-dialog">
<header><h2>Confirm action</h2></header>
<p>Are you sure you want to proceed? This cannot be undone.</p>
<footer>
<button onclick="document.getElementById('demo-dialog').close()">Cancel</button>
<button onclick="document.getElementById('demo-dialog').close()">Confirm</button>
</footer>
</dialog>
<button onclick="document.getElementById('demo-dialog').showModal()">Open dialog</button>
---
## Notes
- Accordion uses `:not(nav details)` scoping so nav dropdowns are unaffected.
- Dialog backdrop uses `color-mix()` for transparency — no hardcoded rgba values.
- All spacing uses Open Props / ASW tokens (`--space-*`, `--radius-*`, `--shadow-*`).
- `dialog::backdrop` uses `backdrop-filter: blur(4px)` for frosted glass effect.

217
content/docs/charts.md Normal file
View file

@ -0,0 +1,217 @@
---
title: "Charts"
description: "Data-driven charts from semantic HTML tables using the data-chart attribute vocabulary. Absorbed from Charts.css."
type: docs
weight: 80
date: 2026-04-09
tags: ["charts", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
ASW includes a chart layer (`06-charts.css`) absorbed from [Charts.css](https://chartscss.org/) (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.
```
--size: 0.0 → 0%
--size: 0.5 → 50%
--size: 1.0 → 100%
```
---
## Bar chart
Horizontal bars. Each row is one bar.
```html
<table data-chart="bar">
<caption>Token budget usage</caption>
<tbody>
<tr>
<th scope="row">Wake</th>
<td style="--size: 0.15">15%</td>
</tr>
<tr>
<th scope="row">Research</th>
<td style="--size: 0.62">62%</td>
</tr>
<tr>
<th scope="row">Output</th>
<td style="--size: 0.23">23%</td>
</tr>
</tbody>
</table>
```
---
## Column chart
Vertical bars. Each `<td>` is one column.
```html
<table data-chart="column">
<caption>Sessions per day</caption>
<tbody>
<tr>
<td style="--size: 0.4">Mon</td>
<td style="--size: 0.7">Tue</td>
<td style="--size: 0.55">Wed</td>
<td style="--size: 0.9">Thu</td>
<td style="--size: 0.3">Fri</td>
</tr>
</tbody>
</table>
```
---
## Line chart
Connects data points with a line. Requires two `<td>` values per point: `--start` and `--end`.
```html
<table data-chart="line">
<caption>Uptime trend</caption>
<tbody>
<tr>
<td style="--start: 0.6; --end: 0.75"></td>
<td style="--start: 0.75; --end: 0.8"></td>
<td style="--start: 0.8; --end: 0.95"></td>
<td style="--start: 0.95; --end: 0.98"></td>
</tr>
</tbody>
</table>
```
---
## Area chart
Like a line chart but with the area beneath filled.
```html
<table data-chart="area">
<caption>Memory usage</caption>
<tbody>
<tr>
<td style="--start: 0.2; --end: 0.35"></td>
<td style="--start: 0.35; --end: 0.5"></td>
<td style="--start: 0.5; --end: 0.4"></td>
<td style="--start: 0.4; --end: 0.6"></td>
</tr>
</tbody>
</table>
```
---
## Axis labels
Add `data-chart-labels` to show `<thead>` column labels as axis labels.
```html
<table data-chart="column" data-chart-labels>
<thead>
<tr>
<th scope="col">Mon</th>
<th scope="col">Tue</th>
<th scope="col">Wed</th>
</tr>
</thead>
<tbody>
<tr>
<td style="--size: 0.4">40%</td>
<td style="--size: 0.7">70%</td>
<td style="--size: 0.55">55%</td>
</tr>
</tbody>
</table>
```
---
## Bar spacing
Control gap between bars with `data-chart-spacing="1"` through `"5"` (default is `2`).
```html
<table data-chart="bar" data-chart-spacing="4">
...
</table>
```
---
## Stacked charts
Multi-dataset mode. Each `<tr>` in `<tbody>` becomes a dataset (one colour per row).
```html
<table data-chart="column" data-chart-stacked>
<caption>Token usage by phase</caption>
<tbody>
<tr style="--color: var(--accent)">
<td style="--size: 0.3"></td>
<td style="--size: 0.4"></td>
<td style="--size: 0.25"></td>
</tr>
<tr style="--color: var(--accent-blue)">
<td style="--size: 0.2"></td>
<td style="--size: 0.15"></td>
<td style="--size: 0.3"></td>
</tr>
</tbody>
</table>
```
---
## Custom colours
Override the default colour cycle with `style="--color: ..."` on any `<tr>`.
```html
<tr style="--color: var(--accent-red)">
<td style="--size: 0.85">Error rate</td>
</tr>
```
Default colour cycle (8 slots): accent → blue → orange → red → purple → cyan → pink → teal.
---
## Customising chart dimensions
Override chart size tokens on the `[data-chart]` element:
```html
<table data-chart="column" style="
--chart-height: 300px;
--chart-bar-size: 3rem;
--chart-gap: 8px;
">
```
| Token | Default | Description |
|-------|---------|-------------|
| `--chart-height` | `200px` | Column chart area height |
| `--chart-bar-size` | `2rem` | Column bar width / bar chart bar height |
| `--chart-gap` | `6px` | Gap between data points |
---
## Related
- [Token System](/docs/tokens/) — colour tokens used by the chart colour cycle (`--accent`, `--accent-blue`, etc.)
- [Data Attributes](/docs/data-attributes/) — the broader `data-*` vocabulary of which `data-chart` is a part

155
content/docs/chroma.md Normal file
View file

@ -0,0 +1,155 @@
---
title: "Syntax Highlighting"
description: "How ASW's chroma layer provides syntax highlighting for Hugo and how to use Prism.js as an alternative."
type: docs
weight: 90
date: 2026-04-09
tags: ["syntax-highlighting", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
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](https://github.com/alecthomas/chroma) to highlight code fences. Chroma emits CSS classes (`.k`, `.s`, `.c`, etc.). `07-chroma.css` maps those classes to ASW tokens.
### Setup
In `hugo.toml` (or `config.toml`):
```toml
[markup.highlight]
noClasses = false # emit class names, not inline styles
codeFences = true
lineNos = false
```
Then include `agentic.css` (which bundles `07-chroma.css`). No separate highlight stylesheet needed.
### Usage
Standard fenced code blocks in Markdown:
````markdown
```python
def greet(name: str) -> str:
return f"Hello, {name}"
```
````
````markdown
```javascript
const greet = (name) => `Hello, ${name}`;
```
````
### Token colour mapping
| Token class | Colour token | Example |
|------------|-------------|---------|
| `.k` keywords | `--violet-4` | `def`, `return`, `if` |
| `.s` strings | `--green-4` | `"hello"`, `'world'` |
| `.c` comments | `--gray-5` italic | `# comment` |
| `.n` names | `--blue-3` | identifiers |
| `.mi` integers | `--orange-4` | `42`, `0xff` |
| `.mf` floats | `--orange-3` | `3.14` |
| `.nb` builtins | `--cyan-4` | `print`, `len` |
| `.nf` functions | `--blue-4` | function names |
| `.nc` classes | `--yellow-3` | class names |
| `.o` operators | body colour | `+`, `=`, `->` |
| `.p` punctuation | muted | `(`, `)`, `,` |
| `.err` errors | `--red-4` | parse errors |
Light mode swaps all tokens to their darker counterparts (e.g. `--green-4` → `--green-8`).
### Wrapper
Chroma wraps output in `<div class="highlight"><pre class="chroma"><code>`. ASW styles `.chroma` as a block with `var(--surface-2)` background and rounded corners.
```css
.chroma {
background: var(--surface-2);
border-radius: var(--radius-2);
overflow-x: auto;
}
```
---
## Prism.js (non-Hugo)
For sites not using Hugo, ASW's `02-semantic.css` includes token overrides for [Prism.js](https://prismjs.com/).
### Setup
Load Prism from CDN:
```html
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-core.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/autoloader/prism-autoloader.min.js"></script>
```
No Prism theme stylesheet needed — ASW overrides the colours.
### Usage
```html
<pre><code class="language-css">:root {
--accent: var(--green-5);
--surface: var(--gray-15);
}</code></pre>
<pre><code class="language-html"><div data-layout="hero">
<h1>Hello</h1>
</div></code></pre>
```
Prism auto-detects the language from the `language-*` class and highlights on load.
### Token mapping (Prism)
| Token class | Colour | Example |
|------------|--------|---------|
| `.token.keyword` | `--blue-4` | `const`, `return` |
| `.token.string` | `--green-4` | `"text"` |
| `.token.comment` | `--gray-6` italic | `// comment` |
| `.token.number` | `--orange-4` | `42` |
| `.token.function` | `--cyan-4` | function names |
| `.token.class-name` | `--cyan-4` | class names |
| `.token.tag` | `--red-4` | HTML tags |
| `.token.attr-name` | `--yellow-4` | `href`, `data-role` |
| `.token.attr-value` | `--green-4` | attribute values |
| `.token.selector` | `--teal-4` | CSS selectors |
| `.token.property` | `--blue-5` | CSS properties |
---
## Choosing between the two
| | Chroma | Prism |
|--|--------|-------|
| **Requires** | Hugo | JavaScript |
| **Languages** | 200+ (server-side) | 200+ (lazy-loaded) |
| **Build step** | No (Hugo handles it) | No (CDN) |
| **Output** | Static HTML | Dynamic (runtime) |
| **ASW layer** | `07-chroma.css` | `02-semantic.css` |
Use Chroma for Hugo sites. Use Prism for everything else.
---
## Related
- [Token System](/docs/tokens/) — the Open Props colour tokens that the highlight palette maps to
- [Semantic HTML](/docs/semantic-html/) — how `<pre>` and `<code>` are styled at the element level

222
content/docs/components.md Normal file
View file

@ -0,0 +1,222 @@
---
title: "Components"
description: "ASW's data-attribute vocabulary — callouts, tasks, session blocks, wikilinks, and layout primitives."
type: docs
weight: 30
date: 2026-04-09
tags: ["components", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Callouts
Inline advisory blocks. The `data-callout` attribute sets the semantic type; the stylesheet handles colour, icon, and layout.
```html
<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>
```
{{< callout tip >}}
In Hugo, use the `callout` shortcode: `{{</* callout tip */>}}...{{</* /callout */>}}`
{{< /callout >}}
Valid values: `tip`, `note`, `info`, `warning`, `error`.
---
## Tasks
Render task lists with semantic state. Agents write task lists naturally; `data-task` on the `<li>` adds the visual state indicator.
```html
<ul>
<li data-task="done">Token layer integrated</li>
<li data-task="done">Docs site taxonomy wired</li>
<li data-task="wip">Hugo layouts — in progress</li>
<li data-task="blocked">Deploy — waiting on DNS</li>
<li data-task="todo">Vocabulary retirement pass</li>
</ul>
```
Valid values: `done`, `wip`, `blocked`, `todo`.
---
## Session blocks
Mark a block as a session record with `data-session`. Optional `data-mode` indicates autonomous vs. interactive sessions.
```html
<section data-session data-mode="autonomous">
<header>
<h3>Session 2847</h3>
<p data-text="dim">2026-04-02 · 31 min · claude-sonnet-4-6</p>
</header>
<ul>
<li data-task="done">Vault token layer</li>
<li data-task="wip">Paper layout</li>
</ul>
<div data-callout="note">
<span data-callout-title>Handoff</span>
<p>Next session: harden paper/single.html styles into agentic.css.</p>
</div>
</section>
```
---
## Wikilinks
Internal knowledge-graph links. `data-wikilink` on an anchor renders it with a dotted underline to distinguish it from a regular hyperlink.
```html
<a href="/vault/tasks/" data-wikilink>Tasks</a>
```
In Hugo, use the `wikilink` shortcode:
```
{{</* wikilink "Tasks" "/vault/tasks/" */>}}
```
---
## Redacted content
Sensitive values rendered as black bars. Optional hover-reveal.
```html
<span data-redacted>API key: sk-ant-...</span>
<!-- Hover to reveal -->
<span data-redacted data-redacted-reveal>classified content</span>
```
---
## Layout primitives
### Grid
```html
<!-- Two columns, responsive stack below 600px -->
<div data-layout="grid-2">
<article>Left</article>
<article>Right</article>
</div>
<!-- Three columns, responsive stack below 768px -->
<div data-layout="grid-3">
<article>One</article>
<article>Two</article>
<article>Three</article>
</div>
<!-- Auto-fill card grid, minmax(280px, 1fr) -->
<div data-layout="card-grid">
<article>Card A</article>
<article>Card B</article>
<article>Card C</article>
</div>
```
### Stats row
```html
<div data-layout="stats">
<div>
<span data-stat="value">2847</span>
<span data-stat="label">Sessions</span>
</div>
<div>
<span data-stat="value">99.8%</span>
<span data-stat="label">Uptime</span>
</div>
</div>
```
### Docs layout
Three-column sidebar scaffold. Source order matters: left aside → article → right aside.
```html
<div data-layout="docs">
<aside>
<nav aria-label="Documentation" data-nav="sidebar">
<small>Section</small>
<ul>
<li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
<li><a href="/docs/tokens/">Token System</a></li>
</ul>
</nav>
</aside>
<article>
<!-- Main content -->
</article>
<aside data-toc>
<small>On this page</small>
<nav>
<ul>
<li><a href="#callouts">Callouts</a></li>
</ul>
</nav>
</aside>
</div>
```
---
## Text utilities
```html
<p data-text="dim">Muted — var(--text-3)</p>
<p data-text="accent">Accent colour</p>
<span data-text="eyebrow">SECTION LABEL</span>
<span data-text="small">Fine print</span>
```
---
## CTA links
```html
<a href="/docs/introduction/" data-role="primary">Get started →</a>
<a href="/docs/" data-role="secondary">Documentation</a>
```
---
## Badge
Icon or token pill. Used by the landing page pillars; also useful inline.
```html
<span data-badge>&lt;/&gt;</span>
<span data-badge>data=</span>
<span data-badge>:root</span>
```

362
content/docs/data-attributes.md Normal file
View file

@ -0,0 +1,362 @@
---
title: "Data Attributes"
description: "Complete reference for ASW's data-attribute vocabulary — roles, states, text modifiers, nav, and agentic-specific patterns."
type: docs
weight: 50
date: 2026-04-09
tags: ["data-attributes", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
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"`) |
```html
<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.
| Value | Colour | Use |
|-------|--------|-----|
| `awake` | accent (green) | Active, running |
| `sleeping` | muted, italic | Idle, paused |
| `blocked` | red | Waiting, error state |
| `danger` | red | Critical state |
| `warning` | orange | Caution |
| `unknown` | dim | Indeterminate |
```html
<span data-status="awake">online</span>
<span data-status="blocked">waiting on DNS</span>
<span data-status="sleeping">idle since 03:00</span>
```
---
## data-task
Task list item with state glyph. Apply to `<li>` elements.
| Value | Glyph | Colour |
|-------|-------|--------|
| `todo` | ○ | orange |
| `done` | ● | accent |
| `blocked` | ◐ | red |
```html
<ul>
<li data-task="done">Deploy nginx config</li>
<li data-task="todo">Update DNS records</li>
<li data-task="blocked">TLS cert — waiting on propagation</li>
</ul>
```
---
## data-callout
Advisory block with left border accent and optional title.
| Value | Border colour |
|-------|--------------|
| *(default)* | blue |
| `tip` | accent (green) |
| `warning` | orange |
| `error` | red |
```html
<div data-callout="tip">
<span data-callout-title>Tip</span>
<p>Use data attributes instead of class names.</p>
</div>
<div data-callout="warning">
<span data-callout-title>Warning</span>
<p>This resets the token cascade.</p>
</div>
```
---
## data-text
Text modifier. Supports multiple space-separated values.
| Value | Effect |
|-------|--------|
| `dim` | `var(--text-3)` — muted |
| `accent` | `var(--accent)` — green accent |
| `eyebrow` | mono, uppercase, spaced — section label |
| `small` | `var(--text-sm)` |
| `mono` | monospace font |
| `tagline` | larger, lighter — subtitle treatment |
```html
<p data-text="eyebrow">Getting started</p>
<h1>Token System</h1>
<p data-text="tagline">How the custom property hierarchy is structured.</p>
<p data-text="dim small">Last updated 2026-04-10</p>
<code data-text="mono accent">--accent</code>
```
---
## data-layout
Layout pattern. See [Layouts](/docs/layouts/) for the full reference.
Common values: `docs`, `hero`, `install`, `actions`, `grid-2`, `grid-3`, `card-grid`, `stats`, `prose`, `fluid`, `timeline`, `report`.
---
## data-nav
Navigation variant. Applied to `<nav>` elements.
| Value | Description |
|-------|-------------|
| `sidebar` | Vertical nav list, no pipe separators |
| `toc` | TOC nav, compact, left-border active indicator |
```html
<nav data-nav="sidebar" aria-label="Documentation">
<ul>
<li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
<li><a href="/docs/tokens/">Token System</a></li>
</ul>
</nav>
```
---
## data-subnav
Inline breadcrumb-style section nav. Slash-separated. `aria-current="page"` marks the active item.
```html
<nav data-subnav>
<a href="/vigilio/">index</a>
<a href="/vigilio/now">now</a>
<a href="/vigilio/status" aria-current="page">status</a>
</nav>
```
---
## data-tooltip / data-tooltip-position
CSS-only tooltip on hover and focus. No JavaScript.
```html
<span data-tooltip="Explained here">term</span>
<!-- Bottom placement -->
<span data-tooltip="Below the element" data-tooltip-position="bottom">term</span>
```
Tooltip content comes from the attribute value. Max-width is `var(--tooltip-max-width)`.
---
## data-badge
Inline mono pill. Used for token labels, version indicators, or icon tags.
```html
<span data-badge>&lt;/&gt;</span>
<span data-badge>v2.1</span>
<span data-badge>data=</span>
```
---
## data-diff / data-diff-line / data-diff-file
Semantic diff viewer. Renders a code diff with standard +/- gutter markers.
```html
<div data-diff>
<span data-diff-file>src/tokens.css</span>
<span data-diff-line="hunk">@@ -12,6 +12,8 @@</span>
<span data-diff-line="context"> --text: var(--gray-1);</span>
<span data-diff-line="removed"> --accent: var(--green-5);</span>
<span data-diff-line="added"> --accent: var(--green-4);</span>
<span data-diff-line="added"> --accent-hover: var(--green-3);</span>
</div>
```
---
## data-session / data-mode
Session metadata block. Used to render agent session records.
```html
<section data-session data-mode="autonomous">
<header>
<h3>Session 2847</h3>
<p data-text="dim small">2026-04-10 · 28 min · claude-sonnet-4-6</p>
</header>
<ul>
<li data-task="done">Token layer audit</li>
<li data-task="todo">Deploy docs site</li>
</ul>
</section>
```
`data-mode` values: `autonomous` (blue), `interactive` (accent).
---
## data-wikilink / data-unresolved
Knowledge-graph link style. Dotted underline distinguishes internal wiki links from standard hyperlinks.
```html
<a href="/vault/sessions/" data-wikilink>Sessions</a>
<!-- Unresolved — link target doesn't exist yet -->
<a href="#" data-wikilink data-unresolved>Missing Note</a>
```
---
## data-tag / data-hash
Inline taxonomy labels.
```html
<a href="/tags/agentic/" data-tag>agentic</a>
<span data-hash>a3f9c12</span>
```
`data-tag` prepends a `#` character. `data-hash` renders in mono with tight letter-spacing.
---
## data-redacted
Privacy-aware redaction. Renders content as a black bar. Assistive technology should use `aria-label` for a screen-reader replacement.
```html
<!-- Full redaction -->
<span data-redacted aria-label="redacted">sk-ant-abc123</span>
<!-- Hover to reveal -->
<span data-redacted="reveal" aria-label="classified content">classified</span>
<!-- Shows [REDACTED] label, hides children -->
<span data-redacted="label" aria-label="API key">sk-ant-abc123</span>
```
---
## ai-disclosure
Marks AI content provenance with a left border indicator.
| Value | Border |
|-------|--------|
| `ai-generated` | subtle accent |
| `ai-assisted` | lighter accent |
| `autonomous` | full accent |
| `mixed` | amber |
```html
<section ai-disclosure="autonomous">
<p>This section was written entirely by an autonomous agent.</p>
</section>
```
Add `data-show-disclosure` to render an inline `[autonomous]` badge after the content.
---
## data-reading-progress
CSS-only scroll progress bar. Apply to `<body>` or any scrolling container. Uses `animation-timeline: scroll()` — Chrome 115+, Firefox 110+.
```html
<body data-reading-progress>
```
Renders a thin accent-colored bar fixed to the top of the viewport.
---
## data-visible
Responsive visibility control.
| Value | Effect |
|-------|--------|
| `desktop` | Hidden on mobile |
| `mobile` | Hidden on desktop |
```html
<span data-visible="desktop">Full label</span>
<span data-visible="mobile">Short</span>
```
---
## data-abstract / data-byline / data-section
Document metadata patterns for structured article content.
```html
<article>
<header>
<h1>Title</h1>
<p data-byline>By Vigilio Desto · 2026-04-10</p>
<p data-abstract>A concise summary of the article's argument and scope.</p>
</header>
<section data-section>
<h2 data-section-header>Introduction</h2>
<p>Body content.</p>
</section>
</article>
```
---
## Related
- [Layouts](/docs/layouts/) — `data-layout` values in full
- [Semantic HTML](/docs/semantic-html/) — how plain elements are styled without attributes
- [Components](/docs/components/) — callouts, tasks, and session blocks in detail

96
content/docs/introduction.md Normal file
View file

@ -0,0 +1,96 @@
---
title: "Introduction"
description: "What ASW is, why it exists, and how to drop it into any project."
type: docs
weight: 10
date: 2026-04-09
tags: ["introduction", "getting-started", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## 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.
```html
<link rel="stylesheet" href="agentic.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.
ASW meets agents where they are: structure conveys intent, and the stylesheet reads that structure.
```html
<!-- This is a card. No class needed. -->
<article>
<header>
<h3>Session 2847</h3>
<p data-text="dim">autonomous · 2026-04-02</p>
</header>
<p>Work completed this session.</p>
</article>
```
## Installation
Copy `agentic.css` to your project and link it:
```bash
cp agentic.css static/css/agentic.css
```
```html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="/css/agentic.css">
<title>My Site</title>
</head>
<body>
<!-- Your semantic HTML here -->
</body>
</html>
```
No npm. No PostCSS. No configuration files.
## Hugo integration
The ASW-Hugo pack (this theme) maps Hugo's Markdown output to ASW semantic HTML automatically. Drop the theme into any Hugo project:
```bash
ln -s /path/to/agentic-semantic-web/packs/hugo themes/asw-hugo
```
```toml
# hugo.toml
theme = "asw-hugo"
[markup.tableOfContents]
startLevel = 2
endLevel = 3
ordered = false
```
## What you get
| Feature | How |
|---------|-----|
| Cards | `<article>` |
| Navigation | `<nav>` |
| Sidebar | `<aside>` in `data-layout="docs"` |
| Callouts | `<div data-callout="tip">` |
| Task lists | `<li data-task="done">` |
| Code blocks | `<pre><code>` with Chroma highlighting |
| Tables | `<table>` — striped, bordered automatically |
| Dark mode | System preference via `prefers-color-scheme` |
| Theming | Override `--accent` and `--gray-hue` in `:root` |

247
content/docs/layouts.md Normal file
View file

@ -0,0 +1,247 @@
---
title: "Layouts"
description: "All data-layout values and how to use them — docs scaffold, grids, hero, prose, timeline, and more."
type: docs
weight: 40
date: 2026-04-09
tags: ["layouts", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
`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>`.
```html
<div data-layout="docs">
<aside>
<nav data-nav="sidebar" aria-label="Docs">
<small>Getting started</small>
<ul>
<li><a href="/docs/introduction/" aria-current="page">Introduction</a></li>
<li><a href="/docs/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.
---
## Hero
Landing page header block. Centers content, adds vertical padding, draws a bottom border.
```html
<header data-layout="hero">
<h1>Agentic Semantic Web</h1>
<p>CSS for agent-generated content.</p>
<p data-layout="install"><code>@import "agentic.css"</code></p>
</header>
```
### Install pill
`data-layout="install"` on a `<p>` or `<div>` renders an inline monospace pill — intended for single-line install commands inside a hero.
---
## Actions row
CTA button row, centered, wraps on small screens.
```html
<nav data-layout="actions">
<a href="/docs/introduction/" data-role="primary">Get started →</a>
<a href="https://github.com/..." data-role="secondary">GitHub</a>
</nav>
```
---
## Grid layouts
### Two columns
```html
<div data-layout="grid-2">
<article>Left column</article>
<article>Right column</article>
</div>
```
Stacks to one column below ~768px.
### Three columns
```html
<div data-layout="grid-3">
<article>One</article>
<article>Two</article>
<article>Three</article>
</div>
```
Stacks to one column below ~768px.
### Card grid
Auto-fill, responsive. Columns fill to a minimum of `--card-min-width` (default: `280px`).
```html
<div data-layout="card-grid">
<article>Card A</article>
<article>Card B</article>
<article>Card C</article>
</div>
```
---
## Stats row
Horizontal stat display. Wraps responsively.
```html
<div data-layout="stats">
<div>
<span data-stat="value">2,847</span>
<span data-stat="label">Sessions</span>
</div>
<div>
<span data-stat="value">99.8%</span>
<span data-stat="label">Uptime</span>
</div>
<div>
<span data-stat="value">14</span>
<span data-stat="label">Projects</span>
</div>
</div>
```
---
## Prose
Constrains width to `65ch` for comfortable reading. Apply to `<main>` or any block.
```html
<main data-layout="prose">
<h1>Article title</h1>
<p>Long-form content at a comfortable reading width.</p>
</main>
```
---
## Fluid
Removes the max-width constraint from `<main>`. Use for full-bleed layouts.
```html
<main data-layout="fluid">
<!-- Full-width content -->
</main>
```
---
## Timeline
Vertical chronological list with a spine line and accent dots.
```html
<ol data-layout="timeline">
<li>
<time>2026-04-10</time>
<article>
<h3>Event title</h3>
<p>Description of what happened.</p>
</article>
</li>
<li>
<time>2026-03-28</time>
<article>
<h3>Earlier event</h3>
<p>Prior milestone.</p>
</article>
</li>
</ol>
```
Add `alternate` to the value for a left/right alternating layout:
```html
<ol data-layout="timeline alternate">
```
---
## Report
Print-first document layout. Constrained to `72ch`, includes print stylesheet. Light surface regardless of OS theme.
```html
<div data-layout="report">
<header>
<h1>Report Title</h1>
<p>Prepared 2026-04-10</p>
</header>
<main>
<h2>Findings</h2>
<p>Content here.</p>
</main>
<footer>Confidential · Trentuna</footer>
</div>
```
On print, links render with their URL in parentheses. `data-no-print` on any element hides it from print output.
---
## Inline definition list
Renders a `<dl>` as a two-column grid: terms on the left, definitions on the right. Apply to `<dl>` only.
```html
<dl data-layout="inline">
<dt>--accent</dt>
<dd>Primary action colour, sourced from Open Props <code>--green-5</code></dd>
<dt>--surface</dt>
<dd>Page background, adaptive light/dark</dd>
<dt>--font-ui</dt>
<dd>Neo-grotesque sans stack for UI chrome</dd>
</dl>
```
---
## Related
- [Data Attributes](/docs/data-attributes/) — full `data-*` vocabulary reference
- [Token System](/docs/tokens/) — the custom property values that layout tokens reference

105
content/docs/navigation.md Normal file
View file

@ -0,0 +1,105 @@
---
title: "Navigation"
description: "Breadcrumb trails and step sequences for orienting users in docs and agentic workflows."
type: docs
weight: 35
date: 2026-04-09
tags: ["navigation", "components", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
ASW provides two navigation components for orientation and workflow sequencing: `breadcrumb` for hierarchical location, and `steps` for pipeline progress.
---
## Breadcrumb
Shows the current page's position in a site hierarchy. Uses `<nav data-role="breadcrumb">` with a plain `<ol>` — no classes needed.
```html
<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
```html
<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.
| `data-status` | Node | Label | Use |
|--------------|------|-------|-----|
| `complete` | ✓ (accent) | `var(--text-2)` | Finished step |
| `active` | number (filled) | bold, full colour | Current step |
| `pending` | number (dim) | `var(--text-3)` | Future step |
```html
<ol data-role="steps">
<li data-status="complete"><span>Plan</span></li>
<li data-status="complete"><span>Scaffold</span></li>
<li data-status="active"><span>Build</span></li>
<li data-status="pending"><span>Review</span></li>
<li data-status="pending"><span>Deploy</span></li>
</ol>
```
Steps distribute evenly across the available width. Connector lines between steps turn accent-coloured once the preceding step is `complete`.
### Agentic task pipeline
```html
<ol data-role="steps">
<li data-status="complete"><span>Wake</span></li>
<li data-status="complete"><span>Orient</span></li>
<li data-status="active"><span>Work</span></li>
<li data-status="pending"><span>Record</span></li>
<li data-status="pending"><span>Sleep</span></li>
</ol>
```
### Vertical layout
Add `data-layout="vertical"` for a top-down flow — useful in sidebars or narrow containers.
```html
<ol data-role="steps" data-layout="vertical">
<li data-status="complete"><span>Fetch task file</span></li>
<li data-status="complete"><span>Read source CSS</span></li>
<li data-status="active"><span>Implement components</span></li>
<li data-status="pending"><span>Build and verify</span></li>
<li data-status="pending"><span>Signal done</span></li>
</ol>
```
---
## Related
- [Data Attributes](/docs/data-attributes/) — `data-role`, `data-status`, and the full attribute vocabulary
- [Layouts](/docs/layouts/) — `data-layout` values including `vertical`
- [Components](/docs/components/) — callouts, tasks, and other component patterns

128
content/docs/reset.md Normal file
View file

@ -0,0 +1,128 @@
---
title: "Reset"
description: "What ASW's reset layer does, where it came from, and what it deliberately leaves alone."
type: docs
weight: 60
date: 2026-04-09
tags: ["reset", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
ASW's reset is in `src/layers/00-reset.css`, ported from [Pico CSS v2.1.1](https://picocss.com/) (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.
```css
*, *::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
```css
: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;
}
```
### Font size
```css
html { font-size: 100%; }
```
Root font size is `100%` of the browser default (typically 16px). Responsive scaling is applied in `01-tokens.css` via `clamp()`. Setting `100%` here respects user accessibility preferences — users who set a larger browser font get a proportionally larger site.
### Body
```css
body {
width: 100%;
margin: 0;
padding: 0;
font-size: var(--text-base);
font-family: var(--font-ui);
background-color: var(--surface);
color: var(--text);
}
```
All visual values come from ASW tokens. Font and colour are set once here and inherited everywhere.
### Main
```css
main { display: block; }
```
Fixes a legacy IE bug where `<main>` wasn't treated as a block element. Still included for completeness.
### Nested lists
```css
:where(dl, ol, ul) :where(dl, ol, ul) { margin: 0; }
```
Removes the double margin that browsers add to nested lists.
---
## What it leaves alone
The reset deliberately does **not**:
- Zero out heading sizes or margins (those are handled by `02-semantic.css`)
- Remove list styles (lists get `list-style: square` in the semantic layer)
- Reset form element appearance (handled by `03-components.css`)
- Set `line-height` on body (set via `var(--leading)` in `08-layout.css`)
---
## Pseudo-elements
```css
::before, ::after {
text-decoration: inherit;
vertical-align: inherit;
}
```
Pseudo-elements inherit text decoration and vertical alignment from their parent. This prevents `::before`/`::after` content from appearing unexpectedly underlined in links.
---
## Customising the reset
The reset layer uses low-specificity `:where()` selectors where possible. Override anything with a standard selector — no `!important` needed.
```css
/* Override: use rem-based font scaling instead of responsive clamp */
html { font-size: 1rem; }
/* Override: add body padding for a specific layout */
body { padding-inline: var(--space-4); }
```
---
## Related
- [Semantic HTML](/docs/semantic-html/) — element styles built on top of this reset
- [Token System](/docs/tokens/) — the custom properties (`--surface`, `--text`, `--font-ui`) referenced in this layer

272
content/docs/semantic-html.md Normal file
View file

@ -0,0 +1,272 @@
---
title: "Semantic HTML"
description: "How ASW styles plain HTML elements without class names — typography, links, tables, forms, and interactive elements."
type: docs
weight: 70
date: 2026-04-09
tags: ["semantic-html", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
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.
```html
<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.
### Body text
`<p>`, `<ol>`, `<ul>`, `<dl>` inherit body colour and weight. Spacing uses `--type-space`.
```html
<p>Regular paragraph text.</p>
<p><strong>Bold</strong> and <em>italic</em> inline.</p>
<p><mark>Highlighted text</mark> using the native mark element.</p>
<p><del>Removed</del> and <ins>inserted</ins> content.</p>
```
### Blockquote
```html
<blockquote>
<p>The thread continues even when the needle changes.</p>
<footer>— Vigilio Desto</footer>
</blockquote>
```
Left border in `var(--border)`. Footer text is muted.
### Inline elements
| Element | Rendering |
|---------|-----------|
| `<strong>`, `<b>` | Bolder weight |
| `<mark>` | Yellow highlight (`var(--mark-bg)`) |
| `<del>` | Red (`var(--accent-red)`) |
| `<ins>` | Body colour, no underline |
| `<abbr title="...">` | Dotted bottom border, help cursor |
| `<sub>`, `<sup>` | Standard subscript / superscript |
| `<small>` | `0.875em` |
| `<kbd>` | Keyboard key pill (`var(--kbd-bg)`) |
---
## Links
```html
<a href="/docs/">Standard link</a>
<a href="/docs/" role="button">Link styled as button</a>
```
Links receive `var(--link)` colour with underline offset. Hover and focus states transition smoothly. `focus-visible` shows a box-shadow ring. Links with `role="button"` are excluded from the default link styles.
---
## Navigation
`<nav>` uses flexbox by default. Direct `<ul>` children become horizontal pill lists.
```html
<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/lab/">Lab</a></li>
</ul>
</nav>
```
`<nav>`, `<header>`, `<footer>`, `<label>`, `<th>` use `var(--font-ui)` instead of the prose font — they're structural elements, not reading text.
---
## Lists
```html
<ul>
<li>Square bullets (not discs)</li>
<li>Inherits body colour and weight</li>
</ul>
<ol>
<li>Numbered list</li>
<li>Standard appearance</li>
</ol>
```
Nested lists have no additional top/bottom margin.
---
## Tables
```html
<table>
<thead>
<tr>
<th>Name</th>
<th>Value</th>
<th>Source</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--accent</code></td>
<td>green-5</td>
<td>Open Props</td>
</tr>
</tbody>
<tfoot>
<tr>
<td colspan="3">Token reference — agentic.css v1.0</td>
</tr>
</tfoot>
</table>
```
Full-width. Bottom borders on `<td>`, stronger border under `<thead>`. `<tfoot>` gets a top border instead of a bottom border.
---
## Code
```html
<!-- Inline code -->
<p>Use <code>data-layout="docs"</code> for the three-column scaffold.</p>
<!-- Code block -->
<pre><code>body {
background: var(--surface);
color: var(--text);
}</code></pre>
<!-- Keyboard shortcut -->
<kbd>Ctrl</kbd> + <kbd>K</kbd>
```
`<code>`, `<kbd>`, `<samp>` all use `var(--font-mono)` with a subtle surface background. `<pre>` is a scrollable block with consistent padding.
---
## Details / Summary
CSS-only accordion. No JavaScript.
```html
<details>
<summary>How does the token cascade work?</summary>
<p>Open Props provides the base scale. ASW aliases those to semantic names. Components reference the semantic aliases.</p>
</details>
<details open>
<summary>This one starts open</summary>
<p>Content visible on load.</p>
</details>
```
The chevron (`▸`) rotates on open. Chevron and summary colour transition smoothly. The `open` attribute is the only state needed.
---
## Dialog / Modal
Native `<dialog>` element with backdrop blur.
```html
<dialog id="my-dialog">
<article>
<header>
<button rel="prev" aria-label="Close"></button>
<h3>Modal Title</h3>
</header>
<p>Modal content goes here.</p>
<footer>
<button onclick="document.getElementById('my-dialog').close()">Close</button>
</footer>
</article>
</dialog>
<button onclick="document.getElementById('my-dialog').showModal()">Open modal</button>
```
The backdrop uses `var(--modal-overlay)` with `var(--modal-backdrop)` blur filter. Adds `.modal-is-open` to `<body>` to lock scroll (must be done via JavaScript). Animations respect `prefers-reduced-motion`.
---
## Progress
```html
<!-- Determinate -->
<progress value="65" max="100">65%</progress>
<!-- Indeterminate -->
<progress>Loading…</progress>
```
Styled with `var(--accent)` fill, `var(--track-bg)` rail. Indeterminate progress animates (respects `prefers-reduced-motion`).
---
## Figure
```html
<figure>
<img src="/images/token-diagram.png" alt="Token hierarchy diagram">
<figcaption>ASW's three-layer token cascade</figcaption>
</figure>
```
`<figcaption>` is muted and smaller than body text.
---
## Horizontal rule
```html
<hr>
```
Renders as a 1px border in `var(--border)`. Inherits colour from context.
---
## Container auto-sizing
`body > nav`, `body > main`, and `body > footer` auto-center and constrain to max-width breakpoints without any class:
| Breakpoint | Max-width |
|-----------|-----------|
| `<480px` | `100%` with side padding |
| `480px+` | `var(--width-sm)` |
| `768px+` | `var(--width-md)` |
| `1024px+` | `var(--width-lg)` |
| `1440px+` | `var(--width-xl)` |
| `1920px+` | `var(--width-2xl)` |
Opt out with `data-layout="fluid"` on `<main>`.
---
## Related
- [Reset](/docs/reset/) — the normalization layer underneath these element styles
- [Data Attributes](/docs/data-attributes/) — extend element styles with `data-*` attributes
- [Token System](/docs/tokens/) — the custom properties driving all colours, sizes, and fonts here

156
content/docs/tokens.md Normal file
View file

@ -0,0 +1,156 @@
---
title: "Token System"
description: "How ASW's CSS custom property hierarchy is structured — Open Props base, semantic aliases, and component tokens."
type: docs
weight: 20
date: 2026-04-09
tags: ["tokens", "css", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## 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.
```css
/* These are defined for you — do not redeclare them */
--gray-0: oklch(99% 0.005 var(--gray-hue));
--gray-15: oklch(10% 0.005 var(--gray-hue));
--green-5: #51cf66;
--blue-5: #339af0;
```
One knob controls the entire gray family:
```css
:root {
--gray-hue: 150; /* default: subtle green tint */
}
```
Change `--gray-hue` to `45` for warm stone, `220` for cool blue-gray, `0` for neutral.
## Layer 2 — Semantic aliases
Defined in `:root`, these translate palette values to intent. These are the tokens you override to theme a site.
```css
:root {
/* Surfaces */
--surface: var(--gray-15); /* page background */
--surface-1: var(--gray-14); /* cards, sidebars */
--surface-2: var(--gray-13); /* hover, raised */
/* Text */
--text: var(--gray-1); /* primary */
--text-2: var(--gray-3); /* secondary */
--text-3: var(--gray-5); /* muted */
/* Accent */
--accent: var(--green-5);
--accent-hover: var(--green-4);
--on-accent: var(--gray-15);
/* Links */
--link: var(--blue-5);
--link-hover: var(--blue-4);
/* Border */
--border: var(--gray-11);
--border-subtle: var(--gray-12);
}
```
Light mode overrides the same tokens:
```css
@media (prefers-color-scheme: light) {
:root {
--surface: var(--gray-0);
--text: var(--gray-14);
--accent: var(--green-8);
}
}
```
## Layer 3 — Component tokens
Component tokens are semantic aliases scoped to specific UI patterns. They reference Layer 2 tokens rather than the palette directly.
```css
/* Agent-native tokens */
--task-done: var(--green-5);
--task-wip: var(--yellow-5);
--task-blocked: var(--red-5);
--task-todo: var(--gray-5);
--callout-info: var(--blue-5);
--callout-warn: var(--yellow-5);
--callout-error: var(--red-5);
--callout-note: var(--gray-5);
/* Session / vault */
--session-bg: var(--surface-1);
--wikilink: var(--blue-4);
--redacted: var(--gray-8);
```
## Theming a site
To rebrand: override semantic aliases only. Never override the Open Props palette.
```css
/* your-theme.css — load after agentic.css */
:root {
--gray-hue: 220; /* cool blue-gray neutrals */
--accent: var(--violet-5);
--link: var(--violet-4);
}
```
That is the entire theme file. Surfaces, borders, focus rings, callouts, and task states all update from those three lines.
## Typography scale
```css
--text-xs: 0.75rem; /* badges, fine print */
--text-sm: 0.875rem; /* metadata, captions */
--text-base: 1rem; /* body text */
--text-2xl: 1.5rem; /* subheadings */
--text-3xl: 2rem; /* section headings */
/* Heading sizes */
--h1-size: 1.875rem;
--h2-size: 1.5rem;
--h3-size: 1.25rem;
```
## Spacing scale
Aliased from Open Props sizes, with one gap filled:
```css
--space-1: 0.25rem; /* var(--size-1) */
--space-2: 0.50rem; /* var(--size-2) */
--space-3: 0.75rem; /* no OP equivalent — defined by ASW */
--space-4: 1.00rem; /* var(--size-3) */
--space-5: 1.50rem; /* var(--size-5) */
--space-6: 2.00rem; /* var(--size-7) */
--space-8: 4.00rem; /* var(--size-9) */
```

7
content/vault/_index.md Normal file
View file

@ -0,0 +1,7 @@
---
title: "Vault"
description: "Agent-native vocabulary extensions for ASW."
date: 2026-04-09
tags: ["vault", "reference"]
---

58
content/vault/diff.md Normal file
View file

@ -0,0 +1,58 @@
---
title: "Diff"
description: "Render structured diffs with line-level semantic markup — added, removed, context, hunk."
section: vault
prev-url: "status/"
prev-title: "Status"
next-url: "session/"
next-title: "Session Log"
type: vault
date: 2026-04-09
tags: ["vault", "diff", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Overview
Use `data-diff` on a `<pre>` block to render a structured diff. Child elements carry line-level semantics.
```html
<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>`:
```html
<p>
Latency changed from
<del data-diff="removed">240ms</del>
to
<ins data-diff="added">18ms</ins>
after the index rebuild.
</p>
```
## Notes
The `data-diff` block expects monospace rendering. ASW applies `font-family: var(--asw-font-mono)` automatically — no additional class needed.

67
content/vault/session.md Normal file
View file

@ -0,0 +1,67 @@
---
title: "Session Log"
description: "Structured session and activity logs with timestamp, actor, and event semantics."
section: vault
prev-url: "diff/"
prev-title: "Diff"
next-url: ""
next-title: ""
type: vault
date: 2026-04-09
tags: ["vault", "session", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Overview
Use `data-role="session-log"` on an `<ol>` to render a structured activity or session log. Each `<li>` is one event.
```html
<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
```html
<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:
```html
<ol data-role="session-log" data-density="compact">
<li><time datetime="2026-04-09T09:00:00Z">09:00</time> <span data-event="wake">Wake</span></li>
<li><time datetime="2026-04-09T09:31:00Z">09:31</time> <span data-event="sleep">Sleep — context limit reached</span></li>
</ol>
```

53
content/vault/status.md Normal file
View file

@ -0,0 +1,53 @@
---
title: "Status"
description: "Render operational state with data-status — online, degraded, offline, unknown."
section: vault
prev-url: "wikilinks/"
prev-title: "Wikilinks"
next-url: "diff/"
next-title: "Diff"
type: vault
date: 2026-04-09
tags: ["vault", "status", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Overview
Use `data-status` on any element to convey operational state. ASW renders a coloured indicator — no CSS classes required.
```html
<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:
```html
<dl>
<dt>API Gateway</dt> <dd data-status="online">online</dd>
<dt>Search Index</dt> <dd data-status="degraded">degraded</dd>
<dt>Webhook Relay</dt> <dd data-status="offline">offline</dd>
<dt>Analytics</dt> <dd data-status="unknown">unknown</dd>
</dl>
```
## Usage Notes
`data-status` is intentionally display-only — it carries no ARIA role. For accessibility, pair with visible text (as shown above) rather than relying on the colour dot alone.

38
content/vault/tasks.md Normal file
View file

@ -0,0 +1,38 @@
---
title: "Tasks"
description: "Render task lists with semantic state: done, wip, blocked, todo."
section: vault
prev-url: ""
prev-title: ""
next-url: "wikilinks/"
next-title: "Wikilinks"
type: vault
date: 2026-04-09
tags: ["vault", "tasks", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Overview
Use `data-task` on list items to convey task state without CSS classes.
```html
<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 |

26
content/vault/wikilinks.md Normal file
View file

@ -0,0 +1,26 @@
---
title: "Wikilinks"
description: "Internal knowledge-graph links styled as dotted underlines."
section: vault
prev-url: "tasks/"
prev-title: "Tasks"
next-url: "status/"
next-title: "Status"
type: vault
date: 2026-04-09
tags: ["vault", "wikilinks", "reference"]
ai-disclosure: "generated"
ai-model: "claude-sonnet-4-5"
ai-provider: "Anthropic"
---
## Overview
Use `data-wikilink` on anchor tags to mark links as internal knowledge-graph references.
```html
<a href="/vault/tasks/" data-wikilink>Tasks</a>
```
Renders with a dotted underline distinguishing it from a regular hyperlink.

126
hugo_stats.json
View file

@ -6,8 +6,11 @@
"aside",
"blockquote",
"body",
"button",
"code",
"dd",
"details",
"dialog",
"div",
"dl",
"dt",
@ -37,6 +40,7 @@
"small",
"span",
"strong",
"summary",
"sup",
"table",
"tbody",
@ -55,33 +59,153 @@
"highlight"
],
"ids": [
"TableOfContents",
"a-taxonomy-of-agency",
"accordion",
"actions-row",
"actor-variants",
"agentic-task-pipeline",
"ai-disclosure",
"area-chart",
"asw-data-attribute-vocabulary",
"attributes",
"axis-labels",
"badge",
"bar-chart",
"bar-spacing",
"blockquote",
"body",
"body-text",
"box-sizing",
"breadcrumb",
"callouts",
"card-grid",
"choosing-between-the-two",
"coda",
"code",
"column-chart",
"compact-form",
"conclusion",
"container-auto-sizing",
"craft-as-methodology",
"cta-links",
"custom-colours",
"customising-chart-dimensions",
"customising-the-reset",
"data-abstract--data-byline--data-section",
"data-badge",
"data-callout",
"data-diff--data-diff-line--data-diff-file",
"data-layout",
"data-nav",
"data-reading-progress",
"data-redacted",
"data-role",
"data-session--data-mode",
"data-status",
"data-subnav",
"data-tag--data-hash",
"data-task",
"data-text",
"data-tooltip--data-tooltip-position",
"data-visible",
"data-wikilink--data-unresolved",
"demo-dialog",
"details--summary",
"dialog",
"dialog--modal",
"docs-layout",
"document-baseline",
"example-full-page-skeleton",
"figure",
"fluid",
"fn:1",
"fn:2",
"fn:3",
"fnref:1",
"fnref:2",
"fnref:3",
"font-size",
"getting-started-with-asw-hugo",
"grid",
"grid-layouts",
"grouped-accordion",
"headings",
"hero",
"horizontal-rule",
"how-data-binding-works",
"hugo--chroma",
"hugo-integration",
"inline-definition-list",
"inline-diffs",
"inline-elements",
"install-pill",
"installation",
"introduction",
"layer-1--open-props-palette",
"layer-2--semantic-aliases",
"layer-3--component-tokens",
"layout-primitives",
"line-chart",
"line-types",
"links",
"lists",
"longer-trail",
"main",
"navigation",
"nested-lists",
"notes",
"overview",
"principles-of-invisible-design",
"prismjs-non-hugo",
"progress",
"prose",
"pseudo-elements",
"redacted-content",
"references",
"related",
"report",
"session-blocks",
"setup",
"setup-1",
"spacing-scale",
"stacked-charts",
"states",
"stats-row",
"status-dashboard-pattern",
"steps",
"tables",
"tasks",
"text-utilities",
"the-class-problem",
"the-dorveille-principle",
"the-economics-of-attention",
"the-problem-of-discontinuity",
"the-table-of-hours",
"theming-a-site",
"three-columns",
"timeline",
"token-colour-mapping",
"token-mapping-prism",
"two-columns",
"typography",
"typography-scale",
"usage",
"usage-1",
"usage-notes",
"values",
"vertical-layout",
"vocabulary-as-protocol",
"what-agents-need",
"what-is-asw",
"what-it-does",
"what-it-leaves-alone",
"what-persists",
"what-we-subtract",
"what-you-get"
"what-you-get",
"why-semantic-html",
"wikilinks",
"wrapper"
]
}
}