@kitnai/chat 0.3.1 → 0.4.0

package/src/elements/prompt-input.tsx

@@ -1,25 +1,84 @@
-import { createSignal } from 'solid-js';
+import { createEffect, createSignal } from 'solid-js';
 import { defineKitnElement } from './define';
 import { DefaultPromptInput } from './default-input';
 import type { AttachmentData } from '../components/attachments';
+import type { SlashCommandItem } from '../components/slash-command';
 
 interface Props extends Record<string, unknown> {
+  /** Controlled value of the input. When set, the host owns the text and must
+   *  update it on `valuechange`; leave unset for uncontrolled behavior. */
   value?: string;
+  /** Placeholder text shown in the empty input. */
   placeholder?: string;
+  /** Disable the input and submit button entirely (non-interactive). */
   disabled?: boolean;
+  /** Show the loading/streaming state and block submit (use while awaiting a
+   *  reply). */
   loading?: boolean;
+  /** Starter prompts shown above the input. Clicking one follows
+   *  `suggestionMode`. Set as a JS property. */
   suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately
+   *  as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: 'submit' | 'fill';
+  /** Slash commands — when set, typing `/` opens the command palette. Set as a
+   *  JS property. */
+  slashCommands?: SlashCommandItem[];
+  /** Command ids to highlight as active. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  /** Show a Search (Globe) button in the left toolbar; clicking it fires a
+   *  `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice`
+   *  event. */
+  voice?: boolean;
+  /** Attachments to seed the input with (so a consumer can pre-populate staged
+   *  files without an upload). Set as a JS property; the element then manages its
+   *  own attachment state from there (add via the paperclip, remove per chip). */
+  attachments?: AttachmentData[];
 }
 
-defineKitnElement<Props>('kitn-prompt-input', {
+/** Events fired by `<kitn-prompt-input>`. */
+interface Events {
+  /** The user submitted the prompt (Enter or send button) with its attachments. */
+  submit: { value: string; attachments: AttachmentData[] };
+  /** The input text changed (fires on every keystroke). */
+  valuechange: { value: string };
+  /** A suggestion was clicked while `suggestion-mode="fill"`. */
+  suggestionclick: { value: string };
+  /** A slash command was chosen from the palette. */
+  slashselect: { command: SlashCommandItem };
+  /** The Search (Globe) toolbar button was clicked. */
+  search: undefined;
+  /** The Voice (Mic) toolbar button was clicked. */
+  voice: undefined;
+}
+
+defineKitnElement<Props, Events>('kitn-prompt-input', {
   value: undefined,
   placeholder: 'Send a message...',
   disabled: false,
   loading: false,
   suggestions: undefined,
-}, (props, { dispatch }) => {
+  suggestionMode: 'submit',
+  slashCommands: undefined,
+  slashActiveIds: undefined,
+  slashCompact: false,
+  search: false,
+  voice: false,
+  attachments: undefined,
+}, (props, { dispatch, flag }) => {
   const [internal, setInternal] = createSignal(props.value ?? '');
-  const [attachments, setAttachments] = createSignal<AttachmentData[]>([]);
+  // Seed staged attachments from the `attachments` property; the element manages
+  // its own state from there (paperclip adds, per-chip remove deletes).
+  const [attachments, setAttachments] = createSignal<AttachmentData[]>(props.attachments ?? []);
+  // Re-seed when the `attachments` property is (re)assigned by the consumer
+  // (e.g. set via a `ref` after mount). Subsequent in-element edits stay local.
+  createEffect(() => {
+    if (props.attachments) setAttachments(props.attachments);
+  });
   const current = () => props.value ?? internal();
 
   const handleChange = (v: string) => { setInternal(v); dispatch('valuechange', { value: v }); };
@@ -27,20 +86,37 @@ defineKitnElement<Props>('kitn-prompt-input', {
     dispatch('submit', { value: current(), attachments: attachments() });
     setAttachments([]);
   };
-  const handleSuggestionClick = (v: string) => { handleChange(v); dispatch('suggestionclick', { value: v }); };
+  const handleSuggestionClick = (v: string) => {
+    if ((props.suggestionMode ?? 'submit') === 'fill') {
+      handleChange(v);
+      dispatch('suggestionclick', { value: v });
+    } else {
+      // Default: behave as if the user typed the suggestion and pressed submit.
+      dispatch('submit', { value: v, attachments: attachments() });
+      setAttachments([]);
+    }
+  };
 
   return (
     <DefaultPromptInput
       value={current()}
       placeholder={props.placeholder}
-      disabled={props.disabled}
-      loading={props.loading}
+      disabled={flag('disabled')}
+      loading={flag('loading')}
       suggestions={props.suggestions}
       attachments={attachments()}
+      slashCommands={props.slashCommands}
+      slashActiveIds={props.slashActiveIds}
+      slashCompact={flag('slashCompact')}
+      search={flag('search')}
+      voice={flag('voice')}
       onValueChange={handleChange}
       onSubmit={handleSubmit}
       onSuggestionClick={handleSuggestionClick}
       onAttachmentsChange={setAttachments}
+      onSearch={() => dispatch('search')}
+      onVoice={() => dispatch('voice')}
+      onSlashSelect={(command) => dispatch('slashselect', { command })}
     />
   );
 });

package/src/elements/prompt-suggestions.tsx

@@ -0,0 +1,58 @@
+import { For } from 'solid-js';
+import { defineKitnElement } from './define';
+import { PromptSuggestion } from '../components/prompt-suggestion';
+
+type Item = string | { label: string; value?: string };
+
+interface Props extends Record<string, unknown> {
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text
+   *  and the emitted value differ. Set as a JS property. */
+  suggestions: Item[];
+  /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
+  variant?: 'outline' | 'ghost' | 'default';
+  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass
+   *  `'sm'` for smaller pills (or `'md'`). */
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+  /** Full-width left-aligned rows instead of pills. */
+  block?: boolean;
+  /** Substring to highlight within each suggestion. */
+  highlight?: string;
+}
+
+/** Events fired by `<kitn-prompt-suggestions>`. */
+interface Events {
+  /** A suggestion was clicked. */
+  select: { value: string };
+}
+
+const labelOf = (s: Item) => (typeof s === 'string' ? s : s.label);
+const valueOf = (s: Item) => (typeof s === 'string' ? s : s.value ?? s.label);
+
+/**
+ * `<kitn-prompt-suggestions>` — a row/list of suggestion chips. Data via the
+ * `suggestions` property; `variant`/`block`/`highlight` attributes; emits
+ * `select`.
+ */
+defineKitnElement<Props, Events>('kitn-prompt-suggestions', {
+  suggestions: [],
+  variant: 'outline',
+  size: undefined,
+  block: false,
+  highlight: undefined,
+}, (props, { dispatch, flag }) => (
+  <div class={flag('block') ? 'flex flex-col gap-2' : 'flex flex-wrap gap-2'}>
+    <For each={props.suggestions}>
+      {(s) => (
+        <PromptSuggestion
+          variant={props.variant}
+          size={props.size}
+          block={flag('block')}
+          highlight={props.highlight}
+          onClick={() => dispatch('select', { value: valueOf(s) })}
+        >
+          {labelOf(s)}
+        </PromptSuggestion>
+      )}
+    </For>
+  </div>
+));

package/src/elements/reasoning.tsx

@@ -0,0 +1,50 @@
+import { defineKitnElement } from './define';
+import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
+import { ChatConfig, useChatConfig } from '../primitives/chat-config';
+
+interface Props extends Record<string, unknown> {
+  /** The reasoning text to display. */
+  text: string;
+  /** Trigger label. */
+  label?: string;
+  /** Controlled open state — set as a property (`el.open = true`). Omit for
+   *  uncontrolled (the trigger toggles it). */
+  open?: boolean;
+  /** While true, auto-expands (and re-collapses when it flips false). */
+  streaming?: boolean;
+  /** Render `text` as markdown. */
+  markdown?: boolean;
+}
+
+/** Events fired by `<kitn-reasoning>`. */
+interface Events {
+  /** Open state changed (via the trigger or streaming auto-open). */
+  openchange: { open: boolean };
+}
+
+/**
+ * `<kitn-reasoning>` — a collapsible reasoning/thinking block that auto-expands
+ * while `streaming`. Text via the `text` property; `markdown`/`streaming` flags;
+ * `open` is a controlled property; emits `openchange`.
+ */
+defineKitnElement<Props, Events>('kitn-reasoning', {
+  text: '',
+  label: 'Reasoning',
+  open: undefined,
+  streaming: false,
+  markdown: true,
+}, (props, { dispatch, flag }) => {
+  const outer = useChatConfig();
+  return (
+    <ChatConfig portalMount={outer.portalMount()}>
+      <Reasoning
+        open={props.open}
+        isStreaming={flag('streaming')}
+        onOpenChange={(open) => dispatch('openchange', { open })}
+      >
+        <ReasoningTrigger>{props.label}</ReasoningTrigger>
+        <ReasoningContent markdown={flag('markdown')}>{props.text}</ReasoningContent>
+      </Reasoning>
+    </ChatConfig>
+  );
+});

package/src/elements/register.ts

@@ -3,6 +3,37 @@
 import './conversation-list';
 import './prompt-input';
 import './chat';
+// Composable leaf elements (spike — see docs/handoff + examples/composable)
+import './thinking-bar';
+import './model-switcher';
+import './attachments';
+// Phase 1 — message-rendering core
+import './message';
+import './markdown';
+import './code-block';
+import './reasoning';
+import './tool';
+// Phase 2 — header / meta
+import './context-meter';
+import './feedback-bar';
+import './chat-scope-picker';
+// Phase 3 — input ecosystem
+// (NB: SlashCommand is context-bound to PromptInput — it observes the input
+//  value via usePromptInput() — so it is NOT a standalone element. It will fold
+//  into <kitn-prompt-input> as a `slash-commands` property in a later pass.)
+import './prompt-suggestions';
+import './file-upload';
+import './voice-input';
+// Phase 4 — indicators & leaves
+import './loader';
+import './text-shimmer';
+import './image';
+import './checkpoint';
+import './message-skills';
+import './source';
+import './response-stream';
+import './empty';
+import './chain-of-thought';
 
 export type { ChatMessage, ChatMessageAction } from './chat-types';
 export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';

package/src/elements/response-stream.tsx

@@ -0,0 +1,40 @@
+import { defineKitnElement } from './define';
+import { ResponseStream, type Mode } from '../components/response-stream';
+
+interface Props extends Record<string, unknown> {
+  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS
+   *  property — async iterables can't be HTML attributes). */
+  text?: string | AsyncIterable<string>;
+  /** Reveal animation. */
+  mode?: Mode;
+  /** Characters/segments per tick. */
+  speed?: number;
+  /** Element tag to render as. */
+  as?: string;
+}
+
+/** Events fired by `<kitn-response-stream>`. */
+interface Events {
+  /** Streaming finished. */
+  complete: void;
+}
+
+/**
+ * `<kitn-response-stream>` — reveals text with a typewriter or fade animation.
+ * Text via the `text` property; `mode`/`speed` attributes; emits `complete`.
+ */
+defineKitnElement<Props, Events>('kitn-response-stream', {
+  text: '',
+  mode: 'typewriter',
+  speed: 20,
+  as: undefined,
+}, (props, { dispatch }) => (
+  <ResponseStream
+    textStream={props.text ?? ''}
+    mode={props.mode}
+    speed={props.speed}
+    as={props.as}
+    class="text-body"
+    onComplete={() => dispatch('complete')}
+  />
+));

package/src/elements/source.tsx

@@ -0,0 +1,67 @@
+import { For, Show } from 'solid-js';
+import { defineKitnElement } from './define';
+import { Source, SourceTrigger, SourceContent, SourceList } from '../components/source';
+
+// --- <kitn-source> — a single citation link with hover preview ---
+
+interface SourceProps extends Record<string, unknown> {
+  /** The URL this citation links to (the domain also seeds the default label/favicon). */
+  href?: string;
+  /** Trigger label (defaults to the domain). */
+  label?: string;
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided — it's a
+   *  global HTML attribute that reflects in a CE constructor and breaks it). */
+  headline?: string;
+  /** Hover-card body text describing the source. */
+  description?: string;
+  /** Show the source's favicon next to the trigger label. */
+  showFavicon?: boolean;
+}
+
+defineKitnElement<SourceProps>('kitn-source', {
+  href: '',
+  label: undefined,
+  headline: '',
+  description: '',
+  showFavicon: false,
+}, (props, { flag }) => (
+  <Show when={props.href}>
+    <Source href={props.href!}>
+      <SourceTrigger label={props.label} showFavicon={flag('showFavicon')} />
+      <SourceContent title={props.headline ?? ''} description={props.description ?? ''} />
+    </Source>
+  </Show>
+));
+
+// --- <kitn-source-list> — a wrapped list of citation links ---
+
+interface SourceItem {
+  href: string;
+  title?: string;
+  description?: string;
+  label?: string;
+  showFavicon?: boolean;
+}
+
+interface SourceListProps extends Record<string, unknown> {
+  /** The sources to render. Set as a JS property. */
+  sources: SourceItem[];
+  /** Show favicons on all items (per-item `showFavicon` overrides). */
+  showFavicon?: boolean;
+}
+
+defineKitnElement<SourceListProps>('kitn-source-list', {
+  sources: [],
+  showFavicon: false,
+}, (props, { flag }) => (
+  <SourceList>
+    <For each={props.sources}>
+      {(s) => (
+        <Source href={s.href}>
+          <SourceTrigger label={s.label} showFavicon={s.showFavicon ?? flag('showFavicon')} />
+          <SourceContent title={s.title ?? ''} description={s.description ?? ''} />
+        </Source>
+      )}
+    </For>
+  </SourceList>
+));

package/src/elements/text-shimmer.tsx

@@ -0,0 +1,28 @@
+import { defineKitnElement } from './define';
+import { TextShimmer } from '../components/text-shimmer';
+
+interface Props extends Record<string, unknown> {
+  /** The text to shimmer. */
+  text?: string;
+  /** Element tag to render as (default `span`). */
+  as?: string;
+  /** Animation duration in seconds. */
+  duration?: number;
+  /** Gradient spread (5–45). */
+  spread?: number;
+}
+
+/**
+ * `<kitn-text-shimmer>` — animated shimmering text. Text via the `text`
+ * attribute; `duration`/`spread` tune the effect.
+ */
+defineKitnElement<Props>('kitn-text-shimmer', {
+  text: '',
+  as: 'span',
+  duration: 4,
+  spread: 20,
+}, (props) => (
+  <TextShimmer as={props.as} duration={props.duration} spread={props.spread} class="text-body">
+    {props.text}
+  </TextShimmer>
+));

package/src/elements/thinking-bar.tsx

@@ -0,0 +1,34 @@
+import { defineKitnElement } from './define';
+import { ThinkingBar } from '../components/thinking-bar';
+
+interface Props extends Record<string, unknown> {
+  /** The shimmering label, e.g. "Thinking…". */
+  text?: string;
+  /** When true, show a "stop" affordance that fires a `stop` event. */
+  stoppable?: boolean;
+  /** Label for the stop affordance. */
+  stopLabel?: string;
+}
+
+/** Events fired by `<kitn-thinking-bar>`. */
+interface Events {
+  /** The "stop / answer now" affordance was clicked. */
+  stop: void;
+}
+
+/**
+ * `<kitn-thinking-bar>` — a pure leaf element: an animated "thinking" indicator
+ * (one of the primitives the batteries-included `<kitn-chat>` does NOT surface).
+ * Config via attributes, the only interaction (`stop`) comes back as an event.
+ */
+defineKitnElement<Props, Events>('kitn-thinking-bar', {
+  text: 'Thinking',
+  stoppable: false,
+  stopLabel: 'Answer now',
+}, (props, { dispatch, flag }) => (
+  <ThinkingBar
+    text={props.text}
+    stopLabel={props.stopLabel}
+    onStop={flag('stoppable') ? () => dispatch('stop') : undefined}
+  />
+));

package/src/elements/tool.tsx

@@ -0,0 +1,23 @@
+import { Show } from 'solid-js';
+import { defineKitnElement } from './define';
+import { Tool, type ToolPart } from '../components/tool';
+
+interface Props extends Record<string, unknown> {
+  /** The tool-call to display. Set as a JS property. */
+  tool?: ToolPart;
+  /** Start expanded. */
+  open?: boolean;
+}
+
+/**
+ * `<kitn-tool>` — a collapsible tool-call panel (input/output inspection with a
+ * state badge). Data via the `tool` property; `open` flag starts it expanded.
+ */
+defineKitnElement<Props>('kitn-tool', {
+  tool: undefined,
+  open: false,
+}, (props, { flag }) => (
+  <Show when={props.tool}>
+    <Tool toolPart={props.tool!} defaultOpen={flag('open')} />
+  </Show>
+));

package/src/elements/voice-input.tsx

@@ -0,0 +1,41 @@
+import { defineKitnElement } from './define';
+import { VoiceInput } from '../components/voice-input';
+
+interface Props extends Record<string, unknown> {
+  /**
+   * Transcriber the host supplies — records audio, returns the text. This is a
+   * **function-valued property** (`el.transcribe = async blob => '...'`) because
+   * a value-returning callback can't be modelled as a fire-and-forget event.
+   */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kitn-voice-input>`. */
+interface Events {
+  /** Raw audio captured (before transcription) — for hosts that prefer to
+   *  handle transcription themselves instead of via the `transcribe` property. */
+  audiocaptured: { blob: Blob };
+  /** Transcription completed (the `transcribe` property resolved). */
+  transcription: { text: string };
+}
+
+/**
+ * `<kitn-voice-input>` — a mic button that records and transcribes. The
+ * canonical **function-property** element: set `el.transcribe` to your async
+ * transcriber. Also emits `audiocaptured` (raw blob) and `transcription` (text).
+ */
+defineKitnElement<Props, Events>('kitn-voice-input', {
+  transcribe: undefined,
+  disabled: false,
+}, (props, { dispatch, flag }) => (
+  <VoiceInput
+    disabled={flag('disabled')}
+    onTranscribe={async (blob) => {
+      dispatch('audiocaptured', { blob });
+      return props.transcribe ? props.transcribe(blob) : '';
+    }}
+    onTranscription={(text) => dispatch('transcription', { text })}
+  />
+));

package/src/index.ts

@@ -34,7 +34,6 @@ export { Separator } from './ui/separator';
 export { ResizablePanelGroup, ResizablePanel, ResizableHandle } from './ui/resizable';
 export type { ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps } from './ui/resizable';
 export { Skeleton } from './ui/skeleton';
-export { Dialog, DialogTrigger, DialogContent } from './ui/dialog';
 
 // Layer 3: AI/Feature Components
 export {

package/src/primitives/chat-config.tsx

@@ -14,7 +14,7 @@ export interface ChatConfigValue {
 }
 
 const defaultConfig: ChatConfigValue = {
-  proseSize: () => 'base' as ProseSize,
+  proseSize: () => 'sm' as ProseSize,
   codeTheme: () => 'github-dark-dimmed',
   portalMount: () => undefined,
   codeHighlight: () => true,
@@ -37,7 +37,7 @@ export interface ChatConfigProps {
  */
 export function ChatConfig(props: ChatConfigProps) {
   const value: ChatConfigValue = {
-    proseSize: () => props.proseSize ?? 'base',
+    proseSize: () => props.proseSize ?? 'sm',
     codeTheme: () => props.codeTheme ?? 'github-dark-dimmed',
     portalMount: () => props.portalMount,
     codeHighlight: () => props.codeHighlight ?? true,

package/src/stories/docs/Accessibility.mdx

@@ -0,0 +1,119 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Accessibility" />
+
+# Accessibility
+
+`@kitnai/chat` 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 `--kitn-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 `--kitn-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.