feat: legacy import — packs, examples, lab, themes, docs, lineage
Import from agentic-semantic-web/ into restructured repo: - 7 packs (apache, caddy, flask, hugo, nginx, pandoc, python) - shared error pages (403-503) - 17 lab experiments (boilerplate, charts, misc) - 31 example pages (charts, components, content, layout, vault) - 2 themes (garden, trentuna stub) - 4 docs (llms.txt, vocabulary, philosophy, agent-directive) - lineage.md (Pico/Open Props/Charts.css history) - Hugo mounts for lab/ and examples/ All agentic.css references updated to asw.css. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
e9895cf90d
commit
86464f3e21
GPG key ID:
F6E479DEFAB84D6E
100 changed files with 14700 additions and 4 deletions
393
docs/agent-directive.md
Normal file
393
docs/agent-directive.md
Normal file
|
|
@ -0,0 +1,393 @@
|
|||
# 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:
|
||||
|
||||
```html
|
||||
<!-- ✅ 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](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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<a href="/tag/foundational" data-tag>foundational</a>
|
||||
<a href="/tag/architecture" data-tag>architecture</a>
|
||||
```
|
||||
|
||||
Vault tags or categorizations.
|
||||
|
||||
### Text Utilities
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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
|
||||
```html
|
||||
<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:
|
||||
|
||||
```js
|
||||
(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:
|
||||
|
||||
```html
|
||||
<!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)
|
||||
```html
|
||||
<!-- 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
|
||||
```html
|
||||
<!-- 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
|
||||
```html
|
||||
<!-- WRONG -->
|
||||
<div class="navigation">...</div>
|
||||
|
||||
<!-- RIGHT -->
|
||||
<nav>...</nav>
|
||||
```
|
||||
|
||||
## What to DO
|
||||
|
||||
### Use semantic HTML for everything HTML provides
|
||||
```html
|
||||
<!-- 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
|
||||
```html
|
||||
<!-- 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
|
||||
```html
|
||||
<!-- 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.**
|
||||
Loading…
Add table
Add a link
Reference in a new issue