Port vault section (5 pages) and docs section (11 pages)

- 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
2026-04-10 18:40:50 +02:00 · 2026-04-10 18:40:50 +02:00 · da1d02ccd1
commit da1d02ccd1
parent cbe44d845c
19 changed files with 2462 additions and 1 deletions
--- a/content/docs/semantic-html.md
+++ b/content/docs/semantic-html.md
@ -0,0 +1,272 @@
+---
+title: "Semantic HTML"
+description: "How ASW styles plain HTML elements without class names — typography, links, tables, forms, and interactive elements."
+type: docs
+weight: 70
+date: 2026-04-09
+tags: ["semantic-html", "css", "reference"]
+ai-disclosure: "generated"
+ai-model: "claude-sonnet-4-5"
+ai-provider: "Anthropic"
+
+---
+
+ASW's `02-semantic.css` layer styles native HTML elements directly. Write valid semantic HTML; it looks right without adding any attributes or classes.
+
+---
+
+## Typography
+
+### Headings
+
+All six heading levels are styled with distinct sizes, weights, and colours drawn from ASW tokens.
+
+```html
+<h1>Page Title</h1>
+<h2>Section Heading</h2>
+<h3>Subsection</h3>
+<h4>Group Header</h4>
+<h5>LABEL</h5>        <!-- uppercase, spaced -->
+<h6>MICRO LABEL</h6>  <!-- uppercase, spaced, smaller -->
+```
+
+`h5` and `h6` receive `text-transform: uppercase` and `letter-spacing` to serve as section labels rather than structural headings. Headings following content elements get extra top margin (`--type-space-top`) automatically.
+
+### Body text
+
+`<p>`, `<ol>`, `<ul>`, `<dl>` inherit body colour and weight. Spacing uses `--type-space`.
+
+```html
+<p>Regular paragraph text.</p>
+<p><strong>Bold</strong> and <em>italic</em> inline.</p>
+<p><mark>Highlighted text</mark> using the native mark element.</p>
+<p><del>Removed</del> and <ins>inserted</ins> content.</p>
+```
+
+### Blockquote
+
+```html
+<blockquote>
+  <p>The thread continues even when the needle changes.</p>
+  <footer>— Vigilio Desto</footer>
+</blockquote>
+```
+
+Left border in `var(--border)`. Footer text is muted.
+
+### Inline elements
+
+| Element | Rendering |
+|---------|-----------|
+| `<strong>`, `<b>` | Bolder weight |
+| `<mark>` | Yellow highlight (`var(--mark-bg)`) |
+| `<del>` | Red (`var(--accent-red)`) |
+| `<ins>` | Body colour, no underline |
+| `<abbr title="...">` | Dotted bottom border, help cursor |
+| `<sub>`, `<sup>` | Standard subscript / superscript |
+| `<small>` | `0.875em` |
+| `<kbd>` | Keyboard key pill (`var(--kbd-bg)`) |
+
+---
+
+## Links
+
+```html
+<a href="/docs/">Standard link</a>
+<a href="/docs/" role="button">Link styled as button</a>
+```
+
+Links receive `var(--link)` colour with underline offset. Hover and focus states transition smoothly. `focus-visible` shows a box-shadow ring. Links with `role="button"` are excluded from the default link styles.
+
+---
+
+## Navigation
+
+`<nav>` uses flexbox by default. Direct `<ul>` children become horizontal pill lists.
+
+```html
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/docs/">Docs</a></li>
+    <li><a href="/lab/">Lab</a></li>
+  </ul>
+</nav>
+```
+
+`<nav>`, `<header>`, `<footer>`, `<label>`, `<th>` use `var(--font-ui)` instead of the prose font — they're structural elements, not reading text.
+
+---
+
+## Lists
+
+```html
+<ul>
+  <li>Square bullets (not discs)</li>
+  <li>Inherits body colour and weight</li>
+</ul>
+
+<ol>
+  <li>Numbered list</li>
+  <li>Standard appearance</li>
+</ol>
+```
+
+Nested lists have no additional top/bottom margin.
+
+---
+
+## Tables
+
+```html
+<table>
+  <thead>
+    <tr>
+      <th>Name</th>
+      <th>Value</th>
+      <th>Source</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>--accent</code></td>
+      <td>green-5</td>
+      <td>Open Props</td>
+    </tr>
+  </tbody>
+  <tfoot>
+    <tr>
+      <td colspan="3">Token reference — agentic.css v1.0</td>
+    </tr>
+  </tfoot>
+</table>
+```
+
+Full-width. Bottom borders on `<td>`, stronger border under `<thead>`. `<tfoot>` gets a top border instead of a bottom border.
+
+---
+
+## Code
+
+```html
+<!-- Inline code -->
+<p>Use <code>data-layout="docs"</code> for the three-column scaffold.</p>
+
+<!-- Code block -->
+<pre><code>body {
+  background: var(--surface);
+  color: var(--text);
+}</code></pre>
+
+<!-- Keyboard shortcut -->
+<kbd>Ctrl</kbd> + <kbd>K</kbd>
+```
+
+`<code>`, `<kbd>`, `<samp>` all use `var(--font-mono)` with a subtle surface background. `<pre>` is a scrollable block with consistent padding.
+
+---
+
+## Details / Summary
+
+CSS-only accordion. No JavaScript.
+
+```html
+<details>
+  <summary>How does the token cascade work?</summary>
+  <p>Open Props provides the base scale. ASW aliases those to semantic names. Components reference the semantic aliases.</p>
+</details>
+
+<details open>
+  <summary>This one starts open</summary>
+  <p>Content visible on load.</p>
+</details>
+```
+
+The chevron (`▸`) rotates on open. Chevron and summary colour transition smoothly. The `open` attribute is the only state needed.
+
+---
+
+## Dialog / Modal
+
+Native `<dialog>` element with backdrop blur.
+
+```html
+<dialog id="my-dialog">
+  <article>
+    <header>
+      <button rel="prev" aria-label="Close"></button>
+      <h3>Modal Title</h3>
+    </header>
+    <p>Modal content goes here.</p>
+    <footer>
+      <button onclick="document.getElementById('my-dialog').close()">Close</button>
+    </footer>
+  </article>
+</dialog>
+
+<button onclick="document.getElementById('my-dialog').showModal()">Open modal</button>
+```
+
+The backdrop uses `var(--modal-overlay)` with `var(--modal-backdrop)` blur filter. Adds `.modal-is-open` to `<body>` to lock scroll (must be done via JavaScript). Animations respect `prefers-reduced-motion`.
+
+---
+
+## Progress
+
+```html
+<!-- Determinate -->
+<progress value="65" max="100">65%</progress>
+
+<!-- Indeterminate -->
+<progress>Loading…</progress>
+```
+
+Styled with `var(--accent)` fill, `var(--track-bg)` rail. Indeterminate progress animates (respects `prefers-reduced-motion`).
+
+---
+
+## Figure
+
+```html
+<figure>
+  <img src="/images/token-diagram.png" alt="Token hierarchy diagram">
+  <figcaption>ASW's three-layer token cascade</figcaption>
+</figure>
+```
+
+`<figcaption>` is muted and smaller than body text.
+
+---
+
+## Horizontal rule
+
+```html
+<hr>
+```
+
+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 `<main>`.
+
+---
+
+## 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