@adia-ai/web-components 0.8.6 → 0.8.8

package/patterns/chat-shell/chat-shell.examples.html

@@ -0,0 +1,129 @@
+<header>
+  <div>
+    <h1>Chat Shell — Composition Pattern</h1>
+    <div data-actions>
+      <tag-ui size="sm">chat-shell</tag-ui>
+      <tag-ui size="sm" variant="ghost">cluster-namespaced</tag-ui>
+    </div>
+  </div>
+  <p>
+    The canonical composition pattern for an LLM chat surface. Built from
+    cluster-namespaced bespoke children — every structural part has its
+    own custom element. The legacy raw-HTML form (raw <code>&lt;header&gt;</code>
+    with <code>data-chat-name</code> / <code>data-chat-status</code>,
+    <code>&lt;section data-chat-messages&gt;</code>,
+    <code>&lt;empty-state-ui data-chat-empty&gt;</code>,
+    <code>&lt;footer&gt;</code> wrapping <code>&lt;chat-input-ui&gt;</code>)
+    was retired in v0.4.0 per
+    <a href="../../../../.brain/adrs/0024-legacy-shell-shapes-retired.md">ADR-0024</a>;
+    new code uses the bespoke shape exclusively per
+    <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>.
+  </p>
+</header>
+
+<section data-section data-property="canonical-hierarchy">
+  <h2 variant="section">Canonical hierarchy</h2>
+  <p data-note>
+    For the full live demo + state-as-attribute documentation, see
+    <a href="/site/components/chat-shell">/site/components/chat-shell</a>.
+    This page is the pattern hub.
+  </p>
+  <code-ui language="html">&lt;chat-shell provider="anthropic" model="claude-sonnet-4-7" proxy-url="/api/llm"&gt;
+
+  &lt;!-- Header — name + status indicator --&gt;
+  &lt;chat-header&gt;
+    &lt;span slot="name"&gt;Claude&lt;/span&gt;
+    &lt;chat-status slot="status"&gt;Connected&lt;/chat-status&gt;
+  &lt;/chat-header&gt;
+
+  &lt;!-- Streaming message thread (with optional empty state) --&gt;
+  &lt;chat-thread&gt;
+    &lt;chat-empty&gt;
+      &lt;empty-state-ui icon="chat-circle"
+        heading="Hello!" description="Ask me anything."&gt;&lt;/empty-state-ui&gt;
+    &lt;/chat-empty&gt;
+  &lt;/chat-thread&gt;
+
+  &lt;!-- Composer wraps the input primitive --&gt;
+  &lt;chat-composer&gt;
+    &lt;chat-input-ui placeholder="Message…"&gt;&lt;/chat-input-ui&gt;
+  &lt;/chat-composer&gt;
+
+&lt;/chat-shell&gt;</code-ui>
+</section>
+
+<section data-section data-property="part-by-part-reference">
+  <h2 variant="section">Part-by-part reference</h2>
+  <table>
+    <thead>
+      <tr><th>Part</th><th>Role</th></tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><a href="/site/components/chat-shell"><code>&lt;chat-shell&gt;</code></a></td>
+        <td>Behavior-only host. Wires LLM streaming, markdown rendering, code-block upgrades, the <code>proxy-url</code> integration path.</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/chat-header"><code>&lt;chat-header&gt;</code></a></td>
+        <td>Top band — slots: <code>name</code>, <code>status</code>, <code>action</code>.</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/chat-thread"><code>&lt;chat-thread&gt;</code></a></td>
+        <td>Streaming message list. Reflects <code>[streaming]</code>.</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/chat-empty"><code>&lt;chat-empty&gt;</code></a></td>
+        <td>Empty-state hint inside <code>&lt;chat-thread&gt;</code> before the first message.</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/chat-composer"><code>&lt;chat-composer&gt;</code></a></td>
+        <td>Input area. Wraps <code>&lt;chat-input-ui&gt;</code>.</td>
+      </tr>
+      <tr>
+        <td><a href="/site/components/chat-sidebar"><code>&lt;chat-sidebar&gt;</code></a></td>
+        <td>Optional conversation-list / inspector rail (<code>slot="leading"</code> or <code>slot="trailing"</code>).</td>
+      </tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section data-property="with-sidebar-conversation-list">
+  <h2 variant="section">With sidebar — conversation list</h2>
+  <p>For a multi-conversation surface, add a <code>&lt;chat-sidebar slot="leading"&gt;</code> with a <code>&lt;nav-ui&gt;</code> of past chats.</p>
+  <code-ui language="html">&lt;chat-shell&gt;
+  &lt;chat-sidebar slot="leading"&gt;
+    &lt;chat-topbar slot="header"&gt;
+      &lt;span slot="heading"&gt;Conversations&lt;/span&gt;
+      &lt;button-ui slot="action" text="+ New" variant="primary" size="sm"&gt;&lt;/button-ui&gt;
+    &lt;/chat-topbar&gt;
+    &lt;nav-ui&gt;
+      &lt;nav-item-ui text="Today's chat" selected&gt;&lt;/nav-item-ui&gt;
+      &lt;nav-item-ui text="API design review"&gt;&lt;/nav-item-ui&gt;
+      &lt;nav-item-ui text="Architecture proposal"&gt;&lt;/nav-item-ui&gt;
+    &lt;/nav-ui&gt;
+  &lt;/chat-sidebar&gt;
+  &lt;chat-header&gt;...&lt;/chat-header&gt;
+  &lt;chat-thread&gt;...&lt;/chat-thread&gt;
+  &lt;chat-composer&gt;...&lt;/chat-composer&gt;
+&lt;/chat-shell&gt;</code-ui>
+</section>
+
+<section data-section data-property="authoring-rules">
+  <h2 variant="section">Authoring rules</h2>
+  <ul>
+    <li><strong>Cluster-namespaced children only.</strong> Use <code>&lt;chat-header&gt;</code>, <code>&lt;chat-thread&gt;</code>, <code>&lt;chat-composer&gt;</code>, <code>&lt;chat-sidebar&gt;</code>. Don't author raw <code>&lt;header data-chat-name&gt;</code> or <code>&lt;section data-chat-messages&gt;</code> — these no longer style or wire.</li>
+    <li><strong>State is queryable as attributes.</strong> <code>shell.querySelector('chat-thread').hasAttribute('streaming')</code>. Style cross-cuts via <code>:has()</code>; no JS coordination needed.</li>
+    <li><strong>Empty state wraps in <code>&lt;chat-empty&gt;</code> inside <code>&lt;chat-thread&gt;</code>.</strong> The thread hides the empty wrapper automatically when the first message arrives.</li>
+    <li><strong>Composer wraps <code>&lt;chat-input-ui&gt;</code>.</strong> Don't put <code>&lt;chat-input-ui&gt;</code> as a direct child of <code>&lt;chat-shell&gt;</code>.</li>
+  </ul>
+</section>
+
+<section data-section data-property="where-to-next">
+  <h2 variant="section">Where to next</h2>
+  <ul>
+    <li><a href="/site/components/chat-shell">chat-shell component reference</a> — full anatomy + live demo</li>
+    <li><a href="/site/components/chat-thread">chat-thread</a> · <a href="/site/components/chat-composer">chat-composer</a> · <a href="/site/components/chat-input">chat-input-ui</a></li>
+    <li><a href="/site/patterns/shells">Macro-shells overview</a></li>
+    <li><a href="/site/patterns/admin-shell">admin-shell pattern</a> (counterpart for admin/dashboard surfaces)</li>
+  </ul>
+</section>

package/patterns/chat-shell/chat-shell.html

@@ -0,0 +1,46 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Chat Shell (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/code/code.css">
+  <link rel="stylesheet" href="../../components/empty-state/empty-state.css">
+  <link rel="stylesheet" href="../../components/tag/tag.css">
+
+  <!-- Component JS -->
+  <script type="module" src="../../components/code/code.js"></script>
+  <script type="module" src="../../components/empty-state/empty-state.js"></script>
+  <script type="module" src="../../components/tag/tag.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('./chat-shell.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 chat-shell.examples.html — ${err.message}</p>`;
+      console.error('[chat-shell.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/patterns/comments-and-collaboration/comments-and-collaboration.examples.html

@@ -0,0 +1,241 @@
+<header>
+  <div>
+    <h1>Comments &amp; Collaboration</h1>
+    <div data-actions>
+      <tag-ui size="sm">card-ui</tag-ui> <tag-ui size="sm">avatar-ui</tag-ui> <tag-ui size="sm">field-ui</tag-ui> <tag-ui size="sm">menu-ui</tag-ui> <tag-ui size="sm">tag-ui</tag-ui> <tag-ui size="sm">button-ui</tag-ui>
+    </div>
+  </div>
+  <p>The substrate for comments threads, @-mentions, and emoji reactions on any first-class object — docs, tasks, designs, code reviews. Composed entirely from existing primitives; the pattern is in the wiring, not in new components.</p>
+</header>
+
+<section data-section data-property="when-to-use">
+  <h2 variant="section">When to use</h2>
+  <p data-note>
+    When users need to talk to each other about a specific object —
+    a design, a task, a row, a paragraph. Comments anchor to the
+    object; mentions notify a person; reactions condense agreement
+    without a reply. The three nest: a comment thread carries
+    mentions inside its text and reactions on each message.
+  </p>
+</section>
+
+<section data-section data-property="thread">
+  <h2 variant="section">Comment thread</h2>
+  <p data-note>A vertical stack of comments anchored to a parent object. Each row carries author avatar + name + timestamp + body + reactions strip + reply action. Threaded replies indent one level — deeper nesting collapses to "X replies" by default.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="comment thread">
+      <card-ui data-chunk="comments-thread" style="max-width: 640px;">
+        <header>
+          <span slot="heading" variant="section">Discussion</span>
+          <text-ui slot="description" color="subtle">3 comments · 2 participants</text-ui>
+          <button-ui slot="action" text="Resolve" variant="ghost" size="sm" icon-leading="check"></button-ui>
+        </header>
+        <section>
+          <col-ui gap="3">
+            <row-ui gap="3" align="start">
+              <avatar-ui size="sm" text="Avery Chen"></avatar-ui>
+              <col-ui gap="1" grow>
+                <row-ui gap="2" align="baseline">
+                  <text-ui strong>Avery Chen</text-ui>
+                  <text-ui color="subtle" size="sm">2 hours ago</text-ui>
+                </row-ui>
+                <text-ui>Should the OKLCH ramp here use the chrome or the data scale? <text-ui color="primary">@Kim</text-ui> what's the convention?</text-ui>
+                <row-ui gap="1">
+                  <tag-ui size="sm" icon-leading="thumbs-up">2</tag-ui>
+                  <tag-ui size="sm" icon-leading="eyes">1</tag-ui>
+                  <button-ui text="Reply" variant="ghost" size="xs"></button-ui>
+                </row-ui>
+              </col-ui>
+            </row-ui>
+            <row-ui gap="3" align="start" style="padding-inline-start: 2.5rem;">
+              <avatar-ui size="sm" text="Kim Granlund"></avatar-ui>
+              <col-ui gap="1" grow>
+                <row-ui gap="2" align="baseline">
+                  <text-ui strong>Kim Granlund</text-ui>
+                  <text-ui color="subtle" size="sm">1 hour ago</text-ui>
+                </row-ui>
+                <text-ui>Chrome — the data scale is reserved for visualization series. Spec at <text-ui color="primary">.claude/docs/specs/component-token-contract.md</text-ui>.</text-ui>
+                <row-ui gap="1">
+                  <tag-ui size="sm" icon-leading="thumbs-up">3</tag-ui>
+                  <button-ui text="Reply" variant="ghost" size="xs"></button-ui>
+                </row-ui>
+              </col-ui>
+            </row-ui>
+            <row-ui gap="3" align="start">
+              <avatar-ui size="sm" text="Jordan Lee"></avatar-ui>
+              <col-ui gap="1" grow>
+                <row-ui gap="2" align="baseline">
+                  <text-ui strong>Jordan Lee</text-ui>
+                  <text-ui color="subtle" size="sm">12 minutes ago</text-ui>
+                </row-ui>
+                <text-ui>Filed a follow-up — adding a lint rule so this doesn't happen again. <text-ui color="primary">#linter</text-ui></text-ui>
+                <row-ui gap="1">
+                  <button-ui text="Reply" variant="ghost" size="xs"></button-ui>
+                </row-ui>
+              </col-ui>
+            </row-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composer">
+  <h2 variant="section">Comment composer</h2>
+  <p data-note>The input field below a thread. Multiline, with attach + mention + emoji affordances inline, and Send / Cancel actions. Submits on Cmd/Ctrl+Enter; Enter inserts a newline.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="comment composer">
+      <card-ui data-chunk="comments-composer" style="max-width: 640px;">
+        <section>
+          <row-ui gap="3" align="start">
+            <avatar-ui size="sm" text="You"></avatar-ui>
+            <col-ui gap="2" grow>
+              <field-ui>
+                <textarea-ui placeholder="Write a comment… use @ to mention" rows="3"></textarea-ui>
+              </field-ui>
+              <row-ui gap="2" align="center">
+                <button-ui icon="paperclip" variant="ghost" size="sm" aria-label="Attach"></button-ui>
+                <button-ui icon="at" variant="ghost" size="sm" aria-label="Mention someone"></button-ui>
+                <button-ui icon="smiley" variant="ghost" size="sm" aria-label="Insert emoji"></button-ui>
+                <text-ui color="subtle" size="sm" style="margin-inline-start: auto;"><kbd-ui>Cmd</kbd-ui> + <kbd-ui>Enter</kbd-ui> to send</text-ui>
+                <button-ui text="Comment" variant="primary" size="sm"></button-ui>
+              </row-ui>
+            </col-ui>
+          </row-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="mention-menu">
+  <h2 variant="section">@-mention picker</h2>
+  <p data-note>Popover that opens after the user types <code>@</code>. Shows team members + recently-mentioned at top, fuzzy-filtered by query. Each row carries avatar + name + handle + role tag. Arrow keys navigate; Enter inserts; Esc closes without inserting.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="mention picker menu">
+      <card-ui data-chunk="comments-mention-menu" raw style="max-width: 320px;" data-shape="popover">
+        <section>
+          <col-ui gap="2">
+            <text-ui strong size="sm" color="subtle">Mention</text-ui>
+            <col-ui gap="1">
+              <row-ui gap="2" align="center">
+                <avatar-ui size="sm" text="Kim Granlund"></avatar-ui>
+                <col-ui gap="0" style="flex: 1;">
+                  <text-ui strong>Kim Granlund</text-ui>
+                  <text-ui color="subtle" size="sm">@kim · Owner</text-ui>
+                </col-ui>
+              </row-ui>
+              <row-ui gap="2" align="center">
+                <avatar-ui size="sm" text="Avery Chen"></avatar-ui>
+                <col-ui gap="0" style="flex: 1;">
+                  <text-ui strong>Avery Chen</text-ui>
+                  <text-ui color="subtle" size="sm">@avery · Designer</text-ui>
+                </col-ui>
+              </row-ui>
+              <row-ui gap="2" align="center">
+                <avatar-ui size="sm" text="Jordan Lee"></avatar-ui>
+                <col-ui gap="0" style="flex: 1;">
+                  <text-ui strong>Jordan Lee</text-ui>
+                  <text-ui color="subtle" size="sm">@jordan · Engineer</text-ui>
+                </col-ui>
+              </row-ui>
+              <divider-ui></divider-ui>
+              <row-ui gap="2" align="center">
+                <icon-ui name="users-three" size="sm"></icon-ui>
+                <col-ui gap="0" style="flex: 1;">
+                  <text-ui strong>@team</text-ui>
+                  <text-ui color="subtle" size="sm">Notify everyone in this workspace</text-ui>
+                </col-ui>
+              </row-ui>
+            </col-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="reactions-bar">
+  <h2 variant="section">Reactions bar</h2>
+  <p data-note>The strip of reaction tags under a comment or message. Each tag shows emoji + count; the user's own reaction is highlighted. A trailing "+" opens the picker. Click a count to toggle the user's own reaction; long-press shows who reacted.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="reactions bar">
+      <row-ui data-chunk="reactions-bar" gap="1">
+        <tag-ui size="sm">👍 4</tag-ui>
+        <tag-ui size="sm" variant="primary">🎉 2</tag-ui>
+        <tag-ui size="sm">👀 1</tag-ui>
+        <tag-ui size="sm">🚀 1</tag-ui>
+        <button-ui icon="plus" variant="ghost" size="xs" aria-label="Add reaction"></button-ui>
+      </row-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="reactions-picker">
+  <h2 variant="section">Reactions picker</h2>
+  <p data-note>The emoji-grid popover that opens from the "+" button. Recent + frequent emojis at top; full categorical grid below; search input above. Arrow + Enter for keyboard; click for pointer.</p>
+  <div data-artifact-container>
+    <div data-artifact-item data-artifact-label="reactions picker">
+      <card-ui data-chunk="reactions-picker" style="max-width: 360px;">
+        <section>
+          <col-ui gap="2">
+            <field-ui>
+              <input-ui placeholder="Search emoji…" icon-leading="magnifying-glass"></input-ui>
+            </field-ui>
+            <col-ui gap="1">
+              <text-ui strong size="sm" color="subtle">Frequently used</text-ui>
+              <row-ui gap="1" wrap>
+                <button-ui text="👍" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🎉" variant="ghost" size="sm"></button-ui>
+                <button-ui text="❤️" variant="ghost" size="sm"></button-ui>
+                <button-ui text="👀" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🚀" variant="ghost" size="sm"></button-ui>
+                <button-ui text="✅" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🙏" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🔥" variant="ghost" size="sm"></button-ui>
+              </row-ui>
+            </col-ui>
+            <col-ui gap="1">
+              <text-ui strong size="sm" color="subtle">Smileys</text-ui>
+              <row-ui gap="1" wrap>
+                <button-ui text="😀" variant="ghost" size="sm"></button-ui>
+                <button-ui text="😄" variant="ghost" size="sm"></button-ui>
+                <button-ui text="😂" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🤔" variant="ghost" size="sm"></button-ui>
+                <button-ui text="😅" variant="ghost" size="sm"></button-ui>
+                <button-ui text="😎" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🥺" variant="ghost" size="sm"></button-ui>
+                <button-ui text="🙃" variant="ghost" size="sm"></button-ui>
+              </row-ui>
+            </col-ui>
+          </col-ui>
+        </section>
+      </card-ui>
+    </div>
+  </div>
+</section>
+
+<section data-section data-property="composition">
+  <h2 variant="section">Composition rules</h2>
+  <ul>
+    <li><strong>Comments anchor to an object</strong> — every thread has a parent (a doc paragraph, a row, a design selection). The thread surface usually opens beside the object, not in a global modal. Threadless "general comments" are a separate pattern (chat thread, 11a).</li>
+    <li><strong>Mentions notify; reactions don't</strong> — typing <code>@name</code> always pings that user; emoji reactions never do. The semantic gap matters: mentions are an action ("read this"), reactions are an acknowledgment ("seen / agreed").</li>
+    <li><strong>Cmd/Ctrl+Enter to send, Enter for newline</strong> — comments are multi-line by default. The opposite (Enter to send, Shift+Enter for newline) is correct for chat input (11b) but wrong here.</li>
+    <li><strong>Reactions are typed by emoji, not by sentiment</strong> — don't normalize "👍" and "🚀" into a `like_count`. Each emoji is its own bucket; counts are per-emoji.</li>
+    <li><strong>Resolve, don't delete</strong> — threads should be resolvable (collapsed, marked done) but not destructively deleted by default. Audit trail matters.</li>
+    <li><strong>Sharing dialogs live in the RBAC domain</strong> — the "Share this with…" surface is concept 36e, not a sub-concept of comments. Don't re-author it under collaboration.</li>
+  </ul>
+</section>
+
+<section data-section data-property="cross-references">
+  <h2 variant="section">See also</h2>
+  <ul>
+    <li><a href="/site/components/field">field-ui</a> · <a href="/site/components/textarea">textarea-ui</a> — composer input.</li>
+    <li><a href="/site/components/menu">menu-ui</a> — mention picker surface.</li>
+    <li><a href="/site/components/tag">tag-ui</a> — reaction chips.</li>
+    <li><a href="/site/components/avatar">avatar-ui</a> — author identity.</li>
+    <li><a href="/site/patterns/permissions-sharing">permissions-sharing</a> — the sharing-dialog surface (concept 36e).</li>
+    <li><a href="/site/patterns/agent-tool-call">agent-tool-call</a> — sibling thread-shape (model output, not user comments).</li>
+  </ul>
+</section>

package/patterns/comments-and-collaboration/comments-and-collaboration.html

@@ -0,0 +1,66 @@
+<!DOCTYPE html>
+<html lang="en" theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Comments &amp; Collaboration (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/avatar/avatar.css">
+  <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/divider/divider.css">
+  <link rel="stylesheet" href="../../components/field/field.css">
+  <link rel="stylesheet" href="../../components/icon/icon.css">
+  <link rel="stylesheet" href="../../components/input/input.css">
+  <link rel="stylesheet" href="../../components/kbd/kbd.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/avatar/avatar.js"></script>
+  <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/divider/divider.js"></script>
+  <script type="module" src="../../components/field/field.js"></script>
+  <script type="module" src="../../components/icon/icon.js"></script>
+  <script type="module" src="../../components/input/input.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/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('./comments-and-collaboration.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 comments-and-collaboration.examples.html — ${err.message}</p>`;
+      console.error('[comments-and-collaboration.html]', err);
+    }
+  </script>
+
+</body>
+</html>