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.

Quick Reference (Key Tokens)

Colors:

--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:

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

See 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

<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

<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

<div data-callout="warning">
  <span data-callout-title>Important</span>
  <p>This requires attention before proceeding.</p>
</div>

Session Metadata

<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

<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

<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:

   <!-- ✅ 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.