@adia-ai/web-components 0.8.6 → 0.8.7

package/patterns/agent-memory/agent-memory.examples.html

@@ -0,0 +1,155 @@
+<header>
+  <div>
+    <h1>Agent Memory</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">list-ui</tag-ui> <tag-ui size="sm">description-list-ui</tag-ui> <tag-ui size="sm">code-ui</tag-ui> <tag-ui size="sm">drawer-ui</tag-ui>
+    </div>
+  </div>
+  <p>Surfaces for inspecting and editing what the agent remembers — facts the user has set ("call me Kim"), workspace context ("we use OKLCH for tokens"), and session-scoped state. Three shapes — a memory list, a single-entry detail view, and an editor for adding or revising.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Whenever an agent has persistent memory the user can audit. Two
+    distinct surfaces: an admin/settings page where the user sees and
+    curates the full memory store, and an inline drawer the agent can
+    pop ("I remembered X — keep / discard / edit"). Both reuse the
+    same primitives; the difference is host and presence of the bulk
+    actions.
+  </p>
+</section>
+
+<section data-section data-property="list">
+  <h2 variant="section">Memory list</h2>
+  <p data-note>Read-only inventory grouped by source (user / workspace / session). Each row carries a one-line fact, source tag, and last-updated time. Click-through opens the detail view.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="memory list">
+      <card-ui data-chunk="agent-memory-list" style="max-width: 640px;">
+        <header>
+          <span slot="heading" variant="section">Agent memory</span>
+          <text-ui slot="description" color="subtle">14 entries across 3 sources</text-ui>
+          <button-ui slot="action" text="Add memory" variant="ghost" size="sm" icon-leading="plus"></button-ui>
+        </header>
+        <section bleed>
+          <list-ui divider contained>
+            <list-item-ui text="Prefers Kim over Kimberly">
+              <span slot="description">From a chat on 2026-04-12</span>
+              <tag-ui slot="action" size="sm">user</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="Uses OKLCH tokens, never raw hex">
+              <span slot="description">From the AdiaUI styleguide</span>
+              <tag-ui slot="action" size="sm" variant="accent">workspace</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="Browser baseline: Chromium 125+, Safari 18.0+">
+              <span slot="description">From AGENTS.md</span>
+              <tag-ui slot="action" size="sm" variant="accent">workspace</tag-ui>
+            </list-item-ui>
+            <list-item-ui text="Working on Group 1 of skill expansion">
+              <span slot="description">Current session</span>
+              <tag-ui slot="action" size="sm">session</tag-ui>
+            </list-item-ui>
+          </list-ui>
+        </section>
+        <footer divider>
+          <text-ui slot="description" color="subtle" size="sm">Workspace memory is shared with team members.</text-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="detail">
+  <h2 variant="section">Memory detail</h2>
+  <p data-note>Single-entry view. <code>description-list-ui</code> for metadata; <code>code-ui</code> for any structured payload (e.g. JSON facts). Footer carries delete + edit actions.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="memory detail">
+      <card-ui data-chunk="agent-memory-detail" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Uses OKLCH tokens, never raw hex</span>
+          <tag-ui slot="action" variant="accent">workspace</tag-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <description-list-ui>
+              <span slot="term">Source</span>
+              <span slot="description">AdiaUI styleguide · component-token-contract.md</span>
+              <span slot="term">First seen</span>
+              <span slot="description">2026-03-14</span>
+              <span slot="term">Last referenced</span>
+              <span slot="description">2026-04-29 · 4 minutes ago</span>
+              <span slot="term">Times applied</span>
+              <span slot="description">142</span>
+            </description-list-ui>
+            <code-ui language="json">{
+  "fact": "no raw hex / rgb / oklch in component CSS",
+  "source": ".claude/docs/specs/component-token-contract.md#tokens",
+  "scope": ["packages/web-components/components/**/*.css"],
+  "exceptions": ["styles/colors/semantics.css", "styles/tokens.css"]
+}</code-ui>
+          </col-ui>
+        </section>
+        <footer divider>
+          <button-ui slot="action" text="Delete" variant="ghost" color="danger" size="sm" icon-leading="trash"></button-ui>
+          <button-ui slot="action" text="Edit" variant="outline" size="sm" icon-leading="pencil"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="editor">
+  <h2 variant="section">Memory editor</h2>
+  <p data-note>Inline drawer pop the agent fires when proposing a memory. Three controls: a <code>textarea-ui</code> for the fact, a <code>radio-ui</code> for scope, and primary/ghost actions in the footer. Errors carry through <code>field-ui</code>'s error slot.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="memory editor">
+      <card-ui data-chunk="agent-memory-editor" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Save this as a memory?</span>
+          <text-ui slot="description" color="subtle">The agent proposed a fact during this conversation.</text-ui>
+        </header>
+        <section>
+          <form-container-ui>
+            <col-ui gap="3">
+              <field-ui label="Fact">
+                <textarea-ui rows="3" value="Browser baseline: Chromium 125+, Safari 18.0+, Firefox 129+"></textarea-ui>
+              </field-ui>
+              <field-ui label="Scope" hint="Workspace memories are shared with your team.">
+                <col-ui gap="1">
+                  <radio-ui name="scope" value="user" label="Just me"></radio-ui>
+                  <radio-ui name="scope" value="workspace" label="My workspace" checked></radio-ui>
+                  <radio-ui name="scope" value="session" label="This session only"></radio-ui>
+                </col-ui>
+              </field-ui>
+            </col-ui>
+            <row-ui slot="actions" gap="2" justify="end">
+              <button-ui text="Discard" variant="ghost"></button-ui>
+              <button-ui text="Save memory" variant="primary"></button-ui>
+            </row-ui>
+          </form-container-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Source is always visible</strong> — the user must be able to see where the agent learned a fact. Hidden provenance erodes trust.</li>
+    <li><strong>Three scopes, named for the user</strong> — "Just me / My workspace / This session" — not technical labels (user / workspace / session) in user-facing copy.</li>
+    <li><strong>Workspace memories carry an accent tag</strong> — the visible distinction reminds the user these are shared.</li>
+    <li><strong>Editor confirmation, not silent persistence</strong> — when the agent proposes a memory, surface the editor pop. Auto-saving without confirmation is the path to "why does it think X?" support tickets.</li>
+    <li><strong>Delete is destructive but not type-to-confirm</strong> — memories are recoverable from history; a single click + toast undo is enough friction.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/list">list-ui</a> · <a href="/site/components/list-item">list-item-ui</a> — list anatomy.</li>
+    <li><a href="/site/components/description-list">description-list-ui</a> — term/description pairs in the detail view.</li>
+    <li><a href="/site/components/field">field-ui</a> — labeled form controls in the editor.</li>
+    <li><a href="/site/components/drawer">drawer-ui</a> — host surface when the editor is inline-popped.</li>
+  </ul>
+</section>

package/patterns/agent-memory/agent-memory.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Agent Memory (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/code/code.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/description-list/description-list.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/list/list.css">
+  <link rel="stylesheet" href="../../components/radio/radio.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+  <link rel="stylesheet" href="../../components/textarea/textarea.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/card/card.js"></script>
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/col/col.js"></script>
+  <script type="module" src="../../components/description-list/description-list.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/list/list.js"></script>
+  <script type="module" src="../../components/radio/radio.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+  <script type="module" src="../../components/text/text.js"></script>
+  <script type="module" src="../../components/textarea/textarea.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./agent-memory.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load agent-memory.examples.html — ${err.message}</p>`;
+      console.error('[agent-memory.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/agent-prompt-library/agent-prompt-library.examples.html

@@ -0,0 +1,181 @@
+<header>
+  <div>
+    <h1>Agent Prompt Library</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">grid-ui</tag-ui> <tag-ui size="sm">search-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">menu-ui</tag-ui> <tag-ui size="sm">option-card-ui</tag-ui>
+    </div>
+  </div>
+  <p>Saved prompts the user can recall instead of re-typing — recurring queries, formatted recipes, role-pinned starters. Three shapes — the full library page, a compact picker (popover or menu), and the prompt card itself.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Whenever users send the same prompt more than twice. The library
+    is the curation surface (settings/library route); the picker is
+    the in-context recall (chat input slash-menu, slash-command); the
+    card is the unit shared between both. All three reuse the same
+    fact: a prompt has a name, body, optional tags, optional pinned
+    role.
+  </p>
+</section>
+
+<section data-section data-property="library-grid">
+  <h2 variant="section">Library grid</h2>
+  <p data-note>Full library route. <code>search-ui</code> at the top, <code>tag-ui</code> filter chips, <code>grid-ui columns="2"</code> of prompt cards. Empty state when search returns nothing.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="prompt library grid">
+      <card-ui data-chunk="agent-prompt-library-grid" style="max-width: 720px;">
+        <header>
+          <span slot="heading" variant="section">Prompt library</span>
+          <text-ui slot="description" color="subtle">12 prompts · 4 categories</text-ui>
+          <button-ui slot="action" text="New prompt" variant="primary" size="sm" icon-leading="plus"></button-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <row-ui gap="2" align="center">
+              <search-ui size="sm" placeholder="Search prompts" style="flex: 1;"></search-ui>
+              <button-ui icon="funnel" variant="ghost" size="sm"></button-ui>
+            </row-ui>
+            <row-ui gap="2">
+              <tag-ui size="sm" variant="accent">All · 12</tag-ui>
+              <tag-ui size="sm">Code review · 4</tag-ui>
+              <tag-ui size="sm">Drafts · 3</tag-ui>
+              <tag-ui size="sm">Research · 3</tag-ui>
+              <tag-ui size="sm">Personal · 2</tag-ui>
+            </row-ui>
+            <grid-ui columns="2" gap="2">
+              <card-ui compact>
+                <header><span slot="heading">Code review</span><tag-ui slot="action" size="sm">Pinned</tag-ui></header>
+                <section><text-ui color="subtle" size="sm">Review the diff for security, perf, and naming. Flag with file:line. Suggest fixes inline.</text-ui></section>
+              </card-ui>
+              <card-ui compact>
+                <header><span slot="heading">Standup draft</span></header>
+                <section><text-ui color="subtle" size="sm">Summarize what I did yesterday from my git log. Group by repo. End with today's plan.</text-ui></section>
+              </card-ui>
+              <card-ui compact>
+                <header><span slot="heading">Spec from notes</span></header>
+                <section><text-ui color="subtle" size="sm">Turn these notes into a spec doc with sections: problem, design, alternatives, open questions.</text-ui></section>
+              </card-ui>
+              <card-ui compact>
+                <header><span slot="heading">Bug repro</span></header>
+                <section><text-ui color="subtle" size="sm">Given this stack trace, propose three hypotheses ordered by likelihood. Show the test that would falsify each.</text-ui></section>
+              </card-ui>
+            </grid-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="picker">
+  <h2 variant="section">Picker (slash-menu)</h2>
+  <p data-note>Compact popover surface fired from a chat input slash-command (<code>/</code> or <code>Cmd+J</code>). <code>menu-ui</code> with the prompt name + first 80 characters of body as the description. Recent prompts at the top.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="prompt picker">
+      <card-ui data-chunk="agent-prompt-picker" raw style="max-width: 420px;" data-shape="popover">
+        <section>
+          <col-ui gap="3">
+            <col-ui gap="1">
+              <text-ui strong size="sm" color="subtle">Recent</text-ui>
+              <col-ui gap="2">
+                <row-ui gap="2" align="center">
+                  <icon-ui name="code" size="sm"></icon-ui>
+                  <col-ui gap="0" style="flex: 1;">
+                    <text-ui strong>Code review</text-ui>
+                    <text-ui color="subtle" size="sm">Review the diff for security, perf, and naming…</text-ui>
+                  </col-ui>
+                  <kbd-ui>⌘1</kbd-ui>
+                </row-ui>
+                <row-ui gap="2" align="center">
+                  <icon-ui name="note" size="sm"></icon-ui>
+                  <col-ui gap="0" style="flex: 1;">
+                    <text-ui strong>Standup draft</text-ui>
+                    <text-ui color="subtle" size="sm">Summarize what I did yesterday from my git log…</text-ui>
+                  </col-ui>
+                  <kbd-ui>⌘2</kbd-ui>
+                </row-ui>
+              </col-ui>
+            </col-ui>
+            <divider-ui></divider-ui>
+            <col-ui gap="1">
+              <text-ui strong size="sm" color="subtle">All prompts</text-ui>
+              <col-ui gap="2">
+                <row-ui gap="2" align="center">
+                  <icon-ui name="file-text" size="sm"></icon-ui>
+                  <col-ui gap="0" style="flex: 1;">
+                    <text-ui strong>Spec from notes</text-ui>
+                    <text-ui color="subtle" size="sm">Turn these notes into a spec doc with sections…</text-ui>
+                  </col-ui>
+                </row-ui>
+                <row-ui gap="2" align="center">
+                  <icon-ui name="bug" size="sm"></icon-ui>
+                  <col-ui gap="0" style="flex: 1;">
+                    <text-ui strong>Bug repro</text-ui>
+                    <text-ui color="subtle" size="sm">Given this stack trace, propose three hypotheses…</text-ui>
+                  </col-ui>
+                </row-ui>
+              </col-ui>
+            </col-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="card">
+  <h2 variant="section">Prompt card (the unit)</h2>
+  <p data-note>The single prompt as a self-contained card. Header with name + tags; body with the full prompt text; footer with run / edit / delete. Reused inside the grid and the slash-menu detail.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="prompt card">
+      <card-ui data-chunk="agent-prompt-card" style="max-width: 560px;">
+        <header>
+          <span slot="heading" variant="section">Code review</span>
+          <row-ui slot="action" gap="1">
+            <tag-ui size="sm" variant="accent">Pinned</tag-ui>
+            <tag-ui size="sm">Code review</tag-ui>
+          </row-ui>
+        </header>
+        <section>
+          <col-ui gap="2">
+            <text-ui>Review the diff for security, perf, and naming. Flag issues with <code>file:line</code> citations. Suggest concrete fixes inline. Skip nitpicks unless asked.</text-ui>
+            <description-list-ui>
+              <span slot="term">Last used</span>
+              <span slot="description">3 hours ago</span>
+              <span slot="term">Times run</span>
+              <span slot="description">28</span>
+            </description-list-ui>
+          </col-ui>
+        </section>
+        <footer divider>
+          <button-ui slot="action" text="Delete" variant="ghost" color="danger" size="sm" icon-leading="trash"></button-ui>
+          <button-ui slot="action" text="Edit" variant="ghost" size="sm" icon-leading="pencil"></button-ui>
+          <button-ui slot="action" text="Run" variant="primary" size="sm" icon-leading="play"></button-ui>
+        </footer>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Picker is keyboard-first</strong> — Cmd+J opens, ⌘1–⌘9 selects recent, type-to-search filters. Mouse-only pickers are slow once a user has more than 5 prompts.</li>
+    <li><strong>Recents above all-prompts</strong> — most picks come from the last 3 used. Surface them first, alphabetical for the rest.</li>
+    <li><strong>Tags are filters, not categories</strong> — a prompt can carry multiple tags. The category chips at the top filter the grid; they don't partition.</li>
+    <li><strong>Pinned ≠ first</strong> — pinned prompts appear with the Pinned tag in any sort, not forced to the top. Surfacing-by-recency wins more selections than surfacing-by-pin.</li>
+    <li><strong>Run is the primary action</strong> — placement and tone match. Edit/delete are secondary; they don't compete.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/menu">menu-ui</a> — picker surface.</li>
+    <li><a href="/site/components/search">search-ui</a> — library top-bar input.</li>
+    <li><a href="/site/components/option-card">option-card-ui</a> — alternative when prompts have rich previews (image / icon).</li>
+    <li><a href="/site/patterns/adia-chat">adia-chat</a> — host surface that fires the picker on slash.</li>
+  </ul>
+</section>

package/patterns/agent-prompt-library/agent-prompt-library.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Agent Prompt Library (pattern) — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../styles/resets.css">
+  <link rel="stylesheet" href="../../styles/tokens.css">
+
+  <!-- Component CSS — primitives this pattern composes -->
+  <link rel="stylesheet" href="../../components/button/button.css">
+  <link rel="stylesheet" href="../../components/card/card.css">
+  <link rel="stylesheet" href="../../components/col/col.css">
+  <link rel="stylesheet" href="../../components/description-list/description-list.css">
+  <link rel="stylesheet" href="../../components/divider/divider.css">
+  <link rel="stylesheet" href="../../components/grid/grid.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/kbd/kbd.css">
+  <link rel="stylesheet" href="../../components/row/row.css">
+  <link rel="stylesheet" href="../../components/search/search.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+  <link rel="stylesheet" href="../../components/text/text.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/button/button.js"></script>
+  <script type="module" src="../../components/card/card.js"></script>
+  <script type="module" src="../../components/col/col.js"></script>
+  <script type="module" src="../../components/description-list/description-list.js"></script>
+  <script type="module" src="../../components/divider/divider.js"></script>
+  <script type="module" src="../../components/grid/grid.js"></script>
+  <script type="module" src="../../components/icon/icon.js"></script>
+  <script type="module" src="../../components/kbd/kbd.js"></script>
+  <script type="module" src="../../components/row/row.js"></script>
+  <script type="module" src="../../components/search/search.js"></script>
+  <script type="module" src="../../components/tag/tag.js"></script>
+  <script type="module" src="../../components/text/text.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--md-sys-color-neutral-background); color: var(--md-sys-color-neutral-on-surface); font-family: var(--a-font-family); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./agent-prompt-library.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load agent-prompt-library.examples.html — ${err.message}</p>`;
+      console.error('[agent-prompt-library.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/agent-tool-call/agent-tool-call.examples.html

@@ -0,0 +1,123 @@
+<header>
+  <div>
+    <h1>Agent Tool Call</h1>
+    <div data-actions>
+      <tag-ui size="sm">agent-artifact-ui</tag-ui> <tag-ui size="sm">code-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui>
+    </div>
+  </div>
+  <p>The block an agent renders when it invokes a tool — search, calculation, API call, function. Four states cover the lifecycle: <strong>running</strong>, <strong>success</strong>, <strong>error</strong>, and the default <strong>collapsed</strong> summary. All four reuse <code>agent-artifact-ui</code> with the <code>kind="TOOL"</code> badge; tone shifts on outcome.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    Whenever an agent calls a function and the user benefits from seeing
+    what the call did. The block is more compact than a full chat reply
+    and stays visually distinct from prose, so a thread of mixed
+    text-plus-tool-calls remains scannable. For multi-step tool runs,
+    pair this with <code>agent-reasoning-ui</code> above and
+    <code>agent-trace-ui</code> below for the full lineage.
+  </p>
+</section>
+
+<section data-section data-property="running">
+  <h2 variant="section">Running</h2>
+  <p data-note>In-progress invocation. <code>tone="neutral"</code> with a <code>progress-ui</code> indeterminate strip in the body. No action buttons until the call resolves.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="running tool call">
+      <agent-artifact-ui data-chunk="agent-tool-call-running" title="search_web" kind="TOOL" icon="magnifying-glass" tone="neutral" style="max-width: 560px;">
+        <col-ui gap="2">
+          <code-ui language="json">{ "query": "claude opus tool use latency", "max_results": 5 }</code-ui>
+          <row-ui align="center" gap="2">
+            <progress-ui indeterminate size="sm" style="flex: 1;"></progress-ui>
+            <text-ui color="subtle" size="sm">Running…</text-ui>
+          </row-ui>
+        </col-ui>
+      </agent-artifact-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="success">
+  <h2 variant="section">Success</h2>
+  <p data-note><code>tone="accent"</code> on resolution. Body shows the call args + a result preview (truncated when long). Secondary slot carries copy / open-in-new-tab actions.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="successful tool call">
+      <agent-artifact-ui data-chunk="agent-tool-call-success" title="search_web" kind="TOOL" icon="check-circle" tone="accent" style="max-width: 560px;">
+        <button-ui slot="secondary" text="Copy result" icon="copy" variant="ghost" size="sm"></button-ui>
+        <col-ui gap="2" style="min-width: 0;">
+          <description-list-ui layout="inline" align="between">
+            <dt>Query</dt><dd><code>claude opus tool use latency</code></dd>
+            <dt>Results</dt><dd>5 sources, 482 ms</dd>
+          </description-list-ui>
+          <code-ui language="json" style="min-width: 0;">[
+  { "title": "Anthropic — Tool use latency", "url": "anthropic.com/news/…", "rank": 1 },
+  { "title": "Latency primer for agent loops", "url": "blog.…", "rank": 2 }
+]</code-ui>
+        </col-ui>
+      </agent-artifact-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="error">
+  <h2 variant="section">Error</h2>
+  <p data-note><code>tone="danger"</code> with a clear next-step. The body carries the call args plus the error message in an <code>alert-ui</code>; secondary slot offers retry.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="failed tool call">
+      <agent-artifact-ui data-chunk="agent-tool-call-error" title="fetch_invoice" kind="TOOL" icon="warning" tone="danger" style="max-width: 560px;">
+        <button-ui slot="secondary" text="Retry" icon="arrow-clockwise" variant="outline" size="sm"></button-ui>
+        <col-ui gap="2" style="min-width: 0;">
+          <code-ui language="json" style="min-width: 0;">{ "invoice_id": "inv_8421", "format": "pdf" }</code-ui>
+          <alert-ui variant="danger">
+            <col-ui slot="content" gap="1">
+              <text-ui strong>404 Not Found</text-ui>
+              <text-ui>No invoice with id <code>inv_8421</code> in the last 90 days. Check the id or widen the date range.</text-ui>
+            </col-ui>
+          </alert-ui>
+        </col-ui>
+      </agent-artifact-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="collapsed">
+  <h2 variant="section">Collapsed (default summary)</h2>
+  <p data-note>Default state inside a long thread — the agent has many tool calls and most don't need detail. Header carries the tool name + result count or status; body expands on click. Use <code>collapsed</code> attribute.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="collapsed tool call summary">
+      <col-ui data-chunk="agent-tool-call-collapsed" gap="2" style="max-width: 560px;">
+        <agent-artifact-ui title="search_web · 5 results · 482 ms" kind="TOOL" icon="magnifying-glass" tone="accent" collapsed>
+          <code-ui language="json">[ /* result list */ ]</code-ui>
+        </agent-artifact-ui>
+        <agent-artifact-ui title="get_weather · San Francisco · 64°F" kind="TOOL" icon="cloud-sun" tone="accent" collapsed>
+          <code-ui language="json">{ "city": "San Francisco", "temp_f": 64, "condition": "fog" }</code-ui>
+        </agent-artifact-ui>
+        <agent-artifact-ui title="run_query · 12 rows" kind="TOOL" icon="database" tone="accent" collapsed>
+          <code-ui language="sql">SELECT id, name, plan FROM users WHERE …</code-ui>
+        </agent-artifact-ui>
+      </col-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Always <code>kind="TOOL"</code></strong> for the badge — distinguishes tool blocks from A2UI artifacts, tickets, notes, etc.</li>
+    <li><strong>Tone tracks state</strong> — <code>neutral</code> while running, <code>accent</code> on success, <code>danger</code> on error. Don't use <code>warning</code> here; reserve that for soft warnings (rate-limit nearing, deprecated tool).</li>
+    <li><strong>Title carries identity</strong> — function name first; for collapsed/summary forms, append <code>·</code> + result count or short status.</li>
+    <li><strong>Body always shows args first</strong> in a <code>code-ui</code> block, then result. The reverse hides the call from the user; an agent thread is a contract, not an output stream.</li>
+    <li><strong>Retry on error, not on success</strong> — error gets a Retry button in <code>slot="secondary"</code>; success gets Copy / Open. Don't double-up.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/agent-artifact">agent-artifact-ui</a> — the underlying component.</li>
+    <li><a href="/site/components/agent-reasoning">agent-reasoning-ui</a> — pair above for "why I called this tool".</li>
+    <li><a href="/site/components/agent-trace">agent-trace-ui</a> — pair below for the full execution trace.</li>
+    <li><a href="/site/patterns/adia-chat">adia-chat</a> — host surface for tool-call blocks in a thread.</li>
+  </ul>
+</section>