@kitnai/chat 0.6.0 → 0.8.0

package/src/stories/examples/ChoosingComponents.mdx

@@ -0,0 +1,94 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Examples/Choosing components" />
+
+# Choosing components
+
+`@kitnai/chat` ships ~32 `kc-*` web components across **three tiers**. This page is
+the mental model for **which tier to reach for** — so you don't have to read all 32
+per-element pages to know where to start.
+
+> The per-element **When / How / Placement** notes live on each element's own story
+> (under **Web Components / kc-\***). This page is the missing *overview* — the
+> decision guide, not the per-element prose.
+
+## The three tiers
+
+### 1. Flagship / shells — _drop-in, the 90% path_
+
+`<kc-chat>` · `<kc-workspace>`
+
+A **whole surface in one tag**. Set `messages`, listen for `submit`, and you have a
+working chat in minutes. `<kc-workspace>` adds the conversation sidebar + header
+around it. These pre-wire the leaf components for you.
+
+**Reach for these first.** Only step down a tier when the flagship doesn't fit.
+
+```html
+<kc-chat id="chat" chat-title="Assistant" style="display:block;height:560px"></kc-chat>
+<script type="module">
+  import '@kitnai/chat/elements';
+  const chat = document.getElementById('chat');
+  chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }];
+  chat.addEventListener('submit', (e) => {/* call your model */});
+</script>
+```
+
+### 2. Leaf features — _compose your own layout_
+
+`<kc-conversations>` · `<kc-message>` · `<kc-tool>` · `<kc-reasoning>` ·
+`<kc-chain-of-thought>` · `<kc-thinking-bar>` · `<kc-response-stream>` ·
+`<kc-source>` / `<kc-sources>` · `<kc-skills>` · `<kc-prompt-input>` ·
+`<kc-suggestions>` · `<kc-file-upload>` · `<kc-voice-input>` · `<kc-attachments>` ·
+`<kc-model-switcher>` · `<kc-context>` · `<kc-scope-picker>` · `<kc-checkpoint>` ·
+`<kc-feedback-bar>` · `<kc-artifact>` · `<kc-resizable>`
+
+The **chat-specific building blocks**. Reach for these when the flagship layout
+doesn't fit — you want a custom three-up shell, an inspector/canvas panel, a bespoke
+header, or to render messages your own way. You own the data flow and the event
+wiring; the leaves render.
+
+`<kc-resizable>` is the **layout spine** for compose-your-own shells; `<kc-artifact>`
+is the **preview/canvas** panel. See the worked example in
+**Examples / Composed chat shell**.
+
+### 3. Primitives — _reusable anywhere_
+
+`<kc-code-block>` · `<kc-markdown>` · `<kc-loader>` · `<kc-text-shimmer>` ·
+`<kc-image>` · `<kc-empty>` · `<kc-file-tree>`
+
+**Not chat-specific.** A code viewer, a markdown renderer, loaders, an image with a
+skeleton, an empty-state, a file explorer — useful in any app. They happen to be
+used inside the chat components, but ship public so you can reuse them standalone.
+
+## The decision test
+
+> **"Would a non-chat app reuse this?"**
+>
+> - **Yes** → it's a **primitive** (tier 3). A docs site wants `<kc-markdown>`; a
+>   dashboard wants `<kc-loader>`; a file browser wants `<kc-file-tree>`.
+> - **No, but it's a chat building block** → it's a **leaf feature** (tier 2).
+>   `<kc-message>`, `<kc-tool>`, `<kc-conversations>` only make sense in a chat.
+> - **I just want a working chat** → use the **flagship** (tier 1). `<kc-chat>`.
+
+## How they fit together
+
+```
+flagship            <kc-chat> / <kc-workspace>        ← pre-wires the leaves
+   ▲ composed from
+leaf features       <kc-conversations> <kc-message> <kc-prompt-input> <kc-artifact> …
+   ▲ composed from / laid out by
+primitives + layout <kc-markdown> <kc-code-block> <kc-loader> … inside <kc-resizable>
+```
+
+Start at the top. Drop a tier each time you need more control.
+
+## Where to go next
+
+- **Examples / Catalog** — every component with sample data + copy-pasteable
+  markup. Answers _"what exists?"_.
+- **Examples / Composed chat shell** — a real chat assembled from leaves inside
+  `<kc-resizable>`, shown next to the `<kc-chat>` drop-in so the contrast is
+  explicit. Answers _"how do I wire it myself, and when should I?"_.
+- **Web Components / kc-\*** — the per-element pages with full API + the When /
+  How / Placement notes.

package/src/stories/examples/sample-data.ts

@@ -0,0 +1,79 @@
+// Shared sample data for the Examples/* web-component stories. Mirrors the data
+// in examples/composable/main.js so the Storybook catalog matches the external
+// showcase. Plain data only — no DOM wiring here.
+
+export const models = [
+  { id: 'opus', name: 'Claude Opus', provider: 'Anthropic' },
+  { id: 'sonnet', name: 'Claude Sonnet', provider: 'Anthropic' },
+  { id: 'haiku', name: 'Claude Haiku', provider: 'Anthropic' },
+];
+
+export const context = {
+  usedTokens: 48200,
+  maxTokens: 200000,
+  inputTokens: 31000,
+  outputTokens: 17200,
+  estimatedCost: 0.42,
+};
+
+/** An inline SVG data-URL — handy for attachment thumbnails without a server. */
+export function imgData(fill: string, glyph: string): string {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="96" height="96"><rect width="96" height="96" rx="12" fill="${fill}"/><text x="48" y="60" font-size="42" text-anchor="middle" fill="white">${glyph}</text></svg>`;
+  return 'data:image/svg+xml;utf8,' + encodeURIComponent(svg);
+}
+
+export const attachments = [
+  { id: '1', type: 'file', filename: 'architecture.png', mediaType: 'image/png', url: imgData('#7c3aed', '◆') },
+  { id: '2', type: 'file', filename: 'spec.pdf', mediaType: 'application/pdf' },
+  { id: '3', type: 'source-document', title: 'kitn.dev/docs', filename: 'kitn.dev' },
+];
+
+export const conversations = [
+  { id: 'c1', title: 'Web component architecture', scope: { type: 'document' }, messageCount: 12, lastMessageAt: '2026-06-11T10:00:00Z', updatedAt: '2026-06-11T10:00:00Z' },
+  { id: 'c2', title: 'Theming & tokens', scope: { type: 'document' }, messageCount: 5, lastMessageAt: '2026-06-10T09:00:00Z', updatedAt: '2026-06-10T09:00:00Z' },
+  { id: 'c3', title: 'Publishing pipeline', scope: { type: 'document' }, messageCount: 8, lastMessageAt: '2026-06-09T09:00:00Z', updatedAt: '2026-06-09T09:00:00Z' },
+];
+
+export const slashCommands = [
+  { id: 'summarize', label: '/summarize', description: 'Summarize the conversation', category: 'Actions' },
+  { id: 'translate', label: '/translate', description: 'Translate the last message', category: 'Actions' },
+  { id: 'image', label: '/image', description: 'Generate an image', category: 'Tools' },
+];
+
+export const sources = [
+  { href: 'https://kitn.dev', title: 'kitn — the kit', description: 'Composable SolidJS + web-component chat UI.', showFavicon: true },
+  { href: 'https://solidjs.com', title: 'SolidJS', description: 'A reactive UI library.', showFavicon: true },
+];
+
+/** A rich assistant turn — reasoning + a tool call + an attachment + actions. */
+export const assistantMessage = {
+  id: 'm-a',
+  role: 'assistant',
+  content: "Here's the plan, with a quick code sample:\n```js\nconst kit = useKitn();\n```",
+  reasoning: { text: 'The user wants X, so I should do Y then Z.', label: 'Reasoning' },
+  tools: [{ type: 'search', state: 'output-available', input: { query: 'kitn docs' }, output: { hits: 3 } }],
+  attachments: [attachments[0]],
+  actions: ['copy', 'like', 'dislike', 'regenerate'],
+};
+
+export const userMessage = { id: 'm-u', role: 'user', content: 'How do I compose these myself?' };
+
+export const cotSteps = [
+  { label: 'Understand the request', content: 'The user wants a composable set.' },
+  { label: 'Design the API', content: 'Route 1: variant + flags + events.' },
+  { label: 'Build & verify' },
+];
+
+/** A short thread for the composed-shell + drop-in stories. */
+export const thread = [
+  { id: '1', role: 'user', content: 'Can you sketch a composable chat shell?' },
+  {
+    id: '2',
+    role: 'assistant',
+    content:
+      'Sure. A shell is just a layout (`<kc-resizable>`) wrapping leaf components:\n\n```html\n<kc-conversations></kc-conversations>\n<kc-message></kc-message>\n<kc-prompt-input></kc-prompt-input>\n```\n\nYou own the data + events; the leaves render.',
+    reasoning: { text: 'Lay out list | chat | artifact, then wire submit + select.', label: 'Reasoning' },
+    tools: [{ type: 'plan_layout', state: 'output-available', input: { panels: 3 }, output: { ok: true } }],
+    actions: ['copy', 'like', 'dislike', 'regenerate'],
+  },
+];

package/src/stories/message-actions.stories.tsx

@@ -46,10 +46,10 @@ async fn fetch_user(id: u64) -> Result<User, AppError> {
 Use \`anyhow::Result\` for applications and \`thiserror\` for libraries to define custom error types.`}
           </MessageContent>
           <MessageActions class="opacity-0 group-hover:opacity-100 transition-opacity">
-            <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><RefreshCw class="size-3.5" /></Button>
+            <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>
+            <Button variant="ghost" size="icon-sm" aria-label="Regenerate response"><RefreshCw class="size-3.5" /></Button>
           </MessageActions>
         </div>
       </Message>
@@ -88,12 +88,12 @@ Import Tailwind in your main CSS file:
 \`\`\``}
           </MessageContent>
           <MessageActions>
-            <Button variant="ghost" size="icon-sm"><Copy class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><ThumbsDown class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><RefreshCw class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><Share class="size-3.5" /></Button>
-            <Button variant="ghost" size="icon-sm"><Bookmark class="size-3.5" /></Button>
+            <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>
+            <Button variant="ghost" size="icon-sm" aria-label="Regenerate response"><RefreshCw class="size-3.5" /></Button>
+            <Button variant="ghost" size="icon-sm" aria-label="Share"><Share class="size-3.5" /></Button>
+            <Button variant="ghost" size="icon-sm" aria-label="Bookmark"><Bookmark class="size-3.5" /></Button>
           </MessageActions>
         </div>
       </Message>
@@ -120,11 +120,11 @@ export const WithCopyConfirmation: Story = {
               The current LTS version of Node.js is 22.x, which includes built-in support for the fetch API, test runner, and watch mode.
             </MessageContent>
             <MessageActions>
-              <Button variant="ghost" size="icon-sm" onClick={handleCopy}>
+              <Button variant="ghost" size="icon-sm" aria-label={copied() ? 'Copied' : 'Copy message'} onClick={handleCopy}>
                 {copied() ? <Check class="size-3.5 text-green-500" /> : <Copy class="size-3.5" />}
               </Button>
-              <Button variant="ghost" size="icon-sm"><ThumbsUp class="size-3.5" /></Button>
-              <Button variant="ghost" size="icon-sm"><ThumbsDown 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>

package/src/stories/pattern-centered-conversation.stories.tsx

@@ -64,8 +64,8 @@ export const Focused: Story = {
                       {answer}
                     </MessageContent>
                     <MessageActions class="-ml-2.5 flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
-                      <Button variant="ghost" size="icon-sm" class="rounded-full"><Copy class="size-3.5" /></Button>
-                      <Button variant="ghost" size="icon-sm" class="rounded-full"><ThumbsUp class="size-3.5" /></Button>
+                      <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Copy message"><Copy class="size-3.5" /></Button>
+                      <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Good response"><ThumbsUp class="size-3.5" /></Button>
                     </MessageActions>
                   </div>
                 </Message>
@@ -79,7 +79,7 @@ export const Focused: Story = {
               <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
                 <PromptInputTextarea placeholder="Reply…" class="min-h-[44px] pt-3 pl-4" />
                 <PromptInputActions class="mt-2 flex w-full items-center justify-end gap-2 px-3 pb-3">
-                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()} aria-label="Send message">
                     <ArrowUp class="size-4" />
                   </Button>
                 </PromptInputActions>

package/src/stories/pattern-docked-widget.stories.tsx

@@ -79,7 +79,7 @@ export const SupportAssistant: Story = {
               <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
                 <PromptInputTextarea placeholder="Message support…" class="min-h-[40px] pt-2.5 pl-3.5" />
                 <PromptInputActions class="mt-1.5 flex w-full items-center justify-end gap-2 px-2.5 pb-2.5">
-                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()} aria-label="Send message">
                     <ArrowUp class="size-4" />
                   </Button>
                 </PromptInputActions>

package/src/stories/pattern-empty-state.stories.tsx

@@ -59,10 +59,10 @@ export const NewChat: Story = {
                 <PromptInputTextarea placeholder="Ask anything…" class="min-h-[44px] pt-3 pl-4" />
                 <PromptInputActions class="mt-2 flex w-full items-center justify-between gap-2 px-3 pb-3">
                   <div class="flex items-center gap-2">
-                    <Button variant="outline" size="icon-sm" class="rounded-full"><Plus class="size-4" /></Button>
-                    <Button variant="outline" size="sm" class="rounded-full gap-1"><Globe class="size-4" />Search</Button>
+                    <Button variant="outline" size="icon-sm" class="rounded-full" aria-label="Add"><Plus class="size-4" /></Button>
+                    <Button variant="outline" size="sm" class="rounded-full gap-1" aria-label="Search the web"><Globe class="size-4" />Search</Button>
                   </div>
-                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()} aria-label="Send message">
                     <ArrowUp class="size-4" />
                   </Button>
                 </PromptInputActions>

package/src/stories/prompt-input-variants.stories.tsx

@@ -24,7 +24,7 @@ export const BasicInput: Story = {
         <PromptInput value={value()} onValueChange={setValue} onSubmit={() => setValue('')}>
           <PromptInputTextarea placeholder="Ask anything..." />
           <PromptInputActions class="justify-end">
-            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()}>
+            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()} aria-label="Send message">
               <ArrowUp class="size-4" />
             </Button>
           </PromptInputActions>
@@ -72,7 +72,7 @@ export const WithSuggestions: Story = {
         <PromptInput value={value()} onValueChange={setValue} onSubmit={() => setValue('')}>
           <PromptInputTextarea placeholder="Ask about this document..." />
           <PromptInputActions class="justify-end">
-            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()}>
+            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()} aria-label="Send message">
               <ArrowUp class="size-4" />
             </Button>
           </PromptInputActions>
@@ -93,12 +93,12 @@ export const WithActionButtons: Story = {
           <PromptInputTextarea placeholder="Message..." />
           <PromptInputActions class="justify-between">
             <div class="flex items-center gap-1">
-              <Button variant="ghost" size="icon-sm"><Paperclip class="size-4 text-muted-foreground" /></Button>
-              <Button variant="ghost" size="icon-sm"><Globe class="size-4 text-muted-foreground" /></Button>
-              <Button variant="ghost" size="icon-sm"><Mic class="size-4 text-muted-foreground" /></Button>
-              <Button variant="ghost" size="icon-sm"><Sparkles class="size-4 text-muted-foreground" /></Button>
+              <Button variant="ghost" size="icon-sm" aria-label="Attach file"><Paperclip class="size-4 text-muted-foreground" /></Button>
+              <Button variant="ghost" size="icon-sm" aria-label="Search the web"><Globe class="size-4 text-muted-foreground" /></Button>
+              <Button variant="ghost" size="icon-sm" aria-label="Voice input"><Mic class="size-4 text-muted-foreground" /></Button>
+              <Button variant="ghost" size="icon-sm" aria-label="AI suggestions"><Sparkles class="size-4 text-muted-foreground" /></Button>
             </div>
-            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()}>
+            <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()} aria-label="Send message">
               <ArrowUp class="size-4" />
             </Button>
           </PromptInputActions>
@@ -119,9 +119,9 @@ export const StreamingState: Story = {
           <PromptInputActions class="justify-between">
             <div class="flex items-center gap-2">
               <Loader variant="typing" size="sm" />
-              <span class="text-xs text-muted-foreground">Generating...</span>
+              <span class="text-xs text-foreground">Generating...</span>
             </div>
-            <Button variant="outline" size="icon-sm" class="rounded-full">
+            <Button variant="outline" size="icon-sm" class="rounded-full" aria-label="Stop">
               <Square class="size-3" />
             </Button>
           </PromptInputActions>
@@ -135,9 +135,9 @@ export const StreamingState: Story = {
           <PromptInputActions class="justify-between">
             <div class="flex items-center gap-2">
               <Loader variant="dots" size="sm" />
-              <span class="text-xs text-muted-foreground">Thinking...</span>
+              <span class="text-xs text-foreground">Thinking...</span>
             </div>
-            <Button variant="outline" size="icon-sm" class="rounded-full">
+            <Button variant="outline" size="icon-sm" class="rounded-full" aria-label="Stop">
               <Square class="size-3" />
             </Button>
           </PromptInputActions>
@@ -166,8 +166,8 @@ export const WithModelSelector: Story = {
           <PromptInputActions class="justify-between">
             <ModelSwitcher models={models} currentModelId={modelId()} onModelChange={setModelId} />
             <div class="flex items-center gap-1">
-              <Button variant="ghost" size="icon-sm"><Paperclip class="size-4 text-muted-foreground" /></Button>
-              <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()}>
+              <Button variant="ghost" size="icon-sm" aria-label="Attach file"><Paperclip class="size-4 text-muted-foreground" /></Button>
+              <Button variant="default" size="icon-sm" class="rounded-full" disabled={!value()} aria-label="Send message">
                 <ArrowUp class="size-4" />
               </Button>
             </div>

package/src/stories/streaming-response.stories.tsx

@@ -107,7 +107,7 @@ export const TypewriterStream: Story = {
               <PromptInput onSubmit={startStream}>
                 <PromptInputTextarea placeholder="Click send to start streaming..." />
                 <PromptInputActions class="justify-end">
-                  <Button variant="default" size="icon-sm" class="rounded-full" onClick={startStream}>
+                  <Button variant="default" size="icon-sm" class="rounded-full" onClick={startStream} aria-label="Send message">
                     <ArrowUp class="size-4" />
                   </Button>
                 </PromptInputActions>
@@ -167,8 +167,8 @@ export const WaitingForFirstToken: Story = {
         <PromptInput disabled isLoading>
           <PromptInputTextarea placeholder="Waiting..." />
           <PromptInputActions class="justify-between">
-            <span class="text-xs text-muted-foreground">Waiting for response...</span>
-            <Button variant="outline" size="icon-sm" class="rounded-full">
+            <span class="text-xs text-foreground">Waiting for response...</span>
+            <Button variant="outline" size="icon-sm" class="rounded-full" aria-label="Stop">
               <Square class="size-3" />
             </Button>
           </PromptInputActions>

package/src/stories/typography.stories.tsx

@@ -35,8 +35,8 @@ function TypographyScale() {
       <p class="text-muted-foreground mb-6 text-sm">
         Defined once in <code class="text-code-foreground">theme.css</code>. Each token generates a Tailwind utility
         (<code class="text-code-foreground">text-meta</code>, …). To restyle the kit's typography globally, override the
-        namespaced <code class="text-code-foreground">--kitn-text-*</code> token on <code class="text-code-foreground">:root</code> —
-        it pierces the Shadow&nbsp;DOM exactly like the <code class="text-code-foreground">--kitn-color-*</code> tokens. (The bare
+        namespaced <code class="text-code-foreground">--kc-text-*</code> token on <code class="text-code-foreground">:root</code> —
+        it pierces the Shadow&nbsp;DOM exactly like the <code class="text-code-foreground">--kc-color-*</code> tokens. (The bare
         <code class="text-code-foreground"> --text-*</code> names stay internal, so a host's own tokens can't collide.)
       </p>
 
@@ -60,8 +60,8 @@ function TypographyScale() {
 
       <h3 class="mt-8 mb-2 text-sm font-semibold">Override example</h3>
       <pre class="bg-muted text-foreground overflow-auto rounded-lg p-3 font-mono text-xs">{`:root {
-  --kitn-text-body: 0.9375rem;   /* bump the reading size to 15px */
-  --kitn-text-meta: 0.8125rem;   /* and the control size to 13px */
+  --kc-text-body: 0.9375rem;   /* bump the reading size to 15px */
+  --kc-text-meta: 0.8125rem;   /* and the control size to 13px */
 }`}</pre>
       <p class="text-muted-foreground mt-2 text-xs">
         Reading text in messages / input / markdown additionally scales with the

package/src/ui/avatar.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Avatar } from './avatar';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Avatar',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A small, rounded **avatar** that renders an image when `src` is provided and falls back to short initials otherwise.',
-          '**When to use:** to identify the author of a message, a conversation participant, or the current user in a header or list.',
-          '**How to use:** always pass a `fallback` (1–2 initials) and a `size`. Provide `src`/`alt` when you have an image; if the image is missing or fails, the `fallback` text shows instead.',
-          '**Placement:** message rows (next to assistant/user content), conversation list items, account menus, and headers.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A small, rounded **avatar** that renders an image when `src` is provided and falls back to short initials otherwise.',
+        '**When to use:** to identify the author of a message, a conversation participant, or the current user in a header or list.',
+        '**How to use:** always pass a `fallback` (1–2 initials) and a `size`. Provide `src`/`alt` when you have an image; if the image is missing or fails, the `fallback` text shows instead.',
+        '**Placement:** message rows (next to assistant/user content), conversation list items, account menus, and headers.',
+      ]),
     },
   },
   argTypes: {

package/src/ui/badge.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Badge } from './badge';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Badge',
@@ -9,14 +10,12 @@ const meta = {
     layout: 'padded',
     docs: {
       controls: { exclude: ['use:eventListener'] },
-      description: {
-        component: [
-          'A compact pill **badge** for short status text, counts, or citation markers, rendered as an inline `<span>`.',
-          '**When to use:** to annotate a count (unread, results), tag a status/label, or mark an inline source citation in assistant output.',
-          '**How to use:** choose a `variant` (`default` label, `count` numeric pill, `citation` clickable source marker) and pass the text or number as children.',
-          '**Placement:** inline with message text (citations), next to titles or list items (labels), and on toolbar/icon buttons (counts).',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A compact pill **badge** for short status text, counts, or citation markers, rendered as an inline `<span>`.',
+        '**When to use:** to annotate a count (unread, results), tag a status/label, or mark an inline source citation in assistant output.',
+        '**How to use:** choose a `variant` (`default` label, `count` numeric pill, `citation` clickable source marker) and pass the text or number as children.',
+        '**Placement:** inline with message text (citations), next to titles or list items (labels), and on toolbar/icon buttons (counts).',
+      ]),
     },
   },
   argTypes: {

package/src/ui/button.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { fn } from 'storybook/test';
 import { Button } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
 
 /**
  * Convention exemplar — every component story should follow this shape:
@@ -15,14 +16,12 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A clickable button with style **variants** and **sizes**, built on a native `<button>` (all standard button attributes pass through).',
-          '**When to use:** any user-triggered action — submitting input, toolbar/icon actions, confirming or dismissing. Use `default` for the primary action, `ghost`/`outline` for secondary or low-emphasis actions.',
-          '**How to use:** set `variant` and `size`, pass label or an icon as children, and wire `onClick`. For icon-only buttons use `size="icon"` / `"icon-sm"` and include an `aria-label`.',
-          '**Placement:** prompt action bars, message action rows, dialogs, toolbars, and empty-state CTAs.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A clickable button with style **variants** and **sizes**, built on a native `<button>` (all standard button attributes pass through).',
+        '**When to use:** any user-triggered action — submitting input, toolbar/icon actions, confirming or dismissing. Use `default` for the primary action, `ghost`/`outline` for secondary or low-emphasis actions.',
+        '**How to use:** set `variant` and `size`, pass label or an icon as children, and wire `onClick`. For icon-only buttons use `size="icon"` / `"icon-sm"` and include an `aria-label`.',
+        '**Placement:** prompt action bars, message action rows, dialogs, toolbars, and empty-state CTAs.',
+      ]),
     },
   },
   argTypes: {
@@ -73,7 +72,7 @@ type Story = StoryObj<typeof meta>;
  *
  * Note: `Button` is a SolidJS *component* (a scoped import), not a global custom
  * element, so the unprefixed name can't conflict with anything — alias on import
- * if a host already has a `Button`. Only the web components (`<kitn-chat>`, …)
+ * if a host already has a `Button`. Only the web components (`<kc-chat>`, …)
  * are prefixed, because those claim global custom-element tag names.
  */
 const IMPORT = `import { Button } from '@kitnai/chat';`;

package/src/ui/button.tsx

@@ -10,6 +10,7 @@ const buttonVariants = cva(
         default: 'bg-primary text-primary-foreground hover:bg-primary/90',
         ghost: 'hover:bg-muted text-foreground',
         outline: 'bg-muted/50 text-foreground hover:bg-muted',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
       },
       size: {
         sm: 'h-8 px-3 text-xs rounded-md',

package/src/ui/collapsible.stories.tsx

@@ -1,5 +1,6 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { Collapsible, CollapsibleTrigger, CollapsibleContent } from './collapsible';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Collapsible',
@@ -8,13 +9,11 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A two-state disclosure that expands and collapses a region of content, animating height via a CSS `grid-template-rows` `0fr` → `1fr` transition (no JS measurement, no layout thrash). The trigger carries `aria-expanded`/`aria-controls` and the collapsed content is `inert`, so it is removed from tab order and the accessibility tree. Works controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).',
-          '**When to use:** to hide secondary detail behind a toggle — a reasoning/"chain of thought" panel, a tool-call payload, an expandable conversation group, an FAQ row.',
-          '**How to use:** wrap `CollapsibleTrigger` and `CollapsibleContent` in a `Collapsible`. The trigger renders a `<button>` by default; pass `as` to render a custom element.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A two-state disclosure that expands and collapses a region of content, animating height via a CSS `grid-template-rows` `0fr` → `1fr` transition (no JS measurement, no layout thrash). The trigger carries `aria-expanded`/`aria-controls` and the collapsed content is `inert`, so it is removed from tab order and the accessibility tree. Works controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`).',
+        '**When to use:** to hide secondary detail behind a toggle — a reasoning/"chain of thought" panel, a tool-call payload, an expandable conversation group, an FAQ row.',
+        '**How to use:** wrap `CollapsibleTrigger` and `CollapsibleContent` in a `Collapsible`. The trigger renders a `<button>` by default; pass `as` to render a custom element.',
+      ]),
     },
   },
   render: () => <CollapsibleDemo defaultOpen />,

package/src/ui/dropdown.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { createSignal } from 'solid-js';
 import { Dropdown, DropdownTrigger, DropdownContent, DropdownItem } from './dropdown';
 import { buttonVariants } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/Dropdown',
@@ -10,13 +11,11 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'An accessible menu that opens from a trigger, built on the kit\'s DIY overlay core (no third-party dependency). Implements the WAI-ARIA menu-button pattern: `aria-haspopup`/`aria-expanded` wiring, roving focus with Arrow/Home/End, type-ahead, Escape/outside-click dismissal, and focus return to the trigger. Portals into the active shadow root and resolves focus through `getRootNode()` so roving focus works inside web components.',
-          '**When to use:** for a list of *actions* or single-choice options triggered by a button — overflow "⋯" menus, model pickers, scope selectors. For hover-only context use `HoverCard`; for a label use `Tooltip`.',
-          '**How to use:** compose `Dropdown` › `DropdownTrigger` (the button) + `DropdownContent` › one `DropdownItem` per action. Give each item an `onSelect` handler — selecting also closes the menu.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'An accessible menu that opens from a trigger, built on the kit\'s DIY overlay core (no third-party dependency). Implements the WAI-ARIA menu-button pattern: `aria-haspopup`/`aria-expanded` wiring, roving focus with Arrow/Home/End, type-ahead, Escape/outside-click dismissal, and focus return to the trigger. Portals into the active shadow root and resolves focus through `getRootNode()` so roving focus works inside web components.',
+        '**When to use:** for a list of *actions* or single-choice options triggered by a button — overflow "⋯" menus, model pickers, scope selectors. For hover-only context use `HoverCard`; for a label use `Tooltip`.',
+        '**How to use:** compose `Dropdown` › `DropdownTrigger` (the button) + `DropdownContent` › one `DropdownItem` per action. Give each item an `onSelect` handler — selecting also closes the menu.',
+      ]),
     },
   },
   render: () => <DropdownDemo />,

package/src/ui/hover-card.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { HoverCard } from './hover-card';
 import { Button } from './button';
+import { componentDescription } from '../stories/docs/element-controls';
 
 const meta = {
   title: 'UI/HoverCard',
@@ -9,13 +10,11 @@ const meta = {
   parameters: {
     layout: 'padded',
     docs: {
-      description: {
-        component: [
-          'A floating card that opens when its trigger is hovered or focused, built on the kit\'s DIY overlay core (positioning + dismiss + presence — no third-party dependency). Portals into the active shadow root so it never clips, and a transparent "safe bridge" keeps it open while the pointer travels from trigger to card.',
-          '**When to use:** to reveal supplementary, non-essential context on hover — a user/profile preview, a link or citation preview, an attachment summary. For an actionable menu use `Dropdown`; for a one-line label use `Tooltip`.',
-          '**How to use:** pass the trigger element as `trigger` and the card body as `children`. Tune `openDelay` / `closeDelay` (ms) to taste.',
-        ].join('\n\n'),
-      },
+      description: componentDescription([
+        'A floating card that opens when its trigger is hovered or focused, built on the kit\'s DIY overlay core (positioning + dismiss + presence — no third-party dependency). Portals into the active shadow root so it never clips, and a transparent "safe bridge" keeps it open while the pointer travels from trigger to card.',
+        '**When to use:** to reveal supplementary, non-essential context on hover — a user/profile preview, a link or citation preview, an attachment summary. For an actionable menu use `Dropdown`; for a one-line label use `Tooltip`.',
+        '**How to use:** pass the trigger element as `trigger` and the card body as `children`. Tune `openDelay` / `closeDelay` (ms) to taste.',
+      ]),
     },
   },
   argTypes: {