@kitnai/chat 0.7.0 → 0.8.1

package/src/elements/{kitn-chain-of-thought.stories.tsx → chain-of-thought.stories.tsx}

@@ -1,8 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 interface Step {
   label: string;
@@ -14,7 +13,7 @@ declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
+      'kc-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -25,19 +24,19 @@ const steps: Step[] = [
   { label: 'Build & verify' },
 ];
 
-/** Render `<kitn-chain-of-thought>` with the `steps` set as a JS property. */
+/** Render `<kc-chain-of-thought>` with the `steps` set as a JS property. */
 function CotElement(props: { steps: Step[] }) {
   let el: (HTMLElement & { steps?: Step[] }) | undefined;
   onMount(() => {
     if (el) el.steps = props.steps;
   });
   return (
-    <kitn-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
+    <kc-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chain-of-thought id="cot"></kitn-chain-of-thought>
+<kc-chain-of-thought id="cot"></kc-chain-of-thought>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -50,20 +49,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-chain-of-thought',
+  title: 'Web Components/kc-chain-of-thought',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-chain-of-thought'),
+  argTypes: argTypesFor('kc-chain-of-thought'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
-          '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
-          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
-          'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+      description: specDescription('kc-chain-of-thought', [
+        '`<kc-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
+        '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
+        "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
+        'See the **Code** tab for HTML usage.',
+      ]),
     },
   },
 } satisfies Meta;
@@ -71,12 +68,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-chain-of-thought" />,
-  parameters: { layout: 'padded' },
-};
-
 /** A three-step reasoning trace; the last step has no detail. */
 export const Default: Story = {
   render: () => <CotElement steps={steps} />,

package/src/elements/chain-of-thought.tsx

@@ -1,5 +1,5 @@
 import { For, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import {
   ChainOfThought,
   ChainOfThoughtStep,
@@ -22,10 +22,10 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-chain-of-thought>` — step-by-step reasoning with connectors and
+ * `<kc-chain-of-thought>` — step-by-step reasoning with connectors and
  * per-step collapsible detail. Data via the `steps` property.
  */
-defineKitnElement<Props>('kitn-chain-of-thought', {
+defineWebComponent<Props>('kc-chain-of-thought', {
   steps: [],
 }, (props) => (
   <ChainOfThought>

package/src/elements/{kitn-chat-scope-picker.stories.tsx → chat-scope-picker.stories.tsx}

@@ -1,22 +1,21 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
         'current-label'?: string;
       };
     }
   }
 }
 
-/** Render `<kitn-chat-scope-picker>` with author/tag options set as properties. */
+/** Render `<kc-scope-picker>` with author/tag options set as properties. */
 function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
   let el: (HTMLElement & { availableAuthors?: string[]; availableTags?: string[] }) | undefined;
   onMount(() => {
@@ -29,12 +28,12 @@ function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
     });
   });
   return (
-    <kitn-chat-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+    <kc-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat-scope-picker id="scope"></kitn-chat-scope-picker>
+<kc-scope-picker id="scope"></kc-scope-picker>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -47,20 +46,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-chat-scope-picker',
+  title: 'Web Components/kc-scope-picker',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-chat-scope-picker'),
+  argTypes: argTypesFor('kc-scope-picker'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
+      description: specDescription('kc-scope-picker', [
+          '`<kc-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
           '**When to use:** letting users narrow a conversation/search to a subset of content. In SolidJS, use the `ChatScopePicker` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `availableAuthors` / `availableTags` **properties** (and optionally `current-label`), and listen for the `scopechange` **CustomEvent** (`undefined` filters = \"All Content\").",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -68,12 +65,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-chat-scope-picker" />,
-  parameters: { layout: 'padded' },
-};
-
 /** Authors and tags available as scope filters. */
 export const Default: Story = {
   render: () => <ScopePickerElement authors={['Rob', 'Alex']} tags={['design', 'api']} />,

package/src/elements/chat-scope-picker.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatScopePicker } from '../components/chat-scope-picker';
 import type { SearchFilters } from '../types';
 
@@ -11,18 +11,18 @@ interface Props extends Record<string, unknown> {
   currentLabel?: string;
 }
 
-/** Events fired by `<kitn-chat-scope-picker>`. */
+/** Events fired by `<kc-scope-picker>`. */
 interface Events {
   /** A scope was chosen (`undefined` filters = "All Content"). */
   scopechange: { filters: SearchFilters | undefined };
 }
 
 /**
- * `<kitn-chat-scope-picker>` — a dropdown to scope a chat by author or tag.
+ * `<kc-scope-picker>` — a dropdown to scope a chat by author or tag.
  * Options via `available-authors`/`available-tags` properties; emits
  * `scopechange`.
  */
-defineKitnElement<Props, Events>('kitn-chat-scope-picker', {
+defineWebComponent<Props, Events>('kc-scope-picker', {
   availableAuthors: [],
   availableTags: [],
   currentLabel: 'All Content',

package/src/elements/{kitn-chat-workspace.stories.tsx → chat-workspace.stories.tsx}

@@ -1,17 +1,16 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
-import './register'; // side effect: registers all kitn custom elements including <kitn-chat-workspace>
+import './register'; // side effect: registers all kitn custom elements including <kc-workspace>
 import type { ConversationGroup, ConversationSummary, ModelOption } from '../types';
 import type { ChatMessage } from './chat-types';
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat-workspace': JSX.HTMLAttributes<HTMLElement>;
+      'kc-workspace': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -52,7 +51,7 @@ const sampleMessages: ChatMessage[] = [
     id: 'm2',
     role: 'assistant',
     content:
-      'Use `<kitn-chat-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `conversationselect` + `submit`.',
+      'Use `<kc-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `conversationselect` + `submit`.',
     actions: ['copy', 'like'],
   },
 ];
@@ -82,7 +81,7 @@ type WorkspaceEl = HTMLElement & {
   value?: string;
 };
 
-/** Live demo of the actual `<kitn-chat-workspace>` custom element (Shadow DOM and all). */
+/** Live demo of the actual `<kc-workspace>` custom element (Shadow DOM and all). */
 function WorkspaceElement(props: { args?: Record<string, unknown> }) {
   let el: WorkspaceEl | undefined;
   onMount(() => {
@@ -114,7 +113,7 @@ function WorkspaceElement(props: { args?: Record<string, unknown> }) {
   });
   return (
     <div style={{ height: '720px', width: '100%' }}>
-      <kitn-chat-workspace
+      <kc-workspace
         ref={(e) => (el = e as WorkspaceEl)}
         style={{ display: 'block', height: '100%' }}
       />
@@ -123,7 +122,7 @@ function WorkspaceElement(props: { args?: Record<string, unknown> }) {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat-workspace id="workspace" style="display:block; height:100vh;"></kitn-chat-workspace>
+<kc-workspace id="workspace" style="display:block; height:100vh;"></kc-workspace>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -138,7 +137,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
   ];
   workspace.messages = [
     { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
-    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+    { id: 'm2', role: 'assistant', content: 'Use <kc-workspace> — set conversations, messages, and models as properties.' },
   ];
   workspace.models = [
     { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
@@ -171,7 +170,7 @@ function Workspace() {
   ];
   const messages: ChatMessage[] = [
     { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
-    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+    { id: 'm2', role: 'assistant', content: 'Use <kc-workspace> — set conversations, messages, and models as properties.' },
   ];
   onMount(() => {
     el.conversations = conversations;
@@ -182,7 +181,7 @@ function Workspace() {
     el.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
   });
   return (
-    <kitn-chat-workspace
+    <kc-workspace
       ref={el}
       style={{ display: 'block', height: '100vh' }}
     />
@@ -190,21 +189,19 @@ function Workspace() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-chat-workspace',
+  title: 'Web Components/kc-workspace',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-chat-workspace'),
+  argTypes: argTypesFor('kc-workspace'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat-workspace>` is the full chat shell as a single **web component** — a resizable split layout with a collapsible conversation list on the left and a full message thread on the right, all isolated in **Shadow DOM**. SolidJS is bundled in, so the host needs nothing.',
+      description: specDescription('kc-workspace', [
+          '`<kc-workspace>` is the full chat shell as a single **web component** — a resizable split layout with a collapsible conversation list on the left and a full message thread on the right, all isolated in **Shadow DOM**. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** dropping an entire chat application shell into a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts and a ready-made list+chat layout. If you *are* in SolidJS and want fine-grained control, compose the `ConversationList` and `ChatThread` primitives directly.',
           '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.conversations = [...]`, `el.messages = [...]`, `el.models = [...]`), and listen for **CustomEvents** (`conversationselect`, `submit`, `sidebartoggle`, `newchat`) directly on the element.',
           '**Placement:** as a full-page surface or large panel. Give it an explicit height (e.g. `height: 100vh`). The sidebar is drag-resizable and can be collapsed via the toggle button in its header.',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -238,8 +235,3 @@ export const InSolidJS: Story = {
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
 
-/** Full generated API reference — properties, events, tokens, and the SolidJS components this element is composed from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-chat-workspace" />,
-  parameters: { layout: 'padded' },
-};

package/src/elements/chat-workspace.tsx

@@ -1,5 +1,5 @@
 import { createSignal, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatThread, type ChatThreadContextUsage } from '../components/chat-thread';
 import { ConversationList } from '../components/conversation-list';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
@@ -73,7 +73,7 @@ interface Events {
   suggestionclick: { value: string };
 }
 
-defineKitnElement<Props, Events>('kitn-chat-workspace', {
+defineWebComponent<Props, Events>('kc-workspace', {
   groups: [], conversations: [], activeId: undefined, messages: [],
   value: undefined, placeholder: 'Send a message...', loading: false,
   suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',

package/src/elements/{kitn-chat.stories.tsx → chat.stories.tsx}

@@ -1,16 +1,15 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
-import './register'; // side effect: registers <kitn-chat>, <kitn-conversation-list>, <kitn-prompt-input>
+import './register'; // side effect: registers <kc-chat>, <kc-conversations>, <kc-prompt-input>
 import type { ChatMessage } from './chat-types';
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat': JSX.HTMLAttributes<HTMLElement>;
+      'kc-chat': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -43,7 +42,7 @@ type ChatEl = HTMLElement & {
   slashCompact?: boolean;
 };
 
-/** Live demo of the actual `<kitn-chat>` custom element (Shadow DOM and all). */
+/** Live demo of the actual `<kc-chat>` custom element (Shadow DOM and all). */
 function ChatElement(props: { args?: Record<string, unknown> }) {
   let el: ChatEl | undefined;
   onMount(() => {
@@ -64,11 +63,11 @@ function ChatElement(props: { args?: Record<string, unknown> }) {
       }
     }
   });
-  return <kitn-chat ref={(e) => (el = e as ChatEl)} style={{ display: 'block', height: '560px' }} />;
+  return <kc-chat ref={(e) => (el = e as ChatEl)} style={{ display: 'block', height: '560px' }} />;
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat id="chat" style="display:block; height:100vh;"></kitn-chat>
+<kc-chat id="chat" style="display:block; height:100vh;"></kc-chat>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -95,7 +94,7 @@ function Chat() {
   ];
   onMount(() => { el.messages = messages; });
   return (
-    <kitn-chat
+    <kc-chat
       ref={el}
       style={{ display: 'block', height: '100vh' }}
       on:submit={(e) => console.log('user sent:', e.detail.value)}
@@ -104,21 +103,19 @@ function Chat() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-chat',
+  title: 'Web Components/kc-chat',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-chat'),
+  argTypes: argTypesFor('kc-chat'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat>` is the framework-agnostic **web component** version of the chat UI — a complete message thread plus prompt input, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
+      description: specDescription('kc-chat', [
+          '`<kc-chat>` is the framework-agnostic **web component** version of the chat UI — a complete message thread plus prompt input, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** dropping a full chat into a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts. If you *are* in SolidJS and want fine-grained control, compose the primitives (`ChatContainer`, `Message`, `PromptInput`) instead.',
           '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.messages = [...]`), and listen for **CustomEvents** (`submit`, `messageaction`, `valuechange`) directly on the element.',
           '**Placement:** as a top-level panel or full-page surface. Give it an explicit height (e.g. `height: 100vh`).',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -151,8 +148,3 @@ export const InSolidJS: Story = {
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
 
-/** Full generated API reference — properties, events, tokens, and the SolidJS components this element is composed from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-chat" />,
-  parameters: { layout: 'padded' },
-};

package/src/elements/chat.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage } from '../components/chat-thread';
 import type { AttachmentData } from '../components/attachments';
 import type { SlashCommandItem } from '../components/slash-command';
@@ -29,7 +29,7 @@ interface Events {
   voice: Record<string, never>;
 }
 
-defineKitnElement<Props, Events>('kitn-chat', {
+defineWebComponent<Props, Events>('kc-chat', {
   messages: [], value: undefined, placeholder: 'Send a message...', loading: false,
   suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,

package/src/elements/{kitn-checkpoint.stories.tsx → checkpoint.stories.tsx}

@@ -1,20 +1,19 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
-import { ElementSpec } from '../stories/docs/element-spec';
-import { argTypesFor } from '../stories/docs/element-controls';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-checkpoint': JSX.HTMLAttributes<HTMLElement>;
+      'kc-checkpoint': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
 
-/** Render the actual `<kitn-checkpoint>` custom element configured by attributes. */
+/** Render the actual `<kc-checkpoint>` custom element configured by attributes. */
 function CheckpointElement(props: { label?: string; tooltip?: string; variant?: string; size?: string }) {
   let el: HTMLElement | undefined;
   onMount(() => {
@@ -25,35 +24,33 @@ function CheckpointElement(props: { label?: string; tooltip?: string; variant?:
     if (props.size) el.setAttribute('size', props.size);
     el.addEventListener('select', () => console.log('checkpoint selected'));
   });
-  return <kitn-checkpoint ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
+  return <kc-checkpoint ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '16px' }} />;
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-checkpoint label="Restore" tooltip="Restore this checkpoint" variant="outline" size="sm"></kitn-checkpoint>
+<kc-checkpoint label="Restore" tooltip="Restore this checkpoint" variant="outline" size="sm"></kc-checkpoint>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
 
-  const cp = document.querySelector('kitn-checkpoint');
+  const cp = document.querySelector('kc-checkpoint');
   // events are CustomEvents on the element (they do not bubble)
   cp.addEventListener('select', () => console.log('restore checkpoint'));
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-checkpoint',
+  title: 'Web Components/kc-checkpoint',
   tags: ['autodocs'],
-  argTypes: argTypesFor('kitn-checkpoint'),
+  argTypes: argTypesFor('kc-checkpoint'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-checkpoint>` is the framework-agnostic **web component** for a bookmark/checkpoint button (with an optional tooltip and label), isolated in **Shadow DOM**.',
+      description: specDescription('kc-checkpoint', [
+          '`<kc-checkpoint>` is the framework-agnostic **web component** for a bookmark/checkpoint button (with an optional tooltip and label), isolated in **Shadow DOM**.',
           '**When to use:** marking a restore point in a conversation in a non-Solid app. In SolidJS, compose the `Checkpoint` primitives.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set `label`, `tooltip`, `variant` (`ghost` | `default` | `outline`), and `size` via attributes, and listen for the `select` **CustomEvent** on click.",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -61,12 +58,6 @@ const meta = {
 export default meta;
 type Story = StoryObj;
 
-/** Full generated API reference — properties, events, tokens, and composed-from. */
-export const API: Story = {
-  render: () => <ElementSpec tag="kitn-checkpoint" />,
-  parameters: { layout: 'padded' },
-};
-
 /** A labeled checkpoint button. (Add a `tooltip` attribute for a hover hint — see the Code tab.) */
 export const Labeled: Story = {
   render: () => <CheckpointElement label="Restore" variant="outline" />,

package/src/elements/checkpoint.tsx

@@ -1,5 +1,5 @@
 import { Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { Checkpoint, CheckpointIcon, CheckpointTrigger } from '../components/checkpoint';
 
 interface Props extends Record<string, unknown> {
@@ -13,17 +13,17 @@ interface Props extends Record<string, unknown> {
   size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
 }
 
-/** Events fired by `<kitn-checkpoint>`. */
+/** Events fired by `<kc-checkpoint>`. */
 interface Events {
   /** The checkpoint was clicked. */
   select: void;
 }
 
 /**
- * `<kitn-checkpoint>` — a bookmark/checkpoint button (optional tooltip + label).
+ * `<kc-checkpoint>` — a bookmark/checkpoint button (optional tooltip + label).
  * Emits `select`.
  */
-defineKitnElement<Props, Events>('kitn-checkpoint', {
+defineWebComponent<Props, Events>('kc-checkpoint', {
   label: undefined,
   tooltip: undefined,
   variant: 'ghost',
@@ -32,6 +32,10 @@ defineKitnElement<Props, Events>('kitn-checkpoint', {
   <Checkpoint>
     <CheckpointTrigger
       tooltip={props.tooltip}
+      // Icon-only (no visible label) needs an accessible name: prefer the
+      // tooltip text, else a sensible default. With a visible label, the text
+      // is the name — leave aria-label unset so it isn't duplicated.
+      aria-label={props.label ? undefined : (props.tooltip ?? 'Checkpoint')}
       variant={props.variant}
       size={props.size}
       onClick={() => dispatch('select')}