@nexub/mcp 0.0.0-stage → 1.7.0

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @nexub/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP server for the [Nexub Design System](https://nexub-ds-docs.pages.dev). It gives your AI coding tool the components, patterns, tokens and design rules of the release you install, so it builds UI with Nexub instead of generic Tailwind.
+
+## Setup
+
+Claude Code:
+
+```bash
+claude mcp add nexub-ds -- npx -y @nexub/mcp
+```
+
+Cursor, Windsurf, VS Code or any client that takes an `mcpServers` config:
+
+```json
+{
+  "mcpServers": {
+    "nexub-ds": { "command": "npx", "args": ["-y", "@nexub/mcp"] }
+  }
+}
+```
+
+Using Claude Code? The `nexub-ds` plugin ships the same content as a skill:
+
+```bash
+claude plugin marketplace add Nexub-AI/nexub-ds
+claude plugin install nexub-ds@nexub
+```
+
+## Tools
+
+| Tool | Returns |
+| --- | --- |
+| `get_guidelines` | Setup, how to build a screen, Calm Depth principles, Liquid Glass and copy rules, review checklist |
+| `list_components` | Every component and pattern, optionally filtered (`query: "table"`) |
+| `get_component` | Props, import, examples, when to use and accessibility for one component (`name: "DatePicker"`) |
+| `get_tokens` | Color roles, typography, spacing, shape, elevation, motion, with Tailwind utilities (`section: "Motion"`) |
+
+## Staying current
+
+The server reports the reference of the version it was published with, and it is versioned with `@nexub/react`. `npx -y @nexub/mcp` always fetches the latest release. Pin `@nexub/mcp@<version>` to match an older install.

package/dist/skill/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: nexub-ds
+description: Build SaaS UI with the Nexub Design System (@nexub/react, @nexub/patterns, @nexub/tokens, @nexub/themes, @nexub/icons). Use when building or restyling any React screen, page, dashboard, form, settings page, auth flow, pricing page or component in a project that uses Nexub DS, or when the user asks for Nexub, Calm Depth or Liquid Glass UI.
+license: MIT
+---
+
+# Nexub Design System
+
+Nexub DS is a token-driven React design system for SaaS products. The visual language is **Calm Depth**: tonal surfaces, one accent per view, spring motion, honest numbers. **Liquid Glass** is an optional material for the floating control layer.
+
+Reference files (read only what the task needs):
+
+- [references/components.md](references/components.md): every component and pattern, grouped by category. Start here.
+- `references/components/<slug>.md`: props, examples, when to use and accessibility for one component. Read it before using a component you have not used yet in this session.
+- [references/tokens.md](references/tokens.md): color roles, type roles, spacing, shape, elevation, motion, z-index.
+
+## 1. Check the setup first
+
+Look for `@nexub/react` in `package.json`. If it is missing, set it up:
+
+```bash
+npm install @nexub/react @nexub/patterns @nexub/themes @nexub/tokens @nexub/icons
+```
+
+```ts
+// app entry or global CSS, once
+import '@nexub/themes/base';   // resets + token CSS variables
+import '@nexub/themes/light';
+import '@nexub/themes/glass';  // only if you use Liquid Glass
+```
+
+```ts
+// tailwind.config.ts (Tailwind v3)
+import nexub from '@nexub/tokens/tailwind';
+export default {
+  presets: [nexub],
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/@nexub/react/dist/**/*.js',
+    './node_modules/@nexub/patterns/dist/**/*.js',
+  ],
+};
+```
+
+Wrap the app in `<ThemeProvider defaultTheme="system" storageKey="app-theme">` from `@nexub/react`. In server-rendered apps (Next.js), put `<ThemeScript storageKey="app-theme" />` in `<head>` and add `suppressHydrationWarning` to `<html>`. Product brands: set `data-product="leap" | "bookub" | "payub" | "founderub"` on the root. This remaps the `tertiary` role.
+
+## 2. How to build a screen
+
+1. **Start from a pattern.** Check the Patterns sections of `references/components.md` before you compose anything by hand.
+2. **Then use components.** Use `@nexub/react` for every control, overlay, layout primitive and piece of typography. Never hand-roll a button, input, dialog, menu or table that the library already has.
+3. **Then use tokens, only for the glue.** Use Tailwind utilities from the preset (`bg-surface-container-low`, `text-on-surface-variant`, `p-4`, `gap-6`, `rounded-shape-container`, `text-title-md`) or `var(--…)`.
+4. **Never hardcode design values.** That means no hex or rgb colors, no Tailwind palette colors (`bg-blue-500`, `text-gray-600`), no arbitrary px values (`p-[13px]`), no ad-hoc shadows or gradients.
+
+Starting points for typical SaaS screens:
+
+| Screen | Build with |
+| --- | --- |
+| App frame | `AppShell` (`AppShell.Root/Header/Body/Sidebar/Main`) + `Sidebar` or `NavigationRail` + `AppHeader` or `TopNav` |
+| Dashboard | `PageHeader` + a `Grid` of `StatCard` + `DataTable` or `Table` + `ActivityFeed` |
+| List / detail | `ListDetail` + `FilterBar` + `EmptyState` |
+| Settings | `SettingsLayout` / `SettingsRow` + `SettingsSection` + `FormField` |
+| Sign in / sign up | `AuthCard` + `FormField` + `PasswordInput` |
+| Pricing / billing | `PlanCard` + `SegmentedControl` (monthly / yearly) + `Amount` |
+| Onboarding | `StepIndicator` + `CheckList` |
+| Search / commands | `CommandPalette` + `KeyboardShortcut` |
+| Empty, loading, error | `EmptyState`, `Skeleton`, `ErrorState`, `Toast` |
+
+Money: use `Amount` and `MoneyInput`. They use tabular figures, the currency's own minor unit and a true minus sign. Icons: import from `@nexub/icons`, not `lucide-react` directly.
+
+## 3. Calm Depth principles
+
+1. **Content leads, chrome recedes.** Navigation is quieter than content. Remove a divider before you add one; let spacing and tone separate regions. Do: a tonal sidebar with no border, where the active item is a soft pill. Don't: a saturated brand-blue sidebar item, or a hard line around every region.
+2. **Hierarchy through tone and layout, not decoration.** Surfaces step `surface` → `surface-container-*` → `surface-elevated`. Shadows are only for things that float. Product UI has no gradients, no colored icon tiles and no gradient eyebrow chips.
+3. **One accent, spent deliberately.** Each view gets one filled (primary) button. Everything else is `tonal`, `outlined` or `text`. Never put two filled buttons side by side.
+4. **Physical, interruptible motion.** Use the spring tokens (`ease-spatial-default duration-spatial-default`), not raw durations. Exits are faster than entrances. Honor `prefers-reduced-motion`.
+5. **Honest numbers and states.** Use tabular figures in data. Hover, pressed, selected and disabled are explicit component states. Never fake a state with opacity.
+6. **Accessible by construction.** Every role pair meets WCAG 2.2 AA in light, dark and high contrast, as long as you pair a role with its `on-` role. Keep visible focus, labelled controls (`FormField` + `Label`) and keyboard support. Use `VisuallyHidden` for icon-only labels.
+
+## 4. Liquid Glass rules
+
+- Glass is for the floating control layer only: top bars, floating toolbars, popovers, menus, sheets, dialogs. Card glass is only for surfaces over imagery or media.
+- Turn it on through props: `<TopNav.Root surface="glass" scrollEdge="soft">`, `<Dialog.Content surface="glass">`, `<Button variant="glass">`.
+- Never put glass on glass. Show at most three glass layers at a time. Tint only the one primary action (`data-glass-tint="primary"`).
+- Never put white text on glass over an unknown background.
+
+## 5. UI copy
+
+Copy is clear, direct, human and confident. Use sentence case, active voice, contractions and specific verbs ("Save changes", not "Submit"). Errors say what happened and what to do: "Your session expired. Sign in again." No "Oops", no emoji in errors, no "Please be advised".
+
+## 6. Before you finish
+
+- [ ] Every control comes from `@nexub/react` or `@nexub/patterns`. No deprecated component (see the index).
+- [ ] There are no hex or rgb colors, Tailwind palette colors, arbitrary px values or custom shadows. Everything is a token utility or `var(--…)`.
+- [ ] Every background role is paired with its `on-` role. Secondary text uses `on-surface-variant` or `on-surface-muted`.
+- [ ] Each view has at most one filled button.
+- [ ] The screen works in light and dark (`data-theme`) and at `data-contrast="high"`.
+- [ ] Every input has a label. Icon-only buttons have an `aria-label`. Keyboard paths work.

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

@@ -0,0 +1,77 @@
+# Accordion
+
+Vertically stacked list of collapsible sections.
+
+- Package: `@nexub/react` · Category: Disclosure · Status: stable
+- Import: `import { Accordion } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/accordion
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Accordion.Root type` | `'single' \| 'multiple'` | `'single'` | Whether one or multiple items can be open at the same time. |
+| `Accordion.Root collapsible` | `boolean` | `false` | When type is "single", allows the open item to be collapsed by clicking it again. |
+| `Accordion.Root defaultValue` | `string \| string[]` |  | The item(s) open by default (uncontrolled). |
+| `Accordion.Root value` | `string \| string[]` |  | Controlled open item(s). |
+| `Accordion.Root onValueChange` | `(value: string \| string[]) => void` |  | Callback fired when the open state changes. |
+| `Accordion.Root disabled` | `boolean` | `false` | Disables all items in the accordion. |
+| `Accordion.Item value` (required) | `string` |  | Unique identifier for the item. |
+| `Accordion.Item disabled` | `boolean` | `false` | Disables this specific item. |
+| `Accordion.Trigger asChild` | `boolean` | `false` | Merges props onto the immediate child element. |
+| `Accordion.Content forceMount` | `boolean` | `false` | Keeps content in the DOM even when collapsed. |
+
+## Example: Default
+
+```tsx
+<Accordion.Root type="single" collapsible defaultValue="item-1">
+  <Accordion.Item value="item-1">
+    <Accordion.Trigger>What is Nexub DS?</Accordion.Trigger>
+    <Accordion.Content>
+      Nexub DS is a design system providing accessible, themeable React components
+      built on Radix UI primitives.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-2">
+    <Accordion.Trigger>Is it accessible?</Accordion.Trigger>
+    <Accordion.Content>
+      Yes. All components follow WAI-ARIA patterns and are keyboard-navigable
+      out of the box.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-3">
+    <Accordion.Trigger>Can I customise the styles?</Accordion.Trigger>
+    <Accordion.Content>
+      Absolutely. Components expose design tokens via CSS custom properties,
+      and every element accepts a className prop.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion.Root>
+```
+
+## Example: Multiple
+
+```tsx
+<Accordion.Root type="multiple" defaultValue={['item-1', 'item-2']}>
+  <Accordion.Item value="item-1">
+    <Accordion.Trigger>First section</Accordion.Trigger>
+    <Accordion.Content>
+      This section is open by default. Multiple items can be expanded
+      simultaneously when type is set to "multiple".
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-2">
+    <Accordion.Trigger>Second section</Accordion.Trigger>
+    <Accordion.Content>
+      Also open by default. Click any trigger to collapse individual sections
+      independently.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="item-3">
+    <Accordion.Trigger>Third section</Accordion.Trigger>
+    <Accordion.Content>
+      Closed by default. Expanding this does not close the others.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion.Root>
+```

package/dist/skill/references/components/activity-feed.md

@@ -0,0 +1,33 @@
+# ActivityFeed
+
+Chronological list of activity events with avatar, description, and timestamp.
+
+- Package: `@nexub/patterns` · Category: Data · Status: stable
+- Import: `import { ActivityFeed } from '@nexub/patterns';`
+- Docs: https://nexub-ds-docs.pages.dev/patterns/activity-feed
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `React.ReactNode` |  | Activity event title. |
+| `description` | `React.ReactNode` |  | Supporting description. |
+| `timestamp` | `string` |  | Time string (e.g. "2 hours ago"). |
+| `avatar` | `React.ReactNode` |  | Avatar element for the actor. |
+
+## Example: Default
+
+```tsx
+<ActivityFeed.Root>
+  <ActivityFeed.Item
+    title="Alex created a new project"
+    description="Project 'Nexub DS v2' was created"
+    timestamp="2 hours ago"
+  />
+  <ActivityFeed.Item
+    title="Sam invited 3 members"
+    description="Jordan, Riley, and Taylor joined"
+    timestamp="Yesterday"
+  />
+</ActivityFeed.Root>
+```

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

@@ -0,0 +1,48 @@
+# Alert Dialog
+
+Confirmation dialog that requires an explicit user action before proceeding.
+
+- Package: `@nexub/react` · Category: Overlays · Status: stable
+- Import: `import { AlertDialog } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/alert-dialog
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `AlertDialog.Root` | `compound` |  | Root provider component that manages open state. |
+| `AlertDialog.Trigger` | `compound` |  | Element that opens the dialog on interaction. |
+| `AlertDialog.Portal` | `compound` |  | Portals the overlay and content into the document body. |
+| `AlertDialog.Overlay` | `compound` |  | Dimmed backdrop rendered behind the content. |
+| `AlertDialog.Content` | `compound` |  | The dialog panel containing title, description, and actions. |
+| `AlertDialog.Title` | `compound` |  | Accessible title announced to screen readers. |
+| `AlertDialog.Description` | `compound` |  | Supporting description text for the dialog. |
+| `AlertDialog.Action` | `compound` |  | Confirms the destructive or affirmative action and closes the dialog. |
+| `AlertDialog.Cancel` | `compound` |  | Cancels the action and closes the dialog. |
+
+## Example: Default
+
+```tsx
+<AlertDialog.Root>
+  <AlertDialog.Trigger asChild>
+    <Button variant="destructive">Delete account</Button>
+  </AlertDialog.Trigger>
+  <AlertDialog.Portal>
+    <AlertDialog.Overlay />
+    <AlertDialog.Content>
+      <AlertDialog.Title>Are you absolutely sure?</AlertDialog.Title>
+      <AlertDialog.Description>
+        This action cannot be undone. This will permanently delete your account and remove all associated data.
+      </AlertDialog.Description>
+      <div style={{ display: 'flex', justifyContent: 'flex-end', gap: '8px', marginTop: '16px' }}>
+        <AlertDialog.Cancel asChild>
+          <Button variant="outline">Cancel</Button>
+        </AlertDialog.Cancel>
+        <AlertDialog.Action asChild>
+          <Button variant="destructive">Confirm delete</Button>
+        </AlertDialog.Action>
+      </div>
+    </AlertDialog.Content>
+  </AlertDialog.Portal>
+</AlertDialog.Root>
+```

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

@@ -0,0 +1,54 @@
+# Alert
+
+Inline contextual message with optional title, icon, and dismiss action.
+
+- Package: `@nexub/react` · Category: Feedback · Status: stable
+- Import: `import { Alert } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/alert
+
+## When to use
+
+- Communicating system status, errors, or success after an action
+- Showing inline validation feedback inside a form
+- Warning the user about a potentially risky operation
+- Providing contextual information relevant to the current page
+
+## When not to use
+
+- Transient messages — use Toast for ephemeral notifications
+- Blocking the user for a required decision — use AlertDialog
+- Marketing or promotional messaging
+- Replacing empty states — use EmptyState instead
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` | `'neutral'` | Semantic colour tone of the alert. |
+| `title` | `string` |  | Bold title rendered at the top of the alert. |
+| `icon` | `ReactNode` |  | Custom icon rendered to the left of the content. |
+| `action` | `ReactNode` |  | Action element (e.g. a button) rendered beside the content. |
+| `onClose` | `() => void` |  | When provided, renders a close button that calls this handler. |
+
+## Example: Default
+
+```tsx
+<Alert tone="info" title="Heads up">Your trial expires in 3 days.</Alert>
+```
+
+## Example: Tones
+
+```tsx
+<div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+  <Alert tone="info" title="Information">This is an informational message.</Alert>
+  <Alert tone="success" title="Success">Your changes have been saved.</Alert>
+  <Alert tone="warning" title="Warning">Please review before proceeding.</Alert>
+  <Alert tone="danger" title="Error">Something went wrong. Please try again.</Alert>
+</div>
+```
+
+## Example: Dismissible
+
+```tsx
+<Alert tone="success" title="Saved" onClose={() => {}}>Your changes have been saved.</Alert>
+```

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

@@ -0,0 +1,34 @@
+# Amount
+
+Honest money: Intl formatting, tabular numerals, the currency’s minor unit and a true minus sign.
+
+- Package: `@nexub/react` · Category: Data Display · Status: beta
+- Import: `import { Amount } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/amount
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` (required) | `number` |  | The amount. |
+| `currency` (required) | `string` |  | ISO 4217 code, e.g. "USD". |
+| `locale` | `string` |  | BCP 47 locale. Defaults to the user's. |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'display'` | `'md'` | `display` is a hero figure with a quieter symbol and minor units. |
+| `tone` | `'neutral' \| 'auto'` | `'neutral'` | `auto` colours gains success and losses error. |
+| `signDisplay` | `Intl signDisplay` |  | e.g. 'exceptZero' to show + on gains. |
+| `animate` | `boolean` | `false` | Roll the digits to new values (NumberTicker). The first render never animates. |
+
+## Example: Display
+
+```tsx
+<Amount value={128450.75} currency="USD" size="display" />
+```
+
+## Example: Gains and losses
+
+```tsx
+<Amount value={312.4} currency="USD" tone="auto" signDisplay="exceptZero" />
+<Amount value={-89.99} currency="USD" tone="auto" />
+```
+
+Related: [money-input](money-input.md), [number-ticker](number-ticker.md)

package/dist/skill/references/components/auth-card.md

@@ -0,0 +1,33 @@
+# AuthCard
+
+Authentication layout pattern. Wraps sign-in, sign-up, and reset flows in a centered card.
+
+- Package: `@nexub/patterns` · Category: Auth · Status: stable
+- Import: `import { AuthCard } from '@nexub/patterns';`
+- Docs: https://nexub-ds-docs.pages.dev/patterns/auth-card
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` (required) | `string` |  | Card heading (e.g. "Sign in to Nexub"). |
+| `description` | `string` |  | Subheading text. |
+| `logo` | `React.ReactNode` |  | Logo or brand mark above the title. |
+| `footer` | `React.ReactNode` |  | Footer content (e.g. "Don't have an account?"). |
+| `children` (required) | `React.ReactNode` |  | Form content. |
+
+## Example: Sign in
+
+```tsx
+<AuthCard
+  title="Sign in to Nexub"
+  description="Enter your credentials below"
+  footer={<Text size="sm">Don't have an account? <Link href="/signup">Sign up</Link></Text>}
+>
+  <div style={{ display: 'flex', flexDirection: 'column', gap: '12px' }}>
+    <Input type="email" placeholder="Email" />
+    <Input type="password" placeholder="Password" />
+    <Button>Sign in</Button>
+  </div>
+</AuthCard>
+```

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

@@ -0,0 +1,54 @@
+# Autocomplete
+
+Type-to-search input with matching options dropdown.
+
+- Package: `@nexub/react` · Category: Form Controls · Status: stable
+- Import: `import { Autocomplete } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/autocomplete
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `options` (required) | `{ value: string; label: string }[]` |  | Array of options available for selection. |
+| `value` | `string` |  | The controlled selected value. |
+| `onValueChange` | `(value: string) => void` |  | Callback fired when the selected value changes. |
+| `placeholder` | `string` |  | Placeholder text shown in the input when empty. |
+| `emptyText` | `string` |  | Text shown when no options match the current search query. |
+| `loading` | `boolean` |  | Shows a loading indicator while options are being fetched. |
+
+## Example: Default
+
+```tsx
+<Autocomplete
+  options={[
+    { value: 'react', label: 'React' },
+    { value: 'vue', label: 'Vue' },
+    { value: 'angular', label: 'Angular' },
+  ]}
+  placeholder="Search framework…"
+/>
+```
+
+## Example: With loading state
+
+```tsx
+<Autocomplete
+  options={[]}
+  loading
+  placeholder="Loading options…"
+/>
+```
+
+## Example: Custom empty text
+
+```tsx
+<Autocomplete
+  options={[
+    { value: 'nexub', label: 'Nexub' },
+    { value: 'acme', label: 'Acme Corp' },
+  ]}
+  placeholder="Search company…"
+  emptyText="No companies found. Try a different search."
+/>
+```

package/dist/skill/references/components/avatar-group.md

@@ -0,0 +1,26 @@
+# Avatar Group
+
+Stacked group of avatars with overflow count.
+
+- Package: `@nexub/react` · Category: Avatar · Status: stable
+- Import: `import { AvatarGroup } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/avatar-group
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `max` | `number` | `4` | Maximum number of avatars shown before an overflow count is rendered. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` |  | Controls avatar dimensions for all children. |
+| `spacing` | `'tight' \| 'normal'` | `'normal'` | Controls the overlap amount between stacked avatars. |
+
+## Example: Default
+
+```tsx
+<AvatarGroup max={3}>
+  <Avatar name="Alice" />
+  <Avatar name="Bob" />
+  <Avatar name="Carol" />
+  <Avatar name="Dave" />
+</AvatarGroup>
+```

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

@@ -0,0 +1,48 @@
+# Avatar
+
+Displays a user's profile picture with initials fallback.
+
+- Package: `@nexub/react` · Category: Avatar · Status: stable
+- Import: `import { Avatar } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/avatar
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `src` | `string` |  | URL of the profile image. |
+| `name` | `string` |  | Full name used to generate initials when no image is provided. |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Controls avatar dimensions. |
+| `badge` | `boolean` |  | Shows a status badge on the avatar. |
+| `badgeColor` | `string` |  | Colour of the status badge. |
+| `fallback` | `ReactNode` |  | Custom fallback rendered when the image fails to load and no name is provided. |
+
+## Example: Default
+
+```tsx
+<Avatar name="Alex Johnson" />
+```
+
+## Example: Sizes
+
+```tsx
+<div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
+  <Avatar size="xs" name="Alex Johnson" />
+  <Avatar size="sm" name="Alex Johnson" />
+  <Avatar size="md" name="Alex Johnson" />
+  <Avatar size="lg" name="Alex Johnson" />
+  <Avatar size="xl" name="Alex Johnson" />
+</div>
+```
+
+## Example: With image
+
+```tsx
+<Avatar src="https://i.pravatar.cc/150?img=1" name="Alex Johnson" />
+```
+
+## Example: With badge
+
+```tsx
+<Avatar name="Online User" badge badgeColor="green" />
+```

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

@@ -0,0 +1,71 @@
+# Badge
+
+Small status indicator or label. Communicates state, category, or count.
+
+- Package: `@nexub/react` · Category: Labels & Badges · Status: stable
+- Import: `import { Badge } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/badge
+
+## When to use
+
+- Labelling a status, category, or tag on an item
+- Showing a count or numeric indicator alongside an element
+- Highlighting new, featured, or updated content
+- Communicating a stage in a workflow (draft, published, archived)
+
+## When not to use
+
+- Interactive filtering — use FilterChip or Chip instead
+- Long text labels that exceed 2–3 words
+- Critical alerts requiring user action — use Alert or Toast
+- Replacing a button — badges are non-interactive by design
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'solid' \| 'soft' \| 'outline'` | `'solid'` | Visual fill style. |
+| `tone` | `'success' \| 'danger' \| 'warning' \| 'info' \| 'neutral'` | `'neutral'` | Semantic color tone. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Badge size. |
+| `leadingIcon` | `React.ReactNode` |  | Icon or dot rendered before the label. |
+
+## Example: Tones
+
+```tsx
+<div style={{ display: 'flex', gap: '8px' }}>
+  <Badge tone="success">Active</Badge>
+  <Badge tone="danger">Error</Badge>
+  <Badge tone="warning">Warning</Badge>
+  <Badge tone="info">Info</Badge>
+  <Badge tone="neutral">Draft</Badge>
+</div>
+```
+
+## Example: Variants
+
+```tsx
+<div style={{ display: 'flex', gap: '8px' }}>
+  <Badge variant="solid" tone="success">Solid</Badge>
+  <Badge variant="soft" tone="info">Soft</Badge>
+  <Badge variant="outline" tone="warning">Outline</Badge>
+</div>
+```
+
+## Example: With leading dot
+
+```tsx
+<div style={{ display: 'flex', gap: '8px' }}>
+  <Badge tone="success" leadingIcon={<span style={{ width: 6, height: 6, borderRadius: '50%', background: 'currentColor' }} />}>Online</Badge>
+  <Badge tone="danger" leadingIcon={<span style={{ width: 6, height: 6, borderRadius: '50%', background: 'currentColor' }} />}>Offline</Badge>
+</div>
+```
+
+## Accessibility
+
+- Roles: status (when conveying live state)
+- `—`: Badges are non-interactive and have no keyboard handlers.
+- Skipped in tab order. Decorative — never trap focus on a Badge.
+- Reads as inline text. For live status changes, wrap in an element with `role="status"` and `aria-live="polite"`.
+- For interactive equivalents (filtering, dismissing) reach for `Chip` or `FilterChip`.
+
+Related: [chip](chip.md), [tag](tag.md), [status-pill](status-pill.md)

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

@@ -0,0 +1,32 @@
+# Banner
+
+> **Deprecated.** Do not use in new code. Deprecated — use Alert. Full-width announcement banner, typically used at the top of a page.
+
+- Package: `@nexub/react` · Category: Feedback · Status: deprecated
+- Import: `import { Banner } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/banner
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tone` | `'neutral' \| 'info' \| 'success' \| 'warning' \| 'danger'` |  | Semantic colour tone of the banner. |
+| `action` | `ReactNode` |  | Action element (e.g. a button or link) rendered to the right of the content. |
+| `onClose` | `() => void` |  | When provided, renders a close button that dismisses the banner. |
+
+## Example: Default
+
+```tsx
+<Banner tone="info">New features available — <strong>see what's new</strong></Banner>
+```
+
+## Example: With action
+
+```tsx
+<Banner
+  tone="warning"
+  action={<Button size="sm" variant="outline">View details</Button>}
+>
+  Your subscription renews in 5 days.
+</Banner>
+```