@kitnai/chat 0.7.0 → 0.8.1

package/src/stories/docs/Introduction.mdx

@@ -13,9 +13,9 @@ Message threads, prompt inputs, streaming responses, markdown + code rendering,
 
 ## Why @kitnai/chat
 
-- **Works in any framework** — drop in the framework-agnostic **web components** (`<kitn-chat>`) and they just work in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS, so SolidJS apps can also import the components natively for full compositional control.
+- **Works in any framework** — drop in the framework-agnostic **web components** (`<kc-chat>`) and they just work in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS, so SolidJS apps can also import the components natively for full compositional control.
 - **Zero style conflicts** — the web components render in **Shadow DOM**, so the host page's CSS can't leak in and the kit's Tailwind can't leak out.
-- **Lightweight** — a markdown-only `<kitn-chat>` is **~61 KB gzip**, a single file. Syntax highlighting loads **on demand, per language, with no WASM** — and never loads at all if you don't render code.
+- **Lightweight** — a markdown-only `<kc-chat>` is **~61 KB gzip**, a single file. Syntax highlighting loads **on demand, per language, with no WASM** — and never loads at all if you don't render code.
 - **~50 composable components** across three layers: headless primitives → accessible UI primitives (built in-house, WCAG 2.1 AA — no third-party UI dependency) → AI feature components.
 - **Themeable** — restyle everything by overriding a handful of `--color-*` design tokens.
 
@@ -26,7 +26,7 @@ The kit ships at two layers, and the sidebar reflects that. **Use the right one
 - **Web Components** — the framework-agnostic `<kitn-*>` custom elements. **This is what to copy into a React, Vue, Angular, Svelte, or plain-HTML app.** Data goes on JS properties, interactions come back as events.
 - **Components · SolidJS** and **UI · SolidJS** — the **native SolidJS** components (feature components) and primitives (Button, Dropdown, HoverCard, …) that the web components are *built from*. Their snippets are SolidJS JSX, so **only copy these into a SolidJS app**.
 
-In other words: the `<kitn-chat>` web component is a thin facade over the SolidJS `ChatContainer`/`Message`/… components — same UI, different consumption model. When in doubt, reach for **Web Components**.
+In other words: the `<kc-chat>` web component is a thin facade over the SolidJS `ChatContainer`/`Message`/… components — same UI, different consumption model. When in doubt, reach for **Web Components**.
 
 ## Where to next
 

package/src/stories/docs/Theming.mdx

@@ -64,7 +64,7 @@ document.documentElement.classList.toggle('dark');
 
 ## Appearance settings
 
-`ChatConfig` (SolidJS) and matching properties on `<kitn-chat>` control non-color appearance:
+`ChatConfig` (SolidJS) and matching properties on `<kc-chat>` control non-color appearance:
 
 | Setting | Values | Purpose |
 | --- | --- | --- |
@@ -79,7 +79,7 @@ document.documentElement.classList.toggle('dark');
 ```
 
 ```html
-<kitn-chat prose-size="base" code-theme="github-dark-dimmed"></kitn-chat>
+<kc-chat prose-size="base" code-theme="github-dark-dimmed"></kc-chat>
 ```
 
 That's the whole theming surface — tokens for color, `ChatConfig` for sizing and code. Everything else is encapsulated.

package/src/stories/docs/element-controls.ts

@@ -4,6 +4,38 @@ type Prop = { name: string; type: string; default?: string; scalar: boolean };
 type ElementMeta = { tag: string; props: Prop[] };
 const all = meta as unknown as ElementMeta[];
 
+// A small, consistent pointer at the top of every Web Component's Docs tab,
+// directing readers to the dedicated API tab (which holds the full generated
+// spec). Keeps the Docs tab focused on examples while keeping the spec one click
+// away — and discoverable, since everyone reads the description first.
+const API_POINTER =
+  '> **Full API reference** — every property, event, default and token is on the **API** tab above.';
+
+/**
+ * Build a Storybook `docs.description` from an element's intro paragraphs, with
+ * the API-tab pointer prepended. The generated spec itself lives in the **API**
+ * tab (see `.storybook/api-tab.tsx`), not inline here.
+ * (`tag` is kept in the signature so callers don't churn if we re-inline later.)
+ */
+export function specDescription(_tag: string, paragraphs: string[]): { component: string } {
+  return { component: [API_POINTER, ...paragraphs].join('\n\n') };
+}
+
+// The Components/UI sibling of API_POINTER — same idea, component vocabulary
+// (props/callbacks/slots rather than properties/events/attributes).
+const COMPONENT_POINTER =
+  '> **Full API reference** — every prop, callback, slot and token is on the **API** tab above.';
+
+/**
+ * Build a Storybook `docs.description` for a SolidJS/UI component story, with the
+ * API-tab pointer prepended. The generated spec (props/callbacks/slots/tokens)
+ * lives on the **API** tab (see `.storybook/api-tab.tsx`), from
+ * `src/components/component-meta.json`.
+ */
+export function componentDescription(paragraphs: string[]): { component: string } {
+  return { component: [COMPONENT_POINTER, ...paragraphs].join('\n\n') };
+}
+
 const enumValues = (type: string): string[] | null => {
   // string-literal unions like "'light' | 'dark' | 'auto'"
   const parts = type.split('|').map((s) => s.trim());

package/src/stories/docs/theme-editor/theme-editor.tsx

@@ -110,6 +110,7 @@ export function ThemeEditor() {
         </div>
         <div class="flex items-center gap-2">
           <select
+            aria-label="Theme preset"
             class="bg-input border border-border rounded-md text-xs px-2 h-8"
             value={presetName()}
             onChange={(e) => loadPreset(e.currentTarget.value)}

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 />,