asw/docs/vocabulary.md

# ASW Data-Attribute Vocabulary

**Quick reference for all data-attributes in the Agentic Semantic Web framework.**

## Vault-Native Concepts

| Attribute | Values | Purpose | Example |
|-----------|--------|---------|---------|
| `data-wikilink` | (none) | Mark as vault note reference | `<span data-wikilink>Note Name</span>` |
| `data-unresolved` | (none) | Mark wikilink target doesn't exist | `<span data-wikilink data-unresolved>Missing</span>` |
| `data-task` | `todo`, `done`, `blocked` | Task state | `<div data-task="done">Finished</div>` |
| `data-status` | `awake`, `sleeping`, `blocked`, `unknown` | System/service status | `<span data-status="awake">Active</span>` |
| `data-callout` | `note`, `warning`, `error`, `tip` | Callout/admonition type | `<div data-callout="warning">...</div>` |
| `data-callout-title` | (none) | Title for callout | `<span data-callout-title>Warning</span>` |
| `data-session` | (none) | Wrapper for session metadata | `<div data-session>...</div>` |
| `data-mode` | `autonomous`, `interactive` | Session type | `<span data-mode="autonomous">Auto</span>` |
| `data-session-meta` | (none) | Session timestamp/metadata | `<span data-session-meta>2026-03-26</span>` |
| `data-hash` | (none) | Git commit hash | `<span data-hash>a3f7b2c</span>` |
| `data-tag` | (none) | Vault tag | `<a data-tag href="/tag/architecture">architecture</a>` |

## Text Utilities

| Attribute | Values | Purpose | Example |
|-----------|--------|---------|---------|
| `data-text` | `mono` | Monospace font | `<span data-text="mono">fixed-width</span>` |
| `data-text` | `dim` | Muted color | `<span data-text="dim">secondary text</span>` |
| `data-text` | `accent` | Accent color | `<span data-text="accent">highlighted</span>` |
| `data-text` | `mono dim` | Combined (space-separated) | `<span data-text="mono dim">0x4A3F</span>` |

## Layout Patterns

| Attribute | Values | Purpose | Example |
|-----------|--------|---------|---------|
| `data-layout` | `grid-2` | Two-column grid (stacks on mobile) | `<div data-layout="grid-2"><div>Col1</div><div>Col2</div></div>` |
| `data-layout` | `card-grid` | Responsive card wrap (2-col flex) | `<div data-layout="card-grid"><article>…</article><article>…</article></div>` |
| `data-layout` | `stats` | Horizontal metrics bar | `<div data-layout="stats"><div><span data-stat="value">42</span><span data-stat="label">things</span></div></div>` |
| `data-layout` | `inline` | Inline definition list | `<dl data-layout="inline"><dt>Key</dt><dd>Value</dd></dl>` |

## Semantic Roles

| Attribute | Values | Purpose | Example |
|-----------|--------|---------|---------|
| `data-role` | `command-box` | Terminal command display | `<div data-role="command-box"><span class="prefix">$</span><code>ls</code></div>` |
| `data-role` | `status-card` | System status card | `<div data-role="status-card"><h3>Status</h3>...</div>` |
| `data-role` | `timeline` | Chronological event list | `<div data-role="timeline"><div>Event 1</div></div>` |
| `data-role` | `diff` | Code diff display | `<pre data-role="diff"><span class="add">+ line</span></pre>` |

## CSS Custom Properties (Design Tokens)

The framework uses semantic design tokens that map to Pico's internal variables. For complete reference, see [design-tokens.md](design-tokens.md).

### Quick Reference (Key Tokens)

**Colors:**
```css
--accent: #22c55e;          /* Primary accent (green) */
--accent-blue: #3b82f6;     /* Links, wikilinks */
--accent-orange: #f59e0b;   /* Warnings, todo */
--accent-red: #ef4444;      /* Errors, blocked */
--bg-primary: #0a0a0a;      /* Main background */
--text-primary: #e5e5e5;    /* Main text */
```

**Typography:**
```css
--font-body: 'Inter', system-ui, sans-serif;
--font-mono: 'JetBrains Mono', ui-monospace, monospace;
```

**See [design-tokens.md](design-tokens.md) for:**
- Complete token reference (15+ tokens)
- How to create custom themes
- Light/dark switching patterns
- Override best practices

## Pico CSS Requirements

ASW builds on Pico CSS. The only class Pico uses:

| Class | Element | Purpose |
|-------|---------|---------|
| `container` | `<main>` | Centered single-column layout (max-width, padding) |

**Everything else is semantic HTML.** No classes needed.

## Semantic HTML Cheat Sheet

Pico styles these automatically (incomplete list):

**Structure:** `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`, `<header>`, `<footer>`
**Interactive:** `<details>`, `<summary>`, `<dialog>`, `<button>`, `<a>`
**Forms:** `<form>`, `<input>`, `<textarea>`, `<select>`, `<label>`, `<fieldset>`
**Data:** `<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`, `<dl>`, `<dt>`, `<dd>`
**Content:** `<h1>`-`<h6>`, `<p>`, `<ul>`, `<ol>`, `<li>`, `<blockquote>`, `<figure>`, `<figcaption>`
**Inline:** `<strong>`, `<em>`, `<mark>`, `<code>`, `<kbd>`, `<small>`, `<time>`
**Code:** `<pre>`, `<code>`
**Misc:** `<progress>`, `<meter>`, `<hr>`

## Usage Patterns

### Task List
```html
<ul>
  <li data-task="done">Complete documentation</li>
  <li data-task="todo">Write examples</li>
  <li data-task="blocked">Waiting on approval</li>
</ul>
```

### Status Display
```html
<dl data-layout="inline">
  <dt>Vigilio</dt>
  <dd><span data-status="awake" data-text="mono">ACTIVE</span></dd>
  <dt>Shelley</dt>
  <dd><span data-status="sleeping" data-text="mono">IDLE</span></dd>
</dl>
```

### Callout with Title
```html
<div data-callout="warning">
  <span data-callout-title>Important</span>
  <p>This requires attention before proceeding.</p>
</div>
```

### Session Metadata
```html
<div data-session>
  Session <span data-text="mono">#47</span>
  <span data-mode="autonomous">autonomous</span>
  <span data-session-meta>2026-03-26 14:30 UTC</span>
  <span data-hash>a3f7b2c</span>
</div>
```

### Two-Column Layout
```html
<div data-layout="grid-2">
  <div>
    <h2>Column 1</h2>
    <p>Content for the left side.</p>
  </div>
  <div>
    <h2>Column 2</h2>
    <p>Content for the right side.</p>
  </div>
</div>
```

### Command Box
```html
<div data-role="command-box">
  <span class="prefix">$</span>
  <code>npm install agentic-semantic-web</code>
</div>
```

## Conventions

1. **All data values in monospace** — Status, session numbers, timestamps, file paths, hashes. Use `data-text="mono"` or wrap in `<code>`.

2. **Combine attributes freely** — `data-text="mono dim"`, `data-wikilink data-unresolved`, etc.

3. **Semantic HTML first** — If HTML has a tag for it, use that. Data-attributes are for concepts HTML doesn't cover.

4. **No inline styles (with exception)** — `style=""` attributes are forbidden EXCEPT for CSS custom properties representing data values:
   ```html
   <!-- ✅ Allowed: CSS variables for data -->
   <div style="--size: 0.8; --value: 42;">Chart bar</div>

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

5. **No invented classes** — The vocabulary is finite and documented here. Don't extend it without documenting.

## Extending the Vocabulary

Need a new data-attribute? Document:
1. What concept you're expressing
2. Why existing patterns don't work
3. Proposed attribute name and values
4. CSS styling needed (if you know)

Example proposal:
```
Concept: Progress indicator with label and percentage
Why existing doesn't work: <progress> shows bar but no structured label
Proposal: data-progress-label="70% complete" or wrapper pattern
CSS: (defer to designer)
```

---

**This is the complete vocabulary.** If it's not listed here, ask before using it.