@kitn.ai/ui 0.14.1

package/src/stories/conversation-with-sources.stories.tsx

@@ -0,0 +1,471 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import {
+  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageAvatar, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  Source, SourceTrigger, SourceContent, SourceList,
+  Button, Separator,
+} from '../index';
+import { Copy, ThumbsUp, ThumbsDown, ArrowUp } from 'lucide-solid';
+import '../elements/register'; // registers kai-sources / kai-source
+
+// kai-sources / kai-source IntrinsicElements are already declared in
+// src/elements/source-list.stories.tsx (same TS project, merged interface).
+// Re-declare here so this file is self-contained; types must match exactly.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      // Plain HTMLAttributes — `numbered` is set via setAttribute in onMount.
+      'kai-sources': JSX.HTMLAttributes<HTMLElement>;
+      'kai-source': JSX.HTMLAttributes<HTMLElement> & {
+        href?: string;
+        label?: string;
+        headline?: string;
+        description?: string;
+        'show-favicon'?: boolean | '';
+      };
+    }
+  }
+}
+
+const meta: Meta = {
+  title: 'Examples/Conversation with Sources',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: [
+          'Show inline citations below an assistant reply. Two routes:',
+          '',
+          '**Prop route (`sources` array):** set `<kai-sources>.sources = [{ href, title, description, label?, showFavicon? }]` as a JS property. Prop sources render first.',
+          '',
+          '**Declarative route (`<kai-source>` children):** place `<kai-source>` elements as children of `<kai-sources>`. They are picked up via `MutationObserver` and appended after any prop sources. Use `headline` (not `title` — `title` is a reserved HTML attribute that conflicts with the custom-element constructor). Confirmed in `src/elements/source.tsx`.',
+          '',
+          '**Automatic numbered labels (`numbered` prop):** set `<kai-sources numbered>` (HTML) or `el.numbered = true` (JS) to label each citation chip with its 1-based index (`1`, `2`, `3`, …) from the merged prop+children list. Per-item `label` values are ignored when `numbered` is set. For manual control, omit `numbered` and set `label={1}` / `label={2}` etc. on each `SourceTrigger` (Solid) or the `label` attribute on each `<kai-source>` child.',
+          '',
+          '**When to omit favicons:** the favicon is fetched from the link\'s domain. Skip it for internal/localhost URLs, or when the domain\'s favicon is low-contrast on your background.',
+        ].join('\n'),
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  name: 'Multi-turn with Citations',
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          'Two exchanges, two citation styles. First exchange uses `label={1|2|3}` for numbered badges, no favicons. Second exchange adds `showFavicon` per-trigger.',
+          '',
+          '**Note:** `<kai-source>` uses `headline` not `title` for the hover-card heading — `title` is a reserved HTML attribute that conflicts with the custom-element constructor (`src/elements/source.tsx`).',
+          '',
+          'See the **Numbered Citations** story for the `numbered` prop that auto-labels all chips with their 1-based index.',
+        ].join('\n'),
+      },
+    },
+  },
+  render: () => (
+    <div class="flex flex-col h-[650px] w-full max-w-2xl bg-background rounded-xl shadow-lg overflow-hidden">
+      <div class="flex items-center px-4 py-3">
+        <h2 class="text-sm font-semibold text-foreground">Research: WebAssembly in Production</h2>
+      </div>
+      <Separator />
+
+      <ChatContainer class="flex-1 p-4">
+        <ChatContainerContent class="space-y-6 py-4">
+
+          {/* First exchange */}
+          <Message>
+            <MessageAvatar src="" fallback="U" alt="User" />
+            <MessageContent>
+              What are the real-world performance benefits of using WebAssembly in production web apps? I want concrete examples, not just benchmarks.
+            </MessageContent>
+          </Message>
+
+          <Message>
+            <MessageAvatar src="" fallback="AI" alt="Assistant" />
+            <div class="flex-1 space-y-2">
+              <MessageContent markdown>
+{`Several major companies have deployed WebAssembly in production with measurable results:
+
+**Figma** replaced their C++ to asm.js pipeline with Wasm and saw a **3x performance improvement** in load times. Their design tool renders complex vector graphics at 60fps using a Wasm-compiled engine.
+
+**Google Earth** ported their native rendering engine to Wasm, enabling the full 3D globe experience in browsers without plugins. Frame rendering dropped from **40ms to 12ms** per frame.
+
+**Shopify** uses Wasm for their theme editor's Liquid template parsing, achieving **10x faster** template compilation compared to their previous JavaScript parser.
+
+The pattern is consistent: CPU-intensive tasks like **image processing, cryptography, physics simulation, and codec operations** see the largest gains. IO-bound operations don't benefit as much.`}
+              </MessageContent>
+
+              <SourceList>
+                <Source href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/">
+                  <SourceTrigger label={1} />
+                  <SourceContent
+                    title="WebAssembly cut Figma's load time by 3x"
+                    description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+                  />
+                </Source>
+                <Source href="https://web.dev/case-studies/earth-webassembly">
+                  <SourceTrigger label={2} />
+                  <SourceContent
+                    title="Google Earth and WebAssembly - web.dev"
+                    description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+                  />
+                </Source>
+                <Source href="https://shopify.engineering/shopify-webassembly">
+                  <SourceTrigger label={3} />
+                  <SourceContent
+                    title="How Shopify Uses WebAssembly"
+                    description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+                  />
+                </Source>
+              </SourceList>
+
+              <MessageActions>
+                <Button variant="ghost" size="icon-sm" aria-label="Copy message"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Good response"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Bad response"><ThumbsDown class="size-3.5" /></Button>
+              </MessageActions>
+            </div>
+          </Message>
+
+          {/* Second exchange with different citation pattern */}
+          <Message>
+            <MessageAvatar src="" fallback="U" alt="User" />
+            <MessageContent>
+              What about the downsides? Are there situations where Wasm actually hurts performance?
+            </MessageContent>
+          </Message>
+
+          <Message>
+            <MessageAvatar src="" fallback="AI" alt="Assistant" />
+            <div class="flex-1 space-y-2">
+              <MessageContent markdown>
+{`Yes, there are real tradeoffs to consider:
+
+**Bundle size** -- Wasm modules can be significantly larger than equivalent JavaScript. The Squoosh image editor found their Wasm codecs added **2-4MB** of download size, which they mitigated with lazy loading.
+
+**DOM access overhead** -- Every call from Wasm to the DOM crosses a boundary with serialization cost. Applications that frequently manipulate the DOM (like React-style UI frameworks) can actually be **slower** in Wasm than optimized JavaScript.
+
+**Startup latency** -- Wasm modules must be compiled before execution. While streaming compilation helps, large modules can take **200-500ms** to initialize on mobile devices.
+
+**Garbage collection** -- Until the Wasm GC proposal ships broadly, languages like Go and Java bring their own GC runtime, adding **5-20MB** to module size.
+
+The consensus from the Chrome team's analysis is: **use Wasm for compute-heavy inner loops, keep UI and orchestration in JavaScript**.`}
+              </MessageContent>
+
+              <SourceList>
+                <Source href="https://web.dev/squoosh-v2/">
+                  <SourceTrigger label={1} showFavicon />
+                  <SourceContent
+                    title="Squoosh v2: codec improvements with WebAssembly"
+                    description="How the Squoosh team manages Wasm codec size and loading strategies for their image compression tool."
+                  />
+                </Source>
+                <Source href="https://surma.dev/things/js-to-asc/">
+                  <SourceTrigger label={2} showFavicon />
+                  <SourceContent
+                    title="JavaScript to AssemblyScript - Surma.dev"
+                    description="Detailed performance comparison of JS vs AssemblyScript/Wasm for various workloads including DOM-heavy tasks."
+                  />
+                </Source>
+                <Source href="https://v8.dev/blog/wasm-compilation-pipeline">
+                  <SourceTrigger label={3} showFavicon />
+                  <SourceContent
+                    title="Liftoff: V8's Wasm baseline compiler"
+                    description="V8 team's analysis of Wasm compilation latency and their streaming compilation optimization."
+                  />
+                </Source>
+                <Source href="https://chromestatus.com/feature/6062715726462976">
+                  <SourceTrigger label={4} showFavicon />
+                  <SourceContent
+                    title="WebAssembly Garbage Collection - Chrome Platform Status"
+                    description="Status of the WasmGC proposal and its impact on languages targeting WebAssembly."
+                  />
+                </Source>
+              </SourceList>
+
+              <MessageActions>
+                <Button variant="ghost" size="icon-sm" aria-label="Copy message"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Good response"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Bad response"><ThumbsDown class="size-3.5" /></Button>
+              </MessageActions>
+            </div>
+          </Message>
+
+          <ChatContainerScrollAnchor />
+        </ChatContainerContent>
+      </ChatContainer>
+
+      <div class="px-4 pb-4">
+        <PromptInput>
+          <PromptInputTextarea placeholder="Ask about WebAssembly..." />
+          <PromptInputActions class="justify-end">
+            <Button variant="default" size="icon-sm" class="rounded-full" aria-label="Send message">
+              <ArrowUp class="size-4" />
+            </Button>
+          </PromptInputActions>
+        </PromptInput>
+      </div>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Numbered Citations story
+// ---------------------------------------------------------------------------
+
+export const Numbered: Story = {
+  name: 'Numbered Citations',
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          'Demonstrates the `numbered` boolean prop on `<kai-sources>` / `SourceList`.',
+          '',
+          'When `numbered` is set, every citation chip is auto-labelled with its **1-based index** in the merged (prop + declarative-children) source list, regardless of any per-item `label` value.',
+          '',
+          '- Solid: pass `numbered` prop on the wrapping element (future support) or render index manually as shown here.',
+          '- Web component: `<kai-sources numbered>` or `el.numbered = true`.',
+          '',
+          '**Inline prose citations** (e.g. `[1]` inside a markdown paragraph) are still manual — this prop only controls the chip labels in the source strip.',
+          '',
+          '**Note:** `<kai-source>` uses `headline` (not `title`) as the hover-card attribute.',
+        ].join('\n'),
+      },
+    },
+  },
+  render: () => (
+    <div class="flex flex-col gap-6 p-4 w-full max-w-2xl bg-background rounded-xl shadow-lg">
+      <div>
+        <p class="text-sm text-muted-foreground mb-1">
+          Sources strip with <code>numbered</code> — chips show 1, 2, 3 automatically:
+        </p>
+        <SourceList>
+          <Source href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/">
+            <SourceTrigger label={1} />
+            <SourceContent
+              title="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+            />
+          </Source>
+          <Source href="https://web.dev/case-studies/earth-webassembly">
+            <SourceTrigger label={2} />
+            <SourceContent
+              title="Google Earth and WebAssembly - web.dev"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+            />
+          </Source>
+          <Source href="https://shopify.engineering/shopify-webassembly">
+            <SourceTrigger label={3} />
+            <SourceContent
+              title="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+            />
+          </Source>
+          <Source href="https://surma.dev/things/js-to-asc/">
+            <SourceTrigger label={4} />
+            <SourceContent
+              title="JavaScript to AssemblyScript - Surma.dev"
+              description="Detailed performance comparison of JS vs AssemblyScript/Wasm for various workloads."
+            />
+          </Source>
+        </SourceList>
+      </div>
+
+      <div>
+        <p class="text-sm text-muted-foreground mb-1">
+          Same sources without numbering — chips fall back to domain labels:
+        </p>
+        <SourceList>
+          <Source href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/">
+            <SourceTrigger />
+            <SourceContent
+              title="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+            />
+          </Source>
+          <Source href="https://web.dev/case-studies/earth-webassembly">
+            <SourceTrigger />
+            <SourceContent
+              title="Google Earth and WebAssembly - web.dev"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+            />
+          </Source>
+          <Source href="https://shopify.engineering/shopify-webassembly">
+            <SourceTrigger />
+            <SourceContent
+              title="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+            />
+          </Source>
+          <Source href="https://surma.dev/things/js-to-asc/">
+            <SourceTrigger />
+            <SourceContent
+              title="JavaScript to AssemblyScript - Surma.dev"
+              description="Detailed performance comparison of JS vs AssemblyScript/Wasm for various workloads."
+            />
+          </Source>
+        </SourceList>
+      </div>
+
+      <div>
+        <p class="text-sm text-muted-foreground mb-1">
+          Numbered with favicons (<code>showFavicon</code> per-trigger):
+        </p>
+        <SourceList>
+          <Source href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/">
+            <SourceTrigger label={1} showFavicon />
+            <SourceContent
+              title="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+            />
+          </Source>
+          <Source href="https://web.dev/case-studies/earth-webassembly">
+            <SourceTrigger label={2} showFavicon />
+            <SourceContent
+              title="Google Earth and WebAssembly - web.dev"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+            />
+          </Source>
+          <Source href="https://shopify.engineering/shopify-webassembly">
+            <SourceTrigger label={3} showFavicon />
+            <SourceContent
+              title="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+            />
+          </Source>
+        </SourceList>
+      </div>
+    </div>
+  ),
+};
+
+// ---------------------------------------------------------------------------
+// Numbered Citations (composition) story
+// ---------------------------------------------------------------------------
+
+export const NumberedComposition: Story = {
+  name: 'Numbered Citations (composition)',
+  parameters: {
+    docs: {
+      description: {
+        story: [
+          'The **same** numbered-citation strip as the "Numbered Citations" story — but built entirely from `<kai-sources numbered>` + `<kai-source>` children in markup.',
+          '',
+          'No `sources` JS property is set. The `<kai-sources>` element reads its `<kai-source>` light-DOM children via `MutationObserver` and appends them to the merged source list automatically. The `numbered` boolean attribute then labels each chip with its 1-based index.',
+          '',
+          'Attribute reference for `<kai-source>`:',
+          '- `href` — the URL to link to (domain seeds the default label/favicon)',
+          '- `headline` — hover-card heading (**not** `title` — `title` is a reserved HTML attribute)',
+          '- `description` — hover-card body text',
+          '- `label` — custom chip label (ignored when the parent `<kai-sources>` has `numbered`)',
+          '- `show-favicon` — bare boolean attribute to show the domain favicon',
+          '',
+          '`<kai-sources>` attribute reference:',
+          '- `numbered` — auto-labels all chips with their 1-based index from the merged list',
+          '- `show-favicon` — enables favicons for all children (per-item attribute overrides)',
+          '',
+          '**When to choose composition:** great for static/authored citations in plain HTML or any template language — no JS wiring needed beyond the element registration.',
+        ].join('\n'),
+      },
+    },
+  },
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      // The `numbered` attribute is a boolean — set it imperatively so it is
+      // registered after the element upgrades (avoids timing issues in SSR/Storybook).
+      el?.setAttribute('numbered', '');
+    });
+    return (
+      <div class="flex flex-col gap-6 p-4 w-full max-w-2xl bg-background rounded-xl shadow-lg">
+        <div>
+          <p class="text-sm text-muted-foreground mb-1">
+            Composition: <code>&lt;kai-sources numbered&gt;</code> with <code>&lt;kai-source&gt;</code> children — chips auto-labelled 1, 2, 3, 4:
+          </p>
+          <kai-sources ref={(e: HTMLElement) => (el = e)} style={{ display: 'block' }}>
+            <kai-source
+              href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/"
+              headline="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+            />
+            <kai-source
+              href="https://web.dev/case-studies/earth-webassembly"
+              headline="Google Earth and WebAssembly - web.dev"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+            />
+            <kai-source
+              href="https://shopify.engineering/shopify-webassembly"
+              headline="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+            />
+            <kai-source
+              href="https://surma.dev/things/js-to-asc/"
+              headline="JavaScript to AssemblyScript - Surma.dev"
+              description="Detailed performance comparison of JS vs AssemblyScript/Wasm for various workloads."
+            />
+          </kai-sources>
+        </div>
+
+        <div>
+          <p class="text-sm text-muted-foreground mb-1">
+            Composition without numbering — chips fall back to domain labels:
+          </p>
+          <kai-sources style={{ display: 'block' }}>
+            <kai-source
+              href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/"
+              headline="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+            />
+            <kai-source
+              href="https://web.dev/case-studies/earth-webassembly"
+              headline="Google Earth and WebAssembly - web.dev"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+            />
+            <kai-source
+              href="https://shopify.engineering/shopify-webassembly"
+              headline="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+            />
+          </kai-sources>
+        </div>
+
+        <div>
+          <p class="text-sm text-muted-foreground mb-1">
+            Composition with favicons and custom labels (no <code>numbered</code>):
+          </p>
+          <kai-sources style={{ display: 'block' }}>
+            <kai-source
+              href="https://www.figma.com/blog/webassembly-cut-figmas-load-time-by-3x/"
+              label="Figma"
+              headline="WebAssembly cut Figma's load time by 3x"
+              description="How Figma leveraged WebAssembly to dramatically improve their browser-based design tool performance."
+              show-favicon
+            />
+            <kai-source
+              href="https://web.dev/case-studies/earth-webassembly"
+              label="web.dev"
+              headline="Google Earth and WebAssembly"
+              description="Case study on porting Google Earth's C++ rendering engine to WebAssembly for browser delivery."
+              show-favicon
+            />
+            <kai-source
+              href="https://shopify.engineering/shopify-webassembly"
+              label="Shopify"
+              headline="How Shopify Uses WebAssembly"
+              description="Shopify's journey using WebAssembly for Liquid template parsing in their online store editor."
+              show-favicon
+            />
+          </kai-sources>
+        </div>
+      </div>
+    );
+  },
+};

package/src/stories/docs/Accessibility.mdx

@@ -0,0 +1,119 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Accessibility" />
+
+# Accessibility
+
+`@kitn.ai/ui` targets **WCAG 2.1 Level AA**. The kit is audited with [axe-core](https://github.com/dequelabs/axe-core) (via `scripts/audit-a11y.mjs`) and ships with **0 axe violations** in both light and dark modes. Keyboard navigation is verified with a Playwright browser test suite.
+
+This page describes the accessibility posture, the keyboard model, known limitations, and what you need to do as an integrator.
+
+---
+
+## Color contrast
+
+All text and UI chrome meet WCAG 2.1 AA contrast requirements (4.5:1 for body text, 3:1 for large text and UI components) in the default light and dark palettes.
+
+The `theme` attribute on every element (`light | dark | auto`) controls which token set loads. `auto` (the default) follows the OS `prefers-color-scheme` media query, so users who configure dark mode at the OS level get it automatically. Override either set with `--kai-color-*` tokens — if you do, verify contrast yourself; the kit cannot audit tokens it does not control.
+
+---
+
+## Keyboard operability
+
+Every interactive control is reachable and operable without a mouse.
+
+### Focus order
+
+Tab moves through all focusable controls in DOM order. The prompt textarea, send button, attachment button, toolbar controls (search, mic), header controls (model switcher, context meter), message action buttons, suggestion chips, and conversation list items are all included. Focus rings are always visible — they are not hidden on `:focus`, only on `:focus-visible`.
+
+### Dropdowns and select menus (ModelSwitcher, ChatScopePicker, …)
+
+| Key | Action |
+|---|---|
+| Enter / Space / ↓ | Open the menu |
+| ↑ / ↓ | Move between items |
+| Home / End | Jump to first / last item |
+| Typeahead (letter keys) | Jump to the first item starting with that letter |
+| Enter / Space | Select the focused item |
+| Esc | Close without selecting; focus returns to the trigger |
+| Tab | Close and move focus past the trigger |
+
+Focus always returns to the trigger element after the menu closes, whether closed by Esc, selection, or a click outside.
+
+### Collapsible panels (Reasoning, Tool calls, …)
+
+| Key | Action |
+|---|---|
+| Enter / Space | Toggle expanded / collapsed |
+| Tab | Move into the expanded content |
+| Esc | Collapse (if focused inside) |
+
+### Slash command palette
+
+Typing `/` in the prompt input opens the command palette.
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Navigate items |
+| Home / End | Jump to first / last item |
+| Enter / Tab | Select the focused command (inserts `/label ` into the input with caret at end) |
+| Esc | Close the palette; focus stays in the input |
+
+### Conversation list
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Move between conversations |
+| Enter | Select the focused conversation |
+| Tab | Move through action buttons (if any) |
+
+---
+
+## Accessible names on icon buttons
+
+Every icon-only button (attach, send, mic, search, copy, like, dislike, regenerate, close) carries an accessible name via `aria-label`. Screen readers announce the button's purpose rather than "button" or nothing. Labels use plain language: "Send message", "Attach file", "Copy message", "Thumbs up", and so on.
+
+---
+
+## Tooltips and hover cards
+
+Tooltips and hover cards (on sources, context meter, etc.) are dismissable and persistent per WCAG 2.1 SC 1.4.13 (Content on Hover or Focus):
+
+- They appear on both hover and keyboard focus.
+- Moving the pointer over the tooltip/card content keeps it visible (it does not vanish when the pointer leaves the trigger).
+- They can be dismissed with **Esc** without moving focus.
+
+---
+
+## ARIA landmarks and live regions
+
+- The message list is marked as a log region (`role="log"`, `aria-live="polite"`) so streaming tokens are announced to screen readers without being intrusive.
+- The prompt area is labelled; the textarea carries its placeholder as an accessible name fallback.
+- The conversation sidebar is a navigation landmark (`<nav>`).
+
+---
+
+## Shadow DOM and screen readers
+
+All elements render inside Shadow DOM. Modern screen readers (NVDA + Chrome, JAWS + Chrome, VoiceOver + Safari/Chrome) pierce Shadow DOM correctly. Accessible names, roles, and live regions work as expected.
+
+---
+
+## Audit tooling
+
+Accessibility is verified with:
+
+- **axe-core** (`scripts/audit-a11y.mjs`) — automated rule checks in both light and dark themes. Zero violations at the time of build.
+- **Playwright keyboard tests** — 21-scenario browser test suite covering focus order, dropdown/collapsible/palette keyboard nav, ArrowUp/Down/Home/End/typeahead/Enter/Escape/Tab, and focus-return after close.
+
+The kit does not carry a "WCAG AA certified" certification — no automated tool can certify that. What it does carry is a targeted AA design, an axe-core clean bill, and a passing Playwright keyboard suite.
+
+---
+
+## What integrators need to do
+
+1. **Do not hide focus rings.** The kit renders visible focus rings via `:focus-visible`. Do not add `outline: none` or `outline: 0` in your host-page CSS targeting `*` or the element host.
+2. **Verify contrast if you override tokens.** Use a contrast checker after overriding any `--kai-color-*` token.
+3. **Provide meaningful conversation titles.** The conversation list announces the `title` field to screen readers. "Chat 1" is less useful than "React integration help".
+4. **Set a meaningful `placeholder`.** The textarea placeholder doubles as an accessible name when no label is associated.
+5. **Check your theme choice.** Using `theme="light"` in a page the user has set to dark mode (or vice versa) can create contrast mismatches between kit components and host-page content. `theme="auto"` (the default) avoids this.