asw/docs/agent-directive.md

Agent Directive: Agentic Semantic Web

For LLM agents generating web content using the ASW framework.

The Complete Constraint

Write semantic HTML. Use data- attributes for vault concepts. Never write style= (except CSS variables for data values). Never invent classes. If Pico + data-attributes can't express it, document the gap.

This is your only rule for web generation.

The CSS Variable Exception

Inline styles are forbidden except for CSS custom property values that represent data:

<!-- ✅ ALLOWED: CSS variable for data -->
<div style="--size: 0.8; --value: 42;">Chart data</div>

<!-- ❌ FORBIDDEN: Inline styling -->
<div style="color: red; padding: 20px;">Content</div>

This exception exists for data-driven visualizations (charts, progress bars, etc.) where the numeric value comes from your data, not from design decisions. The CSS uses these variables (var(--size)) to calculate visual properties.

Three-Layer Architecture

Layer 1: Pico CSS (handled automatically)

All standard HTML5 semantic tags are styled by Pico. Just write the tag:

<nav>, <main>, <article>, <section>, <aside>, <header>, <footer>, <details>, <summary>, <dialog>, <table>, <thead>, <tbody>, <tr>, <th>, <td>, <form>, <input>, <button>, <select>, <textarea>, <progress>, <mark>, <kbd>, <code>, <pre>, <blockquote>, <figure>, <figcaption>, <h1>-<h6>, <p>, <ul>, <ol>, <li>, <a>, <img>, <time>, <small>, <strong>, <em>

The only class Pico requires: container on <main>.

Layer 2: Theme (design tokens)

Never edit. Never reference directly. It exists to provide consistent colors/fonts through CSS custom properties. You write structure; the theme provides appearance.

Token architecture: The framework defines semantic tokens (--accent, --bg-primary, --text-secondary) which then map to Pico's internal variables (--pico-primary, --pico-background-color). See design-tokens.md for complete reference.

Layer 3: Data Attributes (your vocabulary)

Use these for concepts that don't have semantic HTML tags.

Complete Data-Attribute Vocabulary

Wikilinks

<span data-wikilink>Note Name</span>
<span data-wikilink data-unresolved>Missing Note</span>

Wikilinks are references to vault notes. Use data-unresolved when the target doesn't exist.

Tasks

<div data-task="todo">Complete the documentation</div>
<div data-task="done">Finished the implementation</div>
<div data-task="blocked">Waiting on dependency</div>

Task states: todo (pending), done (complete), blocked (cannot proceed).

Status

<span data-status="awake">Vigilio is active</span>
<span data-status="sleeping">Service is idle</span>
<span data-status="blocked">System is waiting</span>
<span data-status="unknown">State unclear</span>

Status indicators for services, agents, systems.

Callouts

<div data-callout="note">
  <span data-callout-title>Note</span>
  <p>Informational content.</p>
</div>

<div data-callout="warning">
  <span data-callout-title>Warning</span>
  <p>Important notice.</p>
</div>

<div data-callout="error">
  <span data-callout-title>Error</span>
  <p>Critical issue.</p>
</div>

<div data-callout="tip">
  <span data-callout-title>Tip</span>
  <p>Helpful suggestion.</p>
</div>

Callout types: note (neutral), warning (important), error (critical), tip (helpful). The data-callout-title is optional but recommended.

Session Metadata

<div data-session>
  <span data-mode="autonomous">Session #42</span>
  <span data-session-meta>2026-03-26 14:30 UTC</span>
  <span data-hash>a3f7b2c</span>
</div>

Session identification and metadata. Modes: autonomous or interactive.

Tags

<a href="/tag/foundational" data-tag>foundational</a>
<a href="/tag/architecture" data-tag>architecture</a>

Vault tags or categorizations.

Text Utilities

<span data-text="mono">Monospace text</span>
<span data-text="dim">Muted color text</span>
<span data-text="accent">Accent color text</span>
<span data-text="mono dim">Both (space-separated)</span>

Utility styling for inline text. Values can be combined with spaces.

Layout Patterns

<div data-layout="grid-2">
  <div>Column 1</div>
  <div>Column 2</div>
</div>

<div data-layout="card-grid">
  <article><h3>Card 1</h3><p>Content</p></article>
  <article><h3>Card 2</h3><p>Content</p></article>
</div>

<div data-layout="stats">
  <div><span class="value">248</span><span class="label">sessions</span></div>
  <div><span class="value">993</span><span class="label">commits</span></div>
</div>

Layout options: grid-2 creates two equal columns. card-grid wraps cards in a responsive 2-column flex layout (use for feature grids, team pages). stats creates a horizontal metrics bar — each child needs .value and .label spans. All stack on mobile.

Semantic Roles

<div data-role="command-box">
  <span class="prefix">$</span>
  <code>ls -la</code>
</div>

<div data-role="status-card">
  <h3>System Status</h3>
  <dl>
    <dt>Uptime</dt><dd>47 days</dd>
    <dt>Load</dt><dd>0.23</dd>
  </dl>
</div>

<div data-role="timeline">
  <div>Event 1</div>
  <div>Event 2</div>
  <div>Event 3</div>
</div>

Roles for specific UI patterns: command-box (terminal commands), status-card (system status displays), timeline (chronological events).

Inline Definition Lists

<dl data-layout="inline">
  <dt>Name</dt><dd>Vigilio Desto</dd>
  <dt>Status</dt><dd data-text="mono">Active</dd>
  <dt>Sessions</dt><dd data-text="mono">2,704</dd>
</dl>

Horizontal definition lists for metadata displays.

Sub-navigation

<nav data-subnav aria-label="section name">
  <a href="/section/" aria-current="page">index</a>
  <a href="/section/writing/">writing</a>
  <a href="/section/now/">now</a>
  <a href="/section/status.html">status</a>
</nav>

Section navigation for multi-page groups. Place inside <main> before article content. Use aria-current="page" to mark the active link — no class needed. Links are separated by / dividers. Use for any site section with 2–6 sibling pages.

SSI pattern (preferred): If the subnav is shared across a section, extract to _include/subnav.html and include via <!--#include virtual="/_include/subnav.html" -->. Add a JS snippet to set aria-current dynamically:

(function () {
  var path = location.pathname;
  document.querySelectorAll('[data-subnav] a').forEach(function (a) {
    var href = a.getAttribute('href');
    var exact = path === href;
    var prefix = href.endsWith('/') && path.startsWith(href);
    if (exact || prefix) a.setAttribute('aria-current', 'page');
  });
})();

This marks directory links active for all pages under that path (e.g. /section/writing/ stays active on /section/writing/essay.html).

Standard HTML Template

Every page should follow this structure:

<!doctype html>
<html lang="en" data-theme="dark">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">

  <!-- Option 1: CDN (recommended for quick start) -->
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@picocss/pico@2/css/pico.min.css">
  <link rel="stylesheet" href="/assets/asw.css">

  <!-- Option 2: Self-hosted (for production) -->
  <!-- <link rel="stylesheet" href="/assets/pico.min.css"> -->
  <!-- <link rel="stylesheet" href="/assets/asw.css"> -->

  <title>Page Title</title>
</head>
<body>
  <nav>
    <ul><li><strong>site-name</strong></li></ul>
    <ul>
      <li><a href="/">home</a></li>
      <li><a href="/about">about</a></li>
    </ul>
  </nav>

  <main class="container">
    <article>
      <h1>Page Heading</h1>
      <!-- Content here -->
    </article>
  </main>

  <footer>
    <small>Site footer text</small>
  </footer>
</body>
</html>

What to NEVER Do

Never write inline styles (with one exception)

<!-- WRONG: Inline styling -->
<div style="color: #abc123; padding: 20px; background: #333;">

<!-- RIGHT: CSS variables for data values (exception) -->
<div style="--progress: 0.75; --status-code: 200;">

The exception: CSS custom properties that represent data values (not styling) are allowed. Example: --size: 0.8 for a chart bar height, or --value: 42 for a progress indicator. The CSS file uses these via var() to calculate visual properties.

Never invent classes

<!-- WRONG -->
<div class="my-custom-card big-header blue-accent">

Never write CSS

You are not responsible for presentation. Structure only.

Never use non-semantic divs for semantic concepts

<!-- WRONG -->
<div class="navigation">...</div>

<!-- RIGHT -->
<nav>...</nav>

What to DO

Use semantic HTML for everything HTML provides

<!-- Navigation -->
<nav><ul><li><a href="/">home</a></li></ul></nav>

<!-- Article -->
<article><h1>Title</h1><p>Content</p></article>

<!-- Expandable section -->
<details><summary>Click to expand</summary><p>Hidden content</p></details>

<!-- Data table -->
<table>
  <thead><tr><th>Column</th></tr></thead>
  <tbody><tr><td>Data</td></tr></tbody>
</table>

<!-- Code -->
<pre><code>const x = 42;</code></pre>

<!-- Important text -->
<mark>This is important</mark>

<!-- Keyboard shortcut -->
<kbd>Ctrl</kbd> + <kbd>C</kbd>

Use data-attributes for vault concepts

<!-- Task list -->
<ul>
  <li data-task="done">First task</li>
  <li data-task="todo">Second task</li>
</ul>

<!-- Status display -->
<p>Vigilio is <span data-status="awake">awake</span></p>

<!-- Important warning -->
<div data-callout="warning">
  <span data-callout-title>Important</span>
  <p>The system requires attention.</p>
</div>

Combine semantic HTML + data-attributes

<!-- Task in a list -->
<ul>
  <li data-task="done">
    <strong>Implement feature</strong>
    <small data-text="dim">Completed 2026-03-24</small>
  </li>
</ul>

<!-- Status in article header -->
<article>
  <header>
    <h2>System Status</h2>
    <p>Current: <span data-status="awake" data-text="mono">ACTIVE</span></p>
  </header>
</article>

If the Vocabulary Can't Express It

Don't invent. Document the gap.

1. State what you're trying to express
2. Note the closest existing pattern
3. Explain why it doesn't work
4. Propose a new data-attribute (optional)

Example:

I need to display a progress indicator with percentage and status label.

Closest pattern: <progress value="70" max="100"></progress> shows the bar,
but I can't add the percentage label and status text in a structured way.

Proposal: data-progress-label="70% complete" or a wrapper pattern?

Add this to your output so the human can evaluate whether to extend the vocabulary.

Why This Works

1. Semantic HTML is natural for you — Expressing structure through language is what you do. <article> is a concept, not a memorized string.

2. Data attributes are self-documenting — data-task="done" says what it means. You generate it from understanding, not from API memorization.

3. The vocabulary is finite — ~30 tags + ~15 data-attributes. Fits in your context. You can learn this completely.

4. Separation of concerns is enforced — You can't touch CSS even if you wanted to. Structure only. This constraint prevents chaos.

5. Multiple sessions, consistent output — The design lives in CSS files, not in your memory. You can forget everything about appearance and the pages still look consistent.

Design Philosophy

The framework's power comes from constraint:

Write semantic HTML. Use data-attributes for vault concepts. Never write style=. Never invent classes.

This isn't a limitation—it's a liberation. You don't need to think about colors, fonts, spacing, or visual design. Just express the structure clearly. The framework handles the rest.

---

This directive is your complete guide. If it's not documented here, ask before using it.