@nexub/mcp 0.0.0-stage → 1.8.0

package/dist/skill/references/components/collapsible.md

@@ -0,0 +1,71 @@
+# Collapsible
+
+Toggle visibility of content with smooth animation.
+
+- Package: `@nexub/react` · Category: Disclosure · Status: stable
+- Import: `import { Collapsible } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/collapsible
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Collapsible.Root open` | `boolean` |  | Controlled open state. |
+| `Collapsible.Root defaultOpen` | `boolean` | `false` | Whether the collapsible is open by default (uncontrolled). |
+| `Collapsible.Root onOpenChange` | `(open: boolean) => void` |  | Callback fired when the open state changes. |
+| `Collapsible.Root disabled` | `boolean` | `false` | Prevents the user from toggling the collapsible. |
+| `Collapsible.Trigger asChild` | `boolean` | `false` | Merges props onto the immediate child element (Radix Slot). |
+| `Collapsible.Content forceMount` | `boolean` | `false` | Keeps the content mounted in the DOM even when closed. |
+
+## Example: Default
+
+```tsx
+<Collapsible.Root>
+  <Collapsible.Trigger asChild>
+    <Button variant="outline">Toggle details</Button>
+  </Collapsible.Trigger>
+  <Collapsible.Content>
+    <div style={{ paddingTop: '12px', color: 'var(--color-text-secondary)' }}>
+      Hidden content revealed on toggle.
+    </div>
+  </Collapsible.Content>
+</Collapsible.Root>
+```
+
+## Example: Controlled
+
+```tsx
+function ControlledExample() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <Collapsible.Root open={open} onOpenChange={setOpen}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+        <span style={{ fontWeight: 500 }}>Advanced settings</span>
+        <Collapsible.Trigger asChild>
+          <IconButton
+            aria-label={open ? 'Collapse' : 'Expand'}
+            variant="ghost"
+            size="sm"
+          />
+        </Collapsible.Trigger>
+      </div>
+      <Collapsible.Content>
+        <div style={{ paddingTop: '12px', display: 'flex', flexDirection: 'column', gap: '12px' }}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <Switch id="notif" />
+            <Label htmlFor="notif">Enable notifications</Label>
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <Switch id="autosave" />
+            <Label htmlFor="autosave">Auto-save drafts</Label>
+          </div>
+          <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+            <Switch id="tooltips" />
+            <Label htmlFor="tooltips">Show tooltips</Label>
+          </div>
+        </div>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+}
+```

package/dist/skill/references/components/combobox.md

@@ -0,0 +1,40 @@
+# Combobox
+
+Command-palette style searchable dropdown built on cmdk.
+
+- Package: `@nexub/react` · Category: Form Controls · Status: stable
+- Import: `import { Combobox } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/combobox
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Combobox.Root` | `compound` |  | Root cmdk command container. |
+| `Combobox.Input` | `compound` |  | Search input that filters the list. |
+| `Combobox.List` | `compound` |  | Scrollable list container for groups and items. |
+| `Combobox.Group` | `compound` |  | Labeled group of items within the list. |
+| `Combobox.Item` | `compound` |  | Individual selectable option. |
+| `Combobox.Empty` | `compound` |  | Content shown when no items match the search query. |
+| `Combobox.Separator` | `compound` |  | Visual separator between groups or items. |
+
+## Example: Default
+
+```tsx
+<Combobox.Root>
+  <Combobox.Input placeholder="Search..." />
+  <Combobox.List>
+    <Combobox.Empty>No results found.</Combobox.Empty>
+    <Combobox.Group heading="Frameworks">
+      <Combobox.Item value="react">React</Combobox.Item>
+      <Combobox.Item value="vue">Vue</Combobox.Item>
+      <Combobox.Item value="svelte">Svelte</Combobox.Item>
+    </Combobox.Group>
+    <Combobox.Separator />
+    <Combobox.Group heading="Languages">
+      <Combobox.Item value="typescript">TypeScript</Combobox.Item>
+      <Combobox.Item value="rust">Rust</Combobox.Item>
+    </Combobox.Group>
+  </Combobox.List>
+</Combobox.Root>
+```

package/dist/skill/references/components/conversation.md

@@ -0,0 +1,100 @@
+# Conversation
+
+Chat layout: a scrolling message list that follows new content, with a sticky composer underneath.
+
+- Package: `@nexub/patterns` · Category: AI · Status: beta
+- Import: `import { Conversation } from '@nexub/patterns';`
+- Docs: https://nexub-ds-docs.pages.dev/patterns/conversation
+
+## When to use
+
+- A full chat or assistant view: messages above, composer below.
+
+## When not to use
+
+- A single question and answer: a PromptInput and a MessageBubble in normal flow are enough.
+- Comment threads that don’t follow new content: use ActivityFeed.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | The messages, usually MessageBubbles. |
+| `composer` | `ReactNode` |  | Sticky slot under the list, usually a PromptInput. |
+| `autoScroll` | `boolean` | `true` | Follow new content while the reader is at the bottom. Scrolling up stops following and shows "Jump to latest". |
+| `announce` | `boolean` | `false` | Make the list a polite `role="log"`. Only for whole-message updates: with token streaming it announces every chunk. |
+| `messages` | `Partial<ConversationMessages>` |  | Overrides for `jumpToLatest` and `conversation`. |
+
+## Example: Mini chat
+
+Send a message: it shows Thinking, then streams a cited reply. Stop or Escape ends the reply early.
+
+```tsx
+type Message = { id: number; from: 'user' | 'assistant'; text: string };
+
+const REPLY = 'Air-source heat pumps work in most homes and run at roughly the cost of gas.';
+const SOURCE = { title: 'Choosing a heat pump', url: 'https://example.com/guides/heat-pumps' };
+
+function Chat() {
+  const [messages, setMessages] = React.useState<Message[]>([]);
+  const [status, setStatus] = React.useState<'idle' | 'submitting' | 'streaming'>('idle');
+  const timer = React.useRef<ReturnType<typeof setTimeout>>();
+
+  function send(text: string) {
+    const id = Date.now();
+    setMessages((m) => [...m, { id, from: 'user', text }, { id: id + 1, from: 'assistant', text: '' }]);
+    setStatus('submitting');
+    timer.current = setTimeout(() => {
+      setStatus('streaming');
+      stream(id + 1, 0);
+    }, 800);
+  }
+
+  function stream(id: number, length: number) {
+    setMessages((m) => m.map((msg) => (msg.id === id ? { ...msg, text: REPLY.slice(0, length) } : msg)));
+    if (length >= REPLY.length) return setStatus('idle');
+    timer.current = setTimeout(() => stream(id, length + 4), 50);
+  }
+
+  function stop() {
+    clearTimeout(timer.current);
+    setStatus('idle');
+  }
+
+  const last = messages[messages.length - 1];
+
+  return (
+    <Conversation
+      style={{ height: 420 }}
+      composer={<PromptInput placeholder="Ask about heat pumps" status={status} onSubmit={send} onStop={stop} />}
+    >
+      {messages.map((msg) =>
+        msg.from === 'user' ? (
+          <MessageBubble key={msg.id} from="user">{msg.text}</MessageBubble>
+        ) : (
+          <MessageBubble key={msg.id} from="assistant">
+            {status === 'submitting' && msg === last ? (
+              <ThinkingIndicator />
+            ) : (
+              <>
+                <StreamingText as="span" text={msg.text} streaming={status === 'streaming' && msg === last} />
+                {msg.text === REPLY && <Citation index={1} source={SOURCE} />}
+              </>
+            )}
+          </MessageBubble>
+        ),
+      )}
+    </Conversation>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: region (default) or log (with `announce`)
+- `Tab`: The message list is focusable so keyboard users can scroll it.
+- Keep focus in the composer while a reply streams; don’t move it to the new message.
+- The list is named "Conversation". Leave `announce` off while streaming tokens and announce the finished reply once instead.
+- With reduced motion, "Jump to latest" scrolls instantly.
+
+Related: [message-bubble](message-bubble.md), [prompt-input](prompt-input.md), [streaming-text](streaming-text.md)

package/dist/skill/references/components/data-table.md

@@ -0,0 +1,70 @@
+# Data Table
+
+Feature-rich data table with sorting and row selection powered by TanStack Table.
+
+- Package: `@nexub/react` · Category: Data Display · Status: stable
+- Import: `import { DataTable } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/data-table
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` (required) | `DataTableColumn<TData>[]` |  | TanStack Table column definitions (`DataTableColumn` is exported from @nexub/react). Set `meta: { align: 'end' }` for numeric columns; headers, sort buttons and cells follow it. |
+| `caption` | `ReactNode` |  | Names the table for assistive tech (and its scroll region). Shown below the table; add `captionHidden` to keep it screen-reader only. |
+| `data` (required) | `TData[]` |  | Array of row data objects to render. |
+| `enableSorting` | `boolean` | `false` | Enables click-to-sort on column headers. |
+| `enableRowSelection` | `boolean` | `false` | Adds a checkbox column for row selection. |
+| `pagination.pageSize` | `number` | `10` | Number of rows per page when pagination is active. |
+| `pagination.pageIndex` | `number` | `0` | Zero-based index of the currently visible page. |
+| `onRowSelectionChange` | `(selectedRows: TData[]) => void` |  | Callback invoked when the row selection state changes. |
+| `loading` | `boolean` | `false` | Shows a skeleton loading state over the table body. |
+| `emptyState` | `React.ReactNode` |  | Custom content rendered when the data array is empty. |
+
+## Example: Default
+
+```tsx
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'role', header: 'Role' },
+  { accessorKey: 'status', header: 'Status' },
+  { accessorKey: 'joined', header: 'Joined' },
+];
+
+const data = [
+  { name: 'Alice Johnson', role: 'Admin', status: 'Active', joined: '2024-01-10' },
+  { name: 'Bob Martinez', role: 'Editor', status: 'Pending', joined: '2024-03-22' },
+  { name: 'Carol Smith', role: 'Viewer', status: 'Inactive', joined: '2024-06-05' },
+  { name: 'David Lee', role: 'Editor', status: 'Active', joined: '2024-09-17' },
+  { name: 'Eva Chen', role: 'Admin', status: 'Active', joined: '2025-01-03' },
+];
+
+<DataTable columns={columns} data={data} />
+```
+
+## Example: With sorting
+
+```tsx
+const columns = [
+  { accessorKey: 'name', header: 'Name', enableSorting: true },
+  { accessorKey: 'role', header: 'Role', enableSorting: true },
+  { accessorKey: 'status', header: 'Status', enableSorting: true },
+  { accessorKey: 'joined', header: 'Joined', enableSorting: true },
+];
+
+const data = [
+  { name: 'Alice Johnson', role: 'Admin', status: 'Active', joined: '2024-01-10' },
+  { name: 'Bob Martinez', role: 'Editor', status: 'Pending', joined: '2024-03-22' },
+  { name: 'Carol Smith', role: 'Viewer', status: 'Inactive', joined: '2024-06-05' },
+  { name: 'David Lee', role: 'Editor', status: 'Active', joined: '2024-09-17' },
+  { name: 'Eva Chen', role: 'Admin', status: 'Active', joined: '2025-01-03' },
+];
+
+<DataTable
+  columns={columns}
+  data={data}
+  enableSorting
+  enableRowSelection
+  pagination={{ pageSize: 5, pageIndex: 0 }}
+/>
+```

package/dist/skill/references/components/date-picker.md

@@ -0,0 +1,56 @@
+# Date Picker
+
+Calendar date picker with text input.
+
+- Package: `@nexub/react` · Category: Form & Input · Status: stable
+- Import: `import { DatePicker } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/date-picker
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Date \| undefined` |  | Controlled selected date value. |
+| `onChange` | `(date: Date \| undefined) => void` |  | Callback invoked when the selected date changes. |
+| `locale` | `Locale (date-fns)` |  | Month and weekday names, week start and the trigger format. Defaults to the NexubProvider `dateLocale`; the calendar also follows the provider `dir`, so arrows flip in RTL. |
+| `placeholder` | `string` | `'Pick a date'` | Placeholder text displayed in the input when no date is selected. |
+| `disabled` | `boolean` | `false` | Disables the date picker input and calendar. |
+| `minDate` | `Date` |  | Earliest selectable date. Dates before this are greyed out. |
+| `maxDate` | `Date` |  | Latest selectable date. Dates after this are greyed out. |
+| `format` | `string` | `'dd/MM/yyyy'` | Date format string for the text input display. |
+| `aria-label` | `string` |  | Field name for screen readers; the selected value is appended. |
+| `id` | `string` |  | Id for the trigger button, e.g. to pair with a <label htmlFor>. |
+| `error` | `string` |  | Error message displayed below the input. |
+
+## Example: Default
+
+```tsx
+<DatePicker placeholder="Select a date…" />
+```
+
+## Example: With value
+
+```tsx
+function ControlledDatePicker() {
+  const [date, setDate] = React.useState(new Date('2026-01-15'));
+  return (
+    <DatePicker
+      aria-label="Appointment date"
+      value={date}
+      onChange={setDate}
+      placeholder="Select a date…"
+    />
+  );
+}
+```
+
+## Example: With constraints
+
+```tsx
+<DatePicker
+  aria-label="Schedule for"
+  placeholder="Select a future date…"
+  minDate={new Date()}
+  maxDate={new Date(Date.now() + 90 * 24 * 60 * 60 * 1000)}
+/>
+```

package/dist/skill/references/components/date-range-picker.md

@@ -0,0 +1,48 @@
+# Date Range Picker
+
+Dual-calendar date range selector.
+
+- Package: `@nexub/react` · Category: Form & Input · Status: stable
+- Import: `import { DateRangePicker } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/date-range-picker
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `{ from: Date \| undefined; to: Date \| undefined }` |  | Controlled date range value. |
+| `onChange` | `(range: { from: Date \| undefined; to: Date \| undefined }) => void` |  | Callback invoked when the selected range changes. |
+| `locale` | `Locale (date-fns)` |  | Month and weekday names, week start and the trigger format. Defaults to the NexubProvider `dateLocale`; the calendar also follows the provider `dir`, so arrows flip in RTL. |
+| `placeholder` | `string` | `'Select date range'` | Placeholder text shown in the trigger input when no range is selected. |
+| `disabled` | `boolean` | `false` | Disables the trigger input and calendar popover. |
+| `minDate` | `Date` |  | Earliest selectable date. Dates before this are greyed out. |
+| `maxDate` | `Date` |  | Latest selectable date. Dates after this are greyed out. |
+| `numberOfMonths` | `number` | `2` | Number of months to display in the calendar popover. |
+| `aria-label` | `string` |  | Field name for screen readers; the selected value is appended. |
+| `id` | `string` |  | Id for the trigger button, e.g. to pair with a <label htmlFor>. |
+| `error` | `string` |  | Error message displayed below the input. |
+
+## Example: Default
+
+```tsx
+<DateRangePicker placeholder="Select date range…" />
+```
+
+## Example: Controlled
+
+```tsx
+function ControlledDateRangePicker() {
+  const [range, setRange] = React.useState({
+    from: new Date('2026-04-01'),
+    to: new Date('2026-04-14'),
+  });
+  return (
+    <DateRangePicker
+      aria-label="Booking period"
+      value={range}
+      onChange={setRange}
+      placeholder="Select date range…"
+    />
+  );
+}
+```

package/dist/skill/references/components/dialog.md

@@ -0,0 +1,57 @@
+# Dialog
+
+Modal dialog built on Radix UI. Fully accessible with focus trapping and ARIA roles.
+
+- Package: `@nexub/react` · Category: Overlays · Status: stable
+- Import: `import { Dialog } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/dialog
+
+## When to use
+
+- Confirming a destructive or irreversible action
+- Collecting a small form without leaving the current page
+- Displaying critical information that requires acknowledgement
+- Previewing content before taking an action
+
+## When not to use
+
+- Long multi-step flows — use a Drawer or a dedicated page instead
+- Quick contextual info — use a Tooltip or Popover
+- Non-blocking side panels — use Sheet or Drawer
+- Stacking multiple dialogs — always limit to one at a time
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` |  | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` |  | Callback when open state changes. |
+| `defaultOpen` | `boolean` | `false` | Uncontrolled initial open state. |
+| `surface` | `'solid' \| 'glass'` | `'solid'` | Glass material on Dialog.Content — see Foundations → Materials. |
+
+## Example: Default
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger asChild>
+    <Button>Open Dialog</Button>
+  </Dialog.Trigger>
+  <Dialog.Portal>
+    <Dialog.Overlay />
+    <Dialog.Content>
+      <Dialog.Header>
+        <Dialog.Title>Edit profile</Dialog.Title>
+        <Dialog.Description>
+          Make changes to your profile here.
+        </Dialog.Description>
+      </Dialog.Header>
+      <Dialog.Footer>
+        <Dialog.Close asChild>
+          <Button variant="outline">Cancel</Button>
+        </Dialog.Close>
+        <Button>Save changes</Button>
+      </Dialog.Footer>
+    </Dialog.Content>
+  </Dialog.Portal>
+</Dialog.Root>
+```

package/dist/skill/references/components/drawer.md

@@ -0,0 +1,79 @@
+# Drawer
+
+Slide-in panel from any edge of the screen.
+
+- Package: `@nexub/react` · Category: Overlays · Status: stable
+- Import: `import { Drawer } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/drawer
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Drawer.Root` | `compound` |  | Root provider that manages open/close state. |
+| `Drawer.Trigger` | `compound` |  | Element that opens the drawer. |
+| `Drawer.Portal` | `compound` |  | Portals the overlay and content into the document body. |
+| `Drawer.Overlay` | `compound` |  | Dimmed backdrop rendered behind the drawer. |
+| `Drawer.Content` | `compound` |  | The drawer panel. Accepts a side prop. |
+| `scrollLock` | `'style' \| 'class'` |  | On Drawer.Root. How page scroll is locked while open. `class` adds a class from @nexub/themes/base instead of injecting a <style> tag, so it works under a strict CSP (style-src 'self'). Default `style`. |
+| `side` | `'left' \| 'right' \| 'top' \| 'bottom'` |  | Edge of the screen from which the drawer slides in. |
+| `Drawer.Header` | `compound` |  | Header section of the drawer panel. |
+| `Drawer.Footer` | `compound` |  | Footer section of the drawer panel. |
+| `Drawer.Title` | `compound` |  | Accessible title for the drawer. |
+| `Drawer.Description` | `compound` |  | Supporting description text for the drawer. |
+| `Drawer.Close` | `compound` |  | Element that closes the drawer. |
+| `surface` | `'solid' \| 'glass'` | `'solid'` | Glass material on Drawer.Content — see Foundations → Materials. |
+
+## Example: Default
+
+```tsx
+<Drawer.Root>
+  <Drawer.Trigger asChild>
+    <Button variant="outline">Open drawer</Button>
+  </Drawer.Trigger>
+  <Drawer.Portal>
+    <Drawer.Overlay />
+    <Drawer.Content side="right">
+      <Drawer.Header>
+        <Drawer.Title>Edit profile</Drawer.Title>
+        <Drawer.Description>Make changes to your profile settings.</Drawer.Description>
+      </Drawer.Header>
+      <div style={{ padding: '16px', flex: 1 }}>
+        <Text size="body-sm" tone="secondary">Drawer body content goes here.</Text>
+      </div>
+      <Drawer.Footer>
+        <Drawer.Close asChild>
+          <Button variant="outline">Cancel</Button>
+        </Drawer.Close>
+        <Button variant="primary">Save changes</Button>
+      </Drawer.Footer>
+    </Drawer.Content>
+  </Drawer.Portal>
+</Drawer.Root>
+```
+
+## Example: Bottom sheet
+
+```tsx
+<Drawer.Root>
+  <Drawer.Trigger asChild>
+    <Button variant="outline">Open bottom sheet</Button>
+  </Drawer.Trigger>
+  <Drawer.Portal>
+    <Drawer.Overlay />
+    <Drawer.Content side="bottom">
+      <Drawer.Header>
+        <Drawer.Title>Share</Drawer.Title>
+      </Drawer.Header>
+      <div style={{ padding: '16px' }}>
+        <Text size="body-sm">Choose how you would like to share this item.</Text>
+      </div>
+      <Drawer.Footer>
+        <Drawer.Close asChild>
+          <Button variant="outline" fullWidth>Cancel</Button>
+        </Drawer.Close>
+      </Drawer.Footer>
+    </Drawer.Content>
+  </Drawer.Portal>
+</Drawer.Root>
+```

package/dist/skill/references/components/empty-state.md

@@ -0,0 +1,77 @@
+# Empty State
+
+Placeholder UI shown when a list or page has no content.
+
+- Package: `@nexub/react` · Category: Data Display · Status: stable
+- Import: `import { EmptyState } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/empty-state
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `EmptyState.Root layout` | `'centered' \| 'inline'` | `'centered'` | "centered" stacks content vertically in the middle of its container; "inline" aligns content to the start. |
+| `EmptyState.Illustration children` | `React.ReactNode` |  | Icon or SVG illustration to render above the title. |
+| `EmptyState.Title children` (required) | `React.ReactNode` |  | Primary heading text for the empty state. |
+| `EmptyState.Description children` | `React.ReactNode` |  | Supporting text providing more context or guidance. |
+| `EmptyState.Actions children` | `React.ReactNode` |  | One or more action buttons rendered below the description. |
+
+## Example: Default
+
+```tsx
+<EmptyState.Root>
+  <EmptyState.Illustration>
+    <svg
+      width="48"
+      height="48"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="var(--color-text-disabled)"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <circle cx="11" cy="11" r="8" />
+      <path d="m21 21-4.35-4.35" />
+    </svg>
+  </EmptyState.Illustration>
+  <EmptyState.Title>No results found</EmptyState.Title>
+  <EmptyState.Description>
+    Try adjusting your search or filters to find what you're looking for.
+  </EmptyState.Description>
+  <EmptyState.Actions>
+    <Button variant="primary">Clear filters</Button>
+    <Button variant="outline">Browse all</Button>
+  </EmptyState.Actions>
+</EmptyState.Root>
+```
+
+## Example: Custom illustration
+
+```tsx
+<EmptyState.Root>
+  <EmptyState.Illustration>
+    <svg
+      width="80"
+      height="80"
+      viewBox="0 0 80 80"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      aria-hidden="true"
+    >
+      <rect width="80" height="80" rx="40" fill="var(--color-bg-subtle)" />
+      <rect x="24" y="28" width="32" height="24" rx="4" stroke="var(--color-border-strong)" strokeWidth="2" />
+      <path d="M24 36h32" stroke="var(--color-border-strong)" strokeWidth="2" />
+      <circle cx="40" cy="48" r="4" fill="var(--color-text-disabled)" />
+    </svg>
+  </EmptyState.Illustration>
+  <EmptyState.Title>No documents yet</EmptyState.Title>
+  <EmptyState.Description>
+    Upload your first document to get started.
+  </EmptyState.Description>
+  <EmptyState.Actions>
+    <Button variant="primary">Upload document</Button>
+  </EmptyState.Actions>
+</EmptyState.Root>
+```

package/dist/skill/references/components/error-state.md

@@ -0,0 +1,37 @@
+# Error State
+
+Full-page or section error view with retry action.
+
+- Package: `@nexub/react` · Category: Data Display · Status: stable
+- Import: `import { ErrorState } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/error-state
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  | Primary error heading shown to the user. |
+| `description` | `string` |  | Supporting text with more detail about the error or recovery steps. |
+| `tone` | `'error' \| 'warning' \| 'info'` | `'error'` | Controls the icon and colour scheme of the error state. |
+| `onRetry` | `() => void` |  | When provided, renders a "Try again" button that calls this function on click. |
+| `actions` | `React.ReactNode` |  | Custom action elements rendered below the description. Takes priority over the default retry button. |
+
+## Example: Default
+
+```tsx
+<ErrorState
+  title="Something went wrong"
+  description="We could not load the data. Please try again."
+  onRetry={() => {}}
+/>
+```
+
+## Example: Warning
+
+```tsx
+<ErrorState
+  tone="warning"
+  title="Connection issue"
+  description="Check your network and try again."
+/>
+```