haac-aikit 0.9.0 → 0.10.0

package/README.md

@@ -6,6 +6,13 @@
 
 One command drops a working AI-coding setup into any repo — rules, skills, safety hooks, subagents, MCP stub, CI templates — for Claude Code, Cursor, Copilot, Windsurf, Aider, Gemini CLI, and Codex.
 
+> [!TIP]
+> **Just want HTML output from Claude Code?** Skip the full kit and install only the html-artifacts skill + 20 templates:
+>
+> ```bash
+> npx haac-aikit init html
+> ```
+
 ## Quickstart
 
 ```bash

package/catalog/skills/tier1/html-artifacts.md

@@ -1,7 +1,7 @@
 ---
 name: html-artifacts
 description: Use when producing structured output that benefits from rich layout, comparison, drill-in, or interaction — specs, plans, PR reviews, design systems, prototypes, diagrams, decks, research explainers, reports, and custom editors. Scaffolds from 20 forked reference templates at `.aikit/templates/html-artifacts/` and fills them with project context. Maintains a gallery at `.aikit/artifacts/index.html`.
-version: "2.0.0"
+version: "2.3.0"
 source: haac-aikit
 license: MIT
 inspired-by: https://thariqs.github.io/html-effectiveness (templates forked with permission, 2026-05-12)
@@ -35,6 +35,42 @@ When conditions match but the user didn't ask for HTML, say one sentence and wai
 - **Provenance footer**: every generated artifact ends with `Sources: … — generated <ISO timestamp>`
 - **AUTO-GENERATED pill**: top-right badge on agent-produced artifacts so readers know the origin
 - **Prompt callout**: exploration / planning artifacts preserve the originating user request in a cream-tinted box at top
+- **Density-adaptive rendering**: when the artifact's total visible items (milestones + risks + cards + rows across all sections) is ≤ 6, drop decorations designed for dense pages — section numbers, tag chips, colored dot indicators, multi-column summary cards. These visuals were tuned for ~12-item artifacts; on sparse content they read as noise instead of hierarchy. The point of structure is signal; if there's little content, decoration buries it.
+- **Decision callout first**: any artifact that asks the user to decide something starts with a "Decision needed" block at the top — the call-to-action in one sentence, options in chips (`A —` / `B —`), the recommendation marked. Don't make decision-makers scroll to find what to approve.
+
+## Accessibility (a11y)
+
+Decision documents get read on phones, with screen readers, in high-contrast mode, by keyboard-only users. The bar is the same as the voice rule — make the artifact work for the actual reading environment, not just a desktop browser.
+
+**Hard rules:**
+
+1. **Landmark roles** — wrap top-level structure in `<main>`, `<nav>`, `<article>`, `<aside>`. Screen readers use these to navigate; readers without them have to crawl the document linearly.
+2. **Alt text on every diagram and icon** — inline `<svg>` gets `<title>` + `aria-labelledby` or `aria-label`; `<img>` gets `alt="..."`. Purely decorative icons get `aria-hidden="true"` so they don't announce as noise.
+3. **Heading hierarchy never skips levels** — `<h1>` → `<h2>` → `<h3>`. Exactly one `<h1>` per artifact (the title).
+4. **Native form controls only** — `<input>` paired with `<label for="...">`, `<button>` for buttons, native `<select>`. No div-button hacks.
+5. **Color contrast ≥ 4.5:1 for body text, ≥ 3:1 for large text** — design tokens already meet WCAG AA; don't override per-artifact in ways that break the ratio.
+6. **Keyboard focus visible** — never `outline: none` without a `:focus-visible` replacement that meets contrast.
+
+## Voice & plain-language rule
+
+The default reader is a smart non-specialist taking a decision. They should understand every sentence on first read without expanding tooltips, looking up jargon, or having prior domain context.
+
+**Four sub-rules:**
+
+1. **One concept per sentence** — no "X with Y and Z" compounds.
+2. **Plain-language verb + concrete object** — "Load images only when the reader scrolls to them" beats "Implement lazy-loading via IntersectionObserver."
+3. **Jargon lives in tag chips, `<code>` spans, or collapsed `<details>`** — never in the main reading path.
+4. **Concrete first, abstract term in parens** — "Make sure failed requests retry safely (idempotent)" beats "Idempotent retry on failure."
+
+**Three side-by-side examples (bad → good):**
+
+| Bad | Good |
+| --- | --- |
+| "Schema & API contract — tRPC router stubs reviewed before anything else lands" | "Define the API the backend will expose. Review the contract before any UI work." |
+| "Optimistic insert with rollback on failure, one level of nesting only" | "Show the comment immediately. Roll back if the server rejects it. One level of replies — no deeper threads." |
+| "Fan-out via realtime channel, per-user read cursors track unread state" | "When a card is open, listen for new comments on it. Push updates to everyone watching." |
+
+The technical details (`tRPC`, `optimistic insert`, `fan-out`) still appear in the artifact — but as tag chips beneath the prose, not in the reading path. The visible layer is decision-grade scannable; the chip layer keeps the artifact grep-able and AI-readable.
 
 ## Pattern playbook (9 patterns, aligned with the source)
 
@@ -42,7 +78,7 @@ When conditions match but the user didn't ask for HTML, say one sentence and wai
 **Templates**: `01-exploration-code-approaches.html`, `02-exploration-visual-designs.html`, `16-implementation-plan.html`
 **Use for**: comparing N approaches, exploring visual directions, handing off a plan
 **Concrete techniques**: numbered approach badges (`01`/`02`/`03`) in oat chips · equal-width code blocks for visual symmetry · pro/con tables with colored dot bullets (olive=pro, clay=con) · chip metrics footer (bundle, testability, reuse, SSR safety) · recommendation callout with left clay border + serif 22px · light/dark toggle via single `:root` swap · numbered milestone rows with date columns on left · phase cards with package chips · risks table (RISK / SEV / MITIGATION) · "Decide with · person · before slice N" footer on open questions
-**Must-haves**: preserve the originating prompt as a top callout; numbered section dots if > 4 sections
+**Must-haves**: preserve the originating prompt as a top callout; numbered section dots if > 4 sections; **Decision needed block at the very top** — a clay-bordered card stating the call-to-action, the options considered (chips: `A —` / `B —`), and which one is recommended. Buried decisions are the failure mode this prevents.
 
 ### 2. Code Review & Understanding
 **Templates**: `03-code-review-pr.html`, `17-pr-writeup.html`, `04-code-understanding.html`
@@ -105,6 +141,9 @@ When conditions match but the user didn't ask for HTML, say one sentence and wai
 - Missing keyboard nav for editors — native form controls, not div-clicks
 - Missing AUTO-GENERATED badge on agent-produced artifacts — readers deserve to know
 - Missing provenance footer — "where did these numbers come from?" should always be answerable
+- **Jargon-heavy main prose** — using `tRPC`, `fan-out`, `idempotent`, `IntersectionObserver` in the reading path makes the artifact unreadable for non-specialists. Plain-language verb + concrete object in prose; technical terms in tag chips and code blocks.
+- **Decision buried below the fold** — artifact asks the user to approve, choose, or sign off but the call-to-action lives in Milestones or Risks, not at the top. Decision-makers shouldn't have to scroll to find what they're approving.
+- **Missing alt text / aria-label on SVG and `<img>`** — diagrams and charts become invisible to screen readers, low-vision users, and search / indexing. Every visual element gets a text equivalent.
 
 ## Template scaffolding
 
@@ -117,15 +156,26 @@ When conditions match but the user didn't ask for HTML, say one sentence and wai
 1. **Read the manifest first**: `Read .aikit/templates/html-artifacts/MANIFEST.json`. Find the entry whose `category` matches the pattern from the playbook above and whose `slug` best matches the user's intent.
 2. **Read the matching template**: `Read .aikit/templates/html-artifacts/<file>.html` (the `file` field from the manifest entry). This is non-optional. If the file is missing, ask the user to run `aikit sync`; do not proceed without it.
 3. **Gather real project context**: run the appropriate commands — `git diff main...HEAD`, `git log --since=...`, read files mentioned in the prompt, etc. Replace the template's placeholder content with these real facts.
-4. **Preserve structure verbatim** when writing the filled artifact:
+4. **Prune irrelevant sections before filling**. Scan the template's `<section>` blocks; for any not required by the user's intent, OMIT them from the filled artifact entirely (don't render them with empty placeholders). Aim for the minimum sections that carry signal — keeping all sections "just in case" forces the reader to skim each one to decide whether it's relevant. Section-keep guide:
+
+   | Templates | Always include | Optional (only if relevant) |
+   | --- | --- | --- |
+   | `01`, `02`, `16` (Exploration & Planning) | Milestones / Approaches + Risks | Data flow §02 (only if client↔server movement) · Mockups §03 (only if UI work) · Key code §04 (only if specific patterns to highlight) |
+   | `03`, `17`, `04` (Code Review) | PR header · Per-file details · Comments | Risk map (only if multiple severities) · Module-map SVG (only for arch reviews) |
+   | `11`, `12` (Reports) | Metric band + main table | Velocity chart (only if time series) · Incident timeline (only for incidents) |
+   | `18`, `19`, `20` (Editors) | Real columns + export button | Dependency warnings (only if dependencies) |
+   | All others | Core content sections of the pattern | Any section where placeholders would carry no signal |
+
+5. **Preserve structure verbatim** when writing the filled artifact:
    - All `:root` CSS variables (`--clay`, `--slate`, `--ivory`, `--oat`, `--olive`, `--gray-*`)
    - All class names, layout grids, and microinteraction conventions
    - All cross-cutting techniques (sticky positioning, `scroll-margin-top`, `<details>` collapsibles, native form controls)
    - The pattern's visual language (severity colors, badge styles, dot indicators, monospace meta text)
-5. **Add required `<head>` elements**: `<title>`, `<meta name="description">`, and `<meta name="aikit-pattern" content="...">` with one of: `Exploration`, `Code Review`, `Design`, `Prototype`, `Illustrations`, `Deck`, `Research`, `Report`, `Editor`.
-6. **Add AUTO-GENERATED pill** top-right and **provenance footer** (`Sources: ... — generated <ISO timestamp>`).
-7. **Save** to `.aikit/artifacts/NN-<slug>.html` (increment `NN` from existing files).
-8. **Regenerate gallery index** per the protocol below.
+   - **Apply the Voice & plain-language rule** when writing prose into content nodes (`<p>`, `<h3>`, milestone bodies, risk explanations). Jargon goes in tag chips, `<code>` spans, or `<details>` — never in main prose.
+6. **Add required `<head>` elements**: `<title>`, `<meta name="description">`, and `<meta name="aikit-pattern" content="...">` with one of: `Exploration`, `Code Review`, `Design`, `Prototype`, `Illustrations`, `Deck`, `Research`, `Report`, `Editor`.
+7. **Add AUTO-GENERATED pill** top-right and **provenance footer** (`Sources: ... — generated <ISO timestamp>`).
+8. **Save** to `.aikit/artifacts/NN-<slug>.html` (increment `NN` from existing files).
+9. **Regenerate gallery index** per the protocol below.
 
 ### User-driven scaffolding (alternative)
 

package/catalog/templates/html-artifacts/01-exploration-code-approaches.html

@@ -254,7 +254,7 @@
   </style>
 </head>
 <body>
-  <div class="page">
+  <main class="page">
 
     <header class="page-head">
       <div class="eyebrow">Exploration · Birchline web client</div>
@@ -448,6 +448,6 @@
       </p>
     </aside>
 
-  </div>
+  </main>
 </body>
 </html>

package/catalog/templates/html-artifacts/02-exploration-visual-designs.html

@@ -392,7 +392,7 @@
     </div>
   </div>
 
-  <div class="page">
+  <main class="page">
 
     <header class="page-head">
       <div class="eyebrow">Exploration · Empty states</div>
@@ -502,7 +502,7 @@
       </article>
 
     </section>
-  </div>
+  </main>
 
   <script>
     const stages = document.querySelectorAll('.stage');

package/catalog/templates/html-artifacts/03-code-review-pr.html

@@ -395,7 +395,7 @@
 </style>
 </head>
 <body>
-<div class="page">
+<main class="page">
 
   <header class="pr-head">
     <div class="repo-line">birchline/web · Pull Request #247</div>
@@ -620,7 +620,7 @@
     </ul>
   </footer>
 
-</div>
+</main>
 
 <script>
   // Briefly highlight a file card when reached via the risk-map anchors.

package/catalog/templates/html-artifacts/05-design-system.html

@@ -353,7 +353,7 @@
 </style>
 </head>
 <body>
-<div class="page">
+<main class="page">
 
   <header>
     <h1>Birchline design system</h1>
@@ -624,6 +624,6 @@
     </div>
   </section>
 
-</div>
+</main>
 </body>
 </html>

package/catalog/templates/html-artifacts/06-component-variants.html

@@ -360,7 +360,7 @@
 </style>
 </head>
 <body>
-<div class="page">
+<main class="page">
 
   <header>
     <h1>Card variant matrix</h1>
@@ -553,7 +553,7 @@
     <pre id="snippet">// hover a card to preview its props</pre>
   </div>
 
-</div>
+</main>
 
 <script>
   (function () {

package/catalog/templates/html-artifacts/07-prototype-animation.html

@@ -346,7 +346,7 @@
 </style>
 </head>
 <body>
-<div class="wrap">
+<main class="wrap">
 
   <header>
     <div class="eyebrow">Birchline / prototype / micro-interaction</div>
@@ -363,7 +363,7 @@
     <div class="stage">
       <div class="task" id="task">
         <div class="check">
-          <svg viewBox="0 0 16 16"><path d="M3 8.5 L6.5 12 L13 4.5"/></svg>
+          <svg viewBox="0 0 16 16" aria-hidden="true"><path d="M3 8.5 L6.5 12 L13 4.5"/></svg>
         </div>
         <span class="label">Send weekly digest</span>
         <span class="due">Fri</span>
@@ -433,7 +433,7 @@
                      transition-delay: 600ms; }</pre>
   </section>
 
-</div>
+</main>
 
 <script>
   var task = document.getElementById('task');

package/catalog/templates/html-artifacts/08-prototype-interaction.html

@@ -243,7 +243,7 @@
 </style>
 </head>
 <body>
-<div class="wrap">
+<main class="wrap">
 
   <header>
     <div class="eyebrow">Birchline / prototype / interaction</div>
@@ -335,7 +335,7 @@
     </div>
 
   </div>
-</div>
+</main>
 
 <script>
   var list = document.getElementById('list');

package/catalog/templates/html-artifacts/09-slide-deck.html

@@ -368,6 +368,8 @@
 </head>
 <body>
 
+  <main>
+
   <!-- ============================================================
        Slide 1 — Title
        ============================================================ -->
@@ -555,6 +557,8 @@
     </div>
   </section>
 
+  </main>
+
   <!-- ============================================================
        Slide counter
        ============================================================ -->

package/catalog/templates/html-artifacts/10-svg-illustrations.html

@@ -186,7 +186,7 @@
 </style>
 </head>
 <body>
-<div class="sheet">
+<main class="sheet">
 
   <header>
     <h1>Background jobs — header illustrations</h1>
@@ -203,7 +203,8 @@
        ============================================================ -->
   <figure>
     <div class="canvas">
-      <svg id="ill-queue" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320">
+      <svg id="ill-queue" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320" role="img" aria-labelledby="svg-queue-title">
+        <title id="svg-queue-title">Background job queue illustration showing five pending jobs and a worker pulling the next job for processing</title>
         <defs>
           <style>
             .m { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: 11px; }
@@ -265,7 +266,8 @@
        ============================================================ -->
   <figure>
     <div class="canvas">
-      <svg id="ill-retry" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320">
+      <svg id="ill-retry" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320" role="img" aria-labelledby="svg-retry-title">
+        <title id="svg-retry-title">Retry with backoff timeline showing four attempts on a job, with exponential delays of one, two, and four seconds before the fourth succeeds</title>
         <defs>
           <style>
             .m { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: 11px; }
@@ -332,7 +334,8 @@
        ============================================================ -->
   <figure>
     <div class="canvas">
-      <svg id="ill-fanout" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320">
+      <svg id="ill-fanout" xmlns="http://www.w3.org/2000/svg" width="720" height="320" viewBox="0 0 720 320" role="img" aria-labelledby="svg-fanout-title">
+        <title id="svg-fanout-title">Fan-out diagram showing an enqueue batch dispatching to multiple parallel worker lanes for concurrent job processing</title>
         <defs>
           <style>
             .m { font-family: ui-monospace, "SF Mono", Menlo, Consolas, monospace; font-size: 11px; }
@@ -471,7 +474,7 @@
     </ul>
   </section>
 
-</div>
+</main>
 
 <script>
   document.querySelectorAll('.dl').forEach(function (btn) {

package/catalog/templates/html-artifacts/11-status-report.html

@@ -302,7 +302,7 @@
 </style>
 </head>
 <body>
-  <div class="page">
+  <main class="page">
 
     <header>
       <div class="header-top">
@@ -523,6 +523,6 @@
       &nbsp;&mdash;&nbsp; generated Mar 16 2025 18:02
     </footer>
 
-  </div>
+  </main>
 </body>
 </html>

package/catalog/templates/html-artifacts/12-incident-report.html

@@ -393,7 +393,7 @@
     <a href="#actions">Action items</a>
   </nav>
 
-  <div class="page">
+  <main class="page">
 
     <header>
       <div class="inc-id">INC-2025-0412</div>
@@ -591,6 +591,6 @@
       Authored from on-call notes + alert history &middot; reviewed by Devon Park, Mira Okafor
     </footer>
 
-  </div>
+  </main>
 </body>
 </html>

package/catalog/templates/html-artifacts/13-flowchart-diagram.html

@@ -158,7 +158,7 @@
 </style>
 </head>
 <body>
-<div class="sheet">
+<main class="sheet">
 
   <header>
     <div class="eyebrow">Illustrations &amp; Diagrams · Flowchart</div>
@@ -173,7 +173,8 @@
 
     <div>
       <div class="canvas">
-        <svg class="flow" viewBox="0 0 620 920">
+        <svg class="flow" viewBox="0 0 620 920" role="img" aria-labelledby="svg-flow-title">
+          <title id="svg-flow-title">Deploy pipeline flowchart for git push main showing CI steps, test gates, image build, deploy stages, and rollback path</title>
           <defs>
             <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
               <path d="M0,0 L10,5 L0,10 z" fill="#87867F"/>
@@ -293,7 +294,7 @@
     </aside>
 
   </div>
-</div>
+</main>
 
 <script>
 const DETAIL = {

package/catalog/templates/html-artifacts/15-research-concept-explainer.html

@@ -191,7 +191,7 @@
 
     <div class="demo">
       <div class="demo-grid">
-        <svg class="ring" id="ring" viewBox="0 0 260 260"></svg>
+        <svg class="ring" id="ring" viewBox="0 0 260 260" role="img" aria-labelledby="svg-ring-title"><title id="svg-ring-title">Consistent hashing ring diagram with nodes and keys placed around a circle; keys assign to the next clockwise node</title></svg>
         <div class="controls">
           <div class="row">
             <label>nodes</label>

package/catalog/templates/html-artifacts/16-implementation-plan.html

@@ -383,7 +383,7 @@
   </style>
 </head>
 <body>
-  <div class="page">
+  <main class="page">
 
     <header class="page-head">
       <div class="eyebrow">Implementation plan · Birchline web client</div>
@@ -462,7 +462,8 @@
       <p class="sec-intro">Optimistic write path on the left, fan-out on the right. The read cursor update is fire-and-forget — we never block the thread render on it.</p>
 
       <div class="diagram">
-        <svg viewBox="0 0 860 340" xmlns="http://www.w3.org/2000/svg">
+        <svg viewBox="0 0 860 340" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="svg-dataflow-title">
+          <title id="svg-dataflow-title">Data flow diagram for comment threads showing optimistic write from CommentComposer through tRPC to the database and realtime fan-out to subscribers</title>
           <defs>
             <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
               <path d="M0,0 L10,5 L0,10 z" fill="#87867F"/>
@@ -697,6 +698,6 @@
       </div>
     </section>
 
-  </div>
+  </main>
 </body>
 </html>

package/catalog/templates/html-artifacts/18-editor-triage-board.html

@@ -291,7 +291,7 @@
 </style>
 </head>
 <body>
-<div class="wrap">
+<main class="wrap">
 
   <header>
     <div class="eyebrow">Birchline / editor / triage</div>
@@ -314,7 +314,7 @@
 
   <div class="board" id="board"></div>
 
-</div>
+</main>
 
 <script>
   // ---------- data ----------

package/catalog/templates/html-artifacts/19-editor-feature-flags.html

@@ -302,7 +302,7 @@
 </style>
 </head>
 <body>
-<div class="wrap">
+<main class="wrap">
 
   <header>
     <div class="eyebrow">Birchline / editor / feature-flags</div>
@@ -334,7 +334,7 @@
     </aside>
   </div>
 
-</div>
+</main>
 
 <script>
 "use strict";

package/catalog/templates/html-artifacts/20-editor-prompt-tuner.html

@@ -287,7 +287,7 @@
 </style>
 </head>
 <body>
-<div class="wrap">
+<main class="wrap">
 
   <header>
     <div class="eyebrow">Birchline / editor / prompt-tuner</div>
@@ -328,7 +328,7 @@
 
   <footer>Highlighted slots fill from each sample's ticket fields. Anything underlined in dashed clay isn't a known field and will pass through unfilled.</footer>
 
-</div>
+</main>
 
 <script>
 (function () {