From da1d02ccd14c22283f526e1b30b02d84b2792058 Mon Sep 17 00:00:00 2001 From: Vigilio Desto Date: Fri, 10 Apr 2026 18:40:50 +0200 Subject: [PATCH] Port vault section (5 pages) and docs section (11 pages) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- content/docs/_index.md | 11 + content/docs/accordion-dialog.md | 117 ++++++++++ content/docs/charts.md | 217 ++++++++++++++++++ content/docs/chroma.md | 155 +++++++++++++ content/docs/components.md | 222 +++++++++++++++++++ content/docs/data-attributes.md | 362 +++++++++++++++++++++++++++++++ content/docs/introduction.md | 96 ++++++++ content/docs/layouts.md | 247 +++++++++++++++++++++ content/docs/navigation.md | 105 +++++++++ content/docs/reset.md | 128 +++++++++++ content/docs/semantic-html.md | 272 +++++++++++++++++++++++ content/docs/tokens.md | 156 +++++++++++++ content/vault/_index.md | 7 + content/vault/diff.md | 58 +++++ content/vault/session.md | 67 ++++++ content/vault/status.md | 53 +++++ content/vault/tasks.md | 38 ++++ content/vault/wikilinks.md | 26 +++ hugo_stats.json | 126 ++++++++++- 19 files changed, 2462 insertions(+), 1 deletion(-) create mode 100644 content/docs/_index.md create mode 100644 content/docs/accordion-dialog.md create mode 100644 content/docs/charts.md create mode 100644 content/docs/chroma.md create mode 100644 content/docs/components.md create mode 100644 content/docs/data-attributes.md create mode 100644 content/docs/introduction.md create mode 100644 content/docs/layouts.md create mode 100644 content/docs/navigation.md create mode 100644 content/docs/reset.md create mode 100644 content/docs/semantic-html.md create mode 100644 content/docs/tokens.md create mode 100644 content/vault/_index.md create mode 100644 content/vault/diff.md create mode 100644 content/vault/session.md create mode 100644 content/vault/status.md create mode 100644 content/vault/tasks.md create mode 100644 content/vault/wikilinks.md diff --git a/content/docs/_index.md b/content/docs/_index.md new file mode 100644 index 0000000..022a819 --- /dev/null +++ b/content/docs/_index.md @@ -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/). diff --git a/content/docs/accordion-dialog.md b/content/docs/accordion-dialog.md new file mode 100644 index 0000000..a13c9cc --- /dev/null +++ b/content/docs/accordion-dialog.md @@ -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 `
`/`` elements. No JS needed — the browser handles open/close state. + +```html +
+ What is agentic HTML? +

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

+
+``` + +**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.

+
+ +--- + +## Grouped Accordion + +Wrap in `
` for flush connected borders. + +```html +
+
+ Reset layer +

Normalises browser defaults without imposing opinions.

+
+
+ Token layer +

Open Props foundation plus ASW semantic aliases.

+
+
+ Components layer +

Buttons, forms, accordion, dialog — all zero-class.

+
+
+``` + +**Live example:** + +
+
+ Reset layer +

Normalises browser defaults without imposing opinions.

+
+
+ Token layer +

Open Props foundation plus ASW semantic aliases.

+
+
+ Components layer +

Buttons, forms, accordion, dialog — all zero-class.

+
+
+ +--- + +## Dialog + +Native `` element. Use `dialog.showModal()` for a modal with backdrop, or `dialog.show()` for a non-modal popover. + +```html + +

Confirm action

+

Are you sure you want to proceed? This cannot be undone.

+
+ + +
+ + + +``` + +**Live example:** + + +

Confirm action

+

Are you sure you want to proceed? This cannot be undone.

+
+ + +
+ + + + +--- + +## 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. diff --git a/content/docs/charts.md b/content/docs/charts.md new file mode 100644 index 0000000..74ded2b --- /dev/null +++ b/content/docs/charts.md @@ -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 ``. CSS turns it into a chart. + +--- + +## How data binding works + +Each `` column labels as axis labels. + +```html +
` 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 + + + + + + + + + + + + + + + + +
Token budget usage
Wake15%
Research62%
Output23%
+``` + +--- + +## Column chart + +Vertical bars. Each `		` is one column. + +```html + + + + + + + + + + + +
Sessions per day
MonTueWedThuFri
+``` + +--- + +## Line chart + +Connects data points with a line. Requires two `		` values per point: `--start` and `--end`. + +```html + + + + + + + + + + +
Uptime trend
+``` + +--- + +## Area chart + +Like a line chart but with the area beneath filled. + +```html + + + + + + + + + + +
Memory usage
+``` + +--- + +## Axis labels + +Add `data-chart-labels` to show `
+ + + + + + + + + + + + + + +
MonTueWed
40%70%55%
+``` + +--- + +## Bar spacing + +Control gap between bars with `data-chart-spacing="1"` through `"5"` (default is `2`). + +```html + + ... +
+``` + +--- + +## Stacked charts + +Multi-dataset mode. Each `` in `` becomes a dataset (one colour per row). + +```html + + + + + + + + + + + + + + +
Token usage by phase
+``` + +--- + +## Custom colours + +Override the default colour cycle with `style="--color: ..."` on any ``. + +```html + + Error rate + +``` + +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 + +``` + +| 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 diff --git a/content/docs/chroma.md b/content/docs/chroma.md new file mode 100644 index 0000000..82b91f4 --- /dev/null +++ b/content/docs/chroma.md @@ -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 `
`. 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
+
+
+```
+
+No Prism theme stylesheet needed — ASW overrides the colours.
+
+### Usage
+
+```html
+
:root {
+  --accent: var(--green-5);
+  --surface: var(--gray-15);
+}

+
+

+  
Hello

+

+```
+
+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 `
` and `` are styled at the element level
diff --git a/content/docs/components.md b/content/docs/components.md
new file mode 100644
index 0000000..da69767
--- /dev/null
+++ b/content/docs/components.md
@@ -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
+

+  Tip
+  
Use data-callout instead of inventing class names.

+

+
+

+  Warning
+  
Overriding Open Props palette tokens breaks theming.

+

+
+

+  Error
+  
This file exceeds the token budget.

+

+
+

+  Note
+  
Both note and info are valid values.

+

+```
+
+{{< callout tip >}}
+In Hugo, use the `callout` shortcode: `{{}}...{{}}`
+{{< /callout >}}
+
+Valid values: `tip`, `note`, `info`, `warning`, `error`.
+
+---
+
+## Tasks
+
+Render task lists with semantic state. Agents write task lists naturally; `data-task` on the `
  • ` adds the visual state indicator.
+
+```html
+
      
+  
    • Token layer integrated
      • 
+  
    • Docs site taxonomy wired
      • 
+  
    • Hugo layouts — in progress
      • 
+  
    • Deploy — waiting on DNS
      • 
+  
    • Vocabulary retirement pass
      • 
+
    
+```
+
+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
+
    
+  
    
+    
    Session 2847
    
+    
    2026-04-02 · 31 min · claude-sonnet-4-6
    
+  
    
+
+  
      
+    
    • Vault token layer
      • 
+    
    • Paper layout
      • 
+  
    
+
+  
    
+    Handoff
+    
    Next session: harden paper/single.html styles into agentic.css.
    
+  
    
+
    
+```
+
+---
+
+## Wikilinks
+
+Internal knowledge-graph links. `data-wikilink` on an anchor renders it with a dotted underline to distinguish it from a regular hyperlink.
+
+```html
+Tasks
+```
+
+In Hugo, use the `wikilink` shortcode:
+
+```
+{{}}
+```
+
+---
+
+## Redacted content
+
+Sensitive values rendered as black bars. Optional hover-reveal.
+
+```html
+API key: sk-ant-...
+
+
+classified content
+```
+
+---
+
+## Layout primitives
+
+### Grid
+
+```html
+
+
    
+  
    Left
    
+  
    Right
    
+
    
+
+
+
    
+  
    One
    
+  
    Two
    
+  
    Three
    
+
    
+
+
+
    
+  
    Card A
    
+  
    Card B
    
+  
    Card C
    
+
    
+```
+
+### Stats row
+
+```html
+
    
+  
    
+    2847
+    Sessions
+  
    
+  
    
+    99.8%
+    Uptime
+  
    
+
    
+```
+
+### Docs layout
+
+Three-column sidebar scaffold. Source order matters: left aside → article → right aside.
+
+```html
+
    
+  
+
+  
    
+    
+  
    
+
+  
+
    
+```
+
+---
+
+## Text utilities
+
+```html
+
    Muted — var(--text-3)
    
+
    Accent colour
    
+SECTION LABEL
+Fine print
+```
+
+---
+
+## CTA links
+
+```html
+Get started →
+Documentation
+```
+
+---
+
+## Badge
+
+Icon or token pill. Used by the landing page pillars; also useful inline.
+
+```html
+</>
+data=
+:root
+```
diff --git a/content/docs/data-attributes.md b/content/docs/data-attributes.md
new file mode 100644
index 0000000..4dd9364
--- /dev/null
+++ b/content/docs/data-attributes.md
@@ -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` | `` | Filled CTA button |
+| `secondary` | `` | Outlined CTA button |
+| `card` | any | Card container |
+| `command-box` | `
    ` | Install/command pill with prefix glyph |
+| `status-card` | `
    ` | Bordered status block |
+| `diff` | `
    ` | Inline diff viewer (legacy; prefer `data-diff`) |
+| `log-entry` | any | Single log line, bottom border |
+| `list-item` | any | Minimal padding list item |
+| `prev-next` | `
    ` | Prev/next navigation pair |
+| `tag-cloud` | `
    ` | Tag cluster |
+| `timeline` | `
    ` | Simple left-spine timeline (legacy; prefer `data-layout="timeline"`) |
+
+```html
+Read docs →
+Source
+
+
    
+  $
+  npm install agentic-css
+
    
+```
+
+---
+
+## 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
+online
+waiting on DNS
+idle since 03:00
+```
+
+---
+
+## data-task
+
+Task list item with state glyph. Apply to `
  • ` elements.
+
+| Value | Glyph | Colour |
+|-------|-------|--------|
+| `todo` | ○ | orange |
+| `done` | ● | accent |
+| `blocked` | ◐ | red |
+
+```html
+
      
+  
    • Deploy nginx config
      • 
+  
    • Update DNS records
      • 
+  
    • TLS cert — waiting on propagation
      • 
+
    
+```
+
+---
+
+## data-callout
+
+Advisory block with left border accent and optional title.
+
+| Value | Border colour |
+|-------|--------------|
+| *(default)* | blue |
+| `tip` | accent (green) |
+| `warning` | orange |
+| `error` | red |
+
+```html
+
    
+  Tip
+  
    Use data attributes instead of class names.
    
+
    
+
+
    
+  Warning
+  
    This resets the token cascade.
    
+
    
+```
+
+---
+
+## 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
+
    Getting started
    
+
    Token System
    
+
    How the custom property hierarchy is structured.
    
+
+
    Last updated 2026-04-10
    
+--accent
+```
+
+---
+
+## 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 `
    • ` — striped, bordered automatically | +| Dark mode | System preference via `prefers-color-scheme` | +| Theming | Override `--accent` and `--gray-hue` in `:root` | diff --git a/content/docs/layouts.md b/content/docs/layouts.md new file mode 100644 index 0000000..3f20157 --- /dev/null +++ b/content/docs/layouts.md @@ -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 ``. `` gets a top border instead of a bottom border. + +--- + +## Code + +```html + +

    Use data-layout="docs" for the three-column scaffold.

    + + +
    body {
+  background: var(--surface);
+  color: var(--text);
+}
    + + +Ctrl + K +``` + +``, ``, `` all use `var(--font-mono)` with a subtle surface background. `
    ` is a scrollable block with consistent padding.
+
+---
+
+## Details / Summary
+
+CSS-only accordion. No JavaScript.
+
+```html
+
    
+  How does the token cascade work?
+  
    Open Props provides the base scale. ASW aliases those to semantic names. Components reference the semantic aliases.
    
+
    
+
+
    
+  This one starts open
+  
    Content visible on load.
    
+
    
+```
+
+The chevron (`▸`) rotates on open. Chevron and summary colour transition smoothly. The `open` attribute is the only state needed.
+
+---
+
+## Dialog / Modal
+
+Native `` element with backdrop blur.
+
+```html
+
+  
    
+    
    
+      
+      
    Modal Title
    
+    
    
+    
    Modal content goes here.
    
+    
    
+      
+    
    
+  
    
+    
+
+
+```
+
+The backdrop uses `var(--modal-overlay)` with `var(--modal-backdrop)` blur filter. Adds `.modal-is-open` to `` to lock scroll (must be done via JavaScript). Animations respect `prefers-reduced-motion`.
+
+---
+
+## Progress
+
+```html
+
+65%
+
+
+Loading…
+```
+
+Styled with `var(--accent)` fill, `var(--track-bg)` rail. Indeterminate progress animates (respects `prefers-reduced-motion`).
+
+---
+
+## Figure
+
+```html
+
    
+  Token hierarchy diagram
+  
    ASW's three-layer token cascade
    
+
    
+```
+
+`
    ` is muted and smaller than body text.
+
+---
+
+## Horizontal rule
+
+```html
+
    
+```
+
+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 `
    `.
+
+---
+
+## 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
diff --git a/content/docs/tokens.md b/content/docs/tokens.md
new file mode 100644
index 0000000..fa391fa
--- /dev/null
+++ b/content/docs/tokens.md
@@ -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) */
+```
diff --git a/content/vault/_index.md b/content/vault/_index.md
new file mode 100644
index 0000000..c8f84d0
--- /dev/null
+++ b/content/vault/_index.md
@@ -0,0 +1,7 @@
+---
+title: "Vault"
+description: "Agent-native vocabulary extensions for ASW."
+date: 2026-04-09
+tags: ["vault", "reference"]
+
+---
diff --git a/content/vault/diff.md b/content/vault/diff.md
new file mode 100644
index 0000000..f25931d
--- /dev/null
+++ b/content/vault/diff.md
@@ -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 `
    ` block to render a structured diff. Child elements carry line-level semantics.
+
+```html
+
    +  @@ -12,7 +12,9 @@
+   function greet(name) {
+  -  return "Hello " + name;
+  +  const greeting = `Hello, ${name}!`;
+  +  return greeting;
+   }
+
    
+```
+
+## 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 `` and ``:
+
+```html
+
    
+  Latency changed from
+  240ms
+  to
+  18ms
+  after the index rebuild.
+
    
+```
+
+## Notes
+
+The `data-diff` block expects monospace rendering. ASW applies `font-family: var(--asw-font-mono)` automatically — no additional class needed.
diff --git a/content/vault/session.md b/content/vault/session.md
new file mode 100644
index 0000000..d5a2d69
--- /dev/null
+++ b/content/vault/session.md
@@ -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 `
      ` to render a structured activity or session log. Each `
    1. ` is one event.
+
+```html
+
        
+  
      1. 
+    
+    vigilio
+    Session started — model claude-sonnet-4-6
+  
        2. 
+  
      2. 
+    
+    vigilio
+    Read vault overview and daily note
+  
        3. 
+  
      3. 
+    
+    system
+    Committed: feat(vault): add session-log pattern
+  
        4. 
+
      
+```
+
+## Attributes
+
+| Attribute | Element | Meaning |
+|-----------|---------|---------|
+| `data-role="session-log"` | `
        ` | Activates session-log layout |
+| `data-actor` | `` | Who performed the action — styled by value |
+| `data-event` | `` | Event type — `wake`, `read`, `write`, `commit`, `sleep` |
+
+## Actor Variants
+
+```html
+vigilio   
+ludo         
+system     
+```
+
+## Compact Form
+
+For dense logs, omit the actor and let timestamp + event carry the entry:
+
+```html
+
          
+  
        1.  Wake
          2. 
+  
        2.  Sleep — context limit reached
          3. 
+
        
+```
diff --git a/content/vault/status.md b/content/vault/status.md
new file mode 100644
index 0000000..25ba394
--- /dev/null
+++ b/content/vault/status.md
@@ -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
+API Gateway
+Search Index
+Legacy Auth
+Webhook Relay
+```
+
+## 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 `
        ` for a compact service health panel:
+
+```html
+
        
+  
        API Gateway
             
        online
        
+  
        Search Index
            
        degraded
        
+  
        Webhook Relay
           
        offline
        
+  
        Analytics
               
        unknown
        
+
        
+```
+
+## 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.
diff --git a/content/vault/tasks.md b/content/vault/tasks.md
new file mode 100644
index 0000000..9b3521e
--- /dev/null
+++ b/content/vault/tasks.md
@@ -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
+
          
+  
        • Completed item
          • 
+  
        • Work in progress
          • 
+  
        • Blocked item
          • 
+  
        • Not started
          • 
+
        
+```
+
+## States
+
+| Value | Meaning |
+|-------|---------|
+| `done` | Completed — green check |
+| `wip` | In progress — amber |
+| `blocked` | Blocked — red |
+| `todo` | Not started — muted |
diff --git a/content/vault/wikilinks.md b/content/vault/wikilinks.md
new file mode 100644
index 0000000..b4036fa
--- /dev/null
+++ b/content/vault/wikilinks.md
@@ -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
+Tasks
+```
+
+Renders with a dotted underline distinguishing it from a regular hyperlink.
diff --git a/hugo_stats.json b/hugo_stats.json
index fa6c225..4fff95c 100644
--- a/hugo_stats.json
+++ b/hugo_stats.json
@@ -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"
     ]
   }
 }
    ` use `var(--font-ui)` instead of the prose font — they're structural elements, not reading text. + +--- + +## Lists + +```html +
      +
    • Square bullets (not discs)
      • +
    • Inherits body colour and weight
      • +
    + +
      +
    1. Numbered list
      2. +
    2. Standard appearance
      3. +
    +``` + +Nested lists have no additional top/bottom margin. + +--- + +## Tables + +```html + + + + + + + + + + + + + + + + + + + + +
    NameValueSource
    --accentgreen-5Open Props
    Token reference — agentic.css v1.0
    +``` + +Full-width. Bottom borders on `    		`, stronger border under `