@nexub/mcp 8.7.0 → 8.8.0

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

@@ -0,0 +1,46 @@
+# Form Error
+
+An error message with an alert icon, announced when it appears.
+
+- Package: `@nexub/react` · Category: Form & Input · Status: stable
+- Import: `import { FormError } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/form-error
+
+## When to use
+
+- A validation message under a field you lay out yourself
+
+## When not to use
+
+- Inside `FormField.Root`: use `FormField.Error`, which wires the ids for you
+- Errors for a whole form: use the Error Summary pattern
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | The message: say what went wrong and how to fix it. |
+| `id` | `string` |  | Point the control at it with `aria-describedby` so the message is read with the field. |
+
+## Example: Under a field
+
+```tsx
+import { FormError, Input, Label } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex w-[280px] flex-col gap-1">
+      <Label htmlFor="fe-email">Email</Label>
+      <Input id="fe-email" type="email" defaultValue="jane@" aria-invalid aria-describedby="fe-email-error" />
+      <FormError id="fe-email-error">Enter an email address like name@example.com.</FormError>
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: alert
+- Has `role="alert"`, so it is announced when rendered. Render it only when there is an error.
+
+Related: [form-field](form-field.md), [helper-text](helper-text.md)

package/dist/skill/references/components/keyboard-shortcut.md

@@ -0,0 +1,55 @@
+# Keyboard Shortcut
+
+A key combination as `Kbd` keys joined by plus signs, read as one label.
+
+- Package: `@nexub/react` · Category: Inline Primitives · Status: stable
+- Import: `import { KeyboardShortcut } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/keyboard-shortcut
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `keys` | `string[]` |  | The keys in order, e.g. `['⌘', 'K']`. Read as "⌘+K" (`aria-label`); pass your own `aria-label` for a spoken form like "Command K". |
+
+## Example: Default
+
+```tsx
+import { KeyboardShortcut } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex flex-wrap items-center gap-4">
+      <KeyboardShortcut keys={['⌘', 'K']} aria-label="Command K" />
+      <KeyboardShortcut keys={['Ctrl', 'Shift', 'P']} />
+    </div>
+  );
+}
+```
+
+## Example: In a menu
+
+```tsx
+import { KeyboardShortcut, Text } from '@nexub/react';
+
+const rows = [
+  { label: 'Search', keys: ['⌘', 'K'], spoken: 'Command K' },
+  { label: 'New project', keys: ['⌘', 'N'], spoken: 'Command N' },
+  { label: 'Save', keys: ['⌘', 'S'], spoken: 'Command S' },
+];
+
+export default function Example() {
+  return (
+    <ul className="flex w-[260px] flex-col gap-2">
+      {rows.map((r) => (
+        <li key={r.label} className="flex items-center justify-between">
+          <Text size="body-sm">{r.label}</Text>
+          <KeyboardShortcut keys={r.keys} aria-label={r.spoken} />
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+Related: [kbd](kbd.md), [command-palette](command-palette.md)

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

@@ -0,0 +1,59 @@
+# Logo
+
+The Nexub mark and wordmark, with an optional product name.
+
+- Package: `@nexub/react` · Category: Inline Primitives · Status: stable
+- Import: `import { Logo } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/logo
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'full' \| 'icon' \| 'mark'` |  | `full` = mark and wordmark; `icon` = the mark only. `mark` is the old name for `icon`. |
+| `product` | `string` |  | Product name after the wordmark, e.g. "Command Hub". Truncates in a narrow container. Ignored for `icon`. |
+| `size` | `'sm' \| 'md' \| 'lg'` |  | Height: 24, 32 or 40 px. |
+| `tone` | `'default' \| 'inverse'` |  | `inverse` is always white, for dark backgrounds or imagery in either theme. |
+| `mark` | `'color' \| 'mono'` |  | `color` = the official mark in brand colours; `mono` = `currentColor`. |
+
+## Example: Variants
+
+```tsx
+import { Logo } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex flex-wrap items-center gap-6">
+      <Logo />
+      <Logo variant="icon" />
+      <Logo mark="mono" />
+      <span className="rounded-shape-container bg-[var(--color-inverse-surface)] p-3">
+        <Logo tone="inverse" />
+      </span>
+    </div>
+  );
+}
+```
+
+## Example: With a product name
+
+```tsx
+import { Logo } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <div className="flex flex-col items-start gap-4">
+      <Logo product="Command Hub" size="sm" />
+      <Logo product="Command Hub" />
+      <Logo product="Command Hub" size="lg" />
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: img
+- Read as "Nexub", or "Nexub Command Hub" with `product`.
+
+Related: [top-nav](top-nav.md), [sidebar](sidebar.md)

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

@@ -0,0 +1,83 @@
+# Menubar
+
+A horizontal bar of menus, like a desktop app’s File / Edit / View, built on Radix.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { Menubar } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/menubar
+
+## When to use
+
+- Editors and tools with many commands grouped like a desktop app
+
+## When not to use
+
+- Site navigation: use `NavigationMenu` or `TopNav`
+- A few icon actions: use `Toolbar`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `Menubar.Root` | `compound` |  | The bar (`value`, `onValueChange`, `loop`). |
+| `Menubar.Menu` | `compound` |  | One menu: a trigger and its content. |
+| `Menubar.Trigger` | `compound` |  | The menu’s button in the bar. |
+| `Menubar.Portal / Content` | `compound` |  | Renders the floating menu in a portal (`sideOffset` default 8). |
+| `Menubar.Item` | `compound` |  | An action (`onSelect`, `disabled`). |
+| `Menubar.CheckboxItem / RadioGroup / RadioItem` | `compound` |  | Toggle and single-choice items. |
+| `Menubar.Label / Group / Separator / Arrow` | `compound` |  | Section heading, grouping, divider and an optional arrow. |
+| `Menubar.Sub / SubTrigger / SubContent` | `compound` |  | A nested submenu. |
+
+## Example: Default
+
+```tsx
+import { Menubar } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <Menubar.Root>
+      <Menubar.Menu>
+        <Menubar.Trigger>File</Menubar.Trigger>
+        <Menubar.Portal>
+          <Menubar.Content>
+            <Menubar.Item>New file</Menubar.Item>
+            <Menubar.Item>Open…</Menubar.Item>
+            <Menubar.Separator />
+            <Menubar.Item>Save</Menubar.Item>
+          </Menubar.Content>
+        </Menubar.Portal>
+      </Menubar.Menu>
+      <Menubar.Menu>
+        <Menubar.Trigger>Edit</Menubar.Trigger>
+        <Menubar.Portal>
+          <Menubar.Content>
+            <Menubar.Item>Undo</Menubar.Item>
+            <Menubar.Item>Redo</Menubar.Item>
+            <Menubar.Separator />
+            <Menubar.Item>Copy</Menubar.Item>
+            <Menubar.Item>Paste</Menubar.Item>
+          </Menubar.Content>
+        </Menubar.Portal>
+      </Menubar.Menu>
+      <Menubar.Menu>
+        <Menubar.Trigger>View</Menubar.Trigger>
+        <Menubar.Portal>
+          <Menubar.Content>
+            <Menubar.Item>Zoom in</Menubar.Item>
+            <Menubar.Item>Zoom out</Menubar.Item>
+          </Menubar.Content>
+        </Menubar.Portal>
+      </Menubar.Menu>
+    </Menubar.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: menubar, menu, menuitem
+- `Arrow Left / Right`: Moves between menus in the bar, and between open menus.
+- `Enter / Space / Arrow Down`: Opens the focused menu.
+- `Escape`: Closes the menu.
+
+Related: [dropdown-menu](dropdown-menu.md), [toolbar](toolbar.md), [context-menu](context-menu.md)

package/dist/skill/references/components/navigation-menu.md

@@ -0,0 +1,78 @@
+# Navigation Menu
+
+Site navigation links with flyout panels, built on Radix.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { NavigationMenu } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/navigation-menu
+
+## When to use
+
+- Marketing or docs sites whose sections need a flyout of links
+
+## When not to use
+
+- Actions: use `DropdownMenu` or `Menubar`
+- App navigation without flyouts: use `TopNav` or `Sidebar`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `NavigationMenu.Root` | `compound` |  | The `<nav>` (`value`, `onValueChange`, `delayDuration`). Renders the panel viewport for you. |
+| `NavigationMenu.List / Item` | `compound` |  | The list of top-level entries. |
+| `NavigationMenu.Trigger` | `compound` |  | Opens the item’s panel on hover or click. |
+| `NavigationMenu.Content` | `compound` |  | The flyout panel for an item. |
+| `NavigationMenu.Link` | `compound` |  | A link, top-level or inside a panel (`href`, `active`, `asChild` for router links). |
+| `NavigationMenu.Indicator` | `compound` |  | Optional arrow under the open trigger. |
+
+## Example: Default
+
+```tsx
+import { NavigationMenu } from '@nexub/react';
+
+const products = [
+  { title: 'Analytics', body: 'Track key metrics in real time.' },
+  { title: 'Dashboards', body: 'Build and share custom views.' },
+  { title: 'Reports', body: 'Export and schedule reports.' },
+];
+
+export default function Example() {
+  return (
+    <NavigationMenu.Root aria-label="Site">
+      <NavigationMenu.List>
+        <NavigationMenu.Item>
+          <NavigationMenu.Trigger>Products</NavigationMenu.Trigger>
+          <NavigationMenu.Content>
+            <ul className="grid w-[280px] gap-1 p-2">
+              {products.map((p) => (
+                <li key={p.title}>
+                  <NavigationMenu.Link href="#">
+                    <span className="block text-label-lg">{p.title}</span>
+                    <span className="mt-1 block text-body-sm text-[var(--color-on-surface-muted)]">{p.body}</span>
+                  </NavigationMenu.Link>
+                </li>
+              ))}
+            </ul>
+          </NavigationMenu.Content>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item>
+          <NavigationMenu.Link href="#">Pricing</NavigationMenu.Link>
+        </NavigationMenu.Item>
+        <NavigationMenu.Item>
+          <NavigationMenu.Link href="#">Docs</NavigationMenu.Link>
+        </NavigationMenu.Item>
+      </NavigationMenu.List>
+    </NavigationMenu.Root>
+  );
+}
+```
+
+## Accessibility
+
+- `Tab`: Moves between top-level entries.
+- `Enter / Space`: Opens or closes a panel.
+- `Escape`: Closes the panel and returns focus to its trigger.
+- Give `NavigationMenu.Root` an `aria-label` when the page has more than one navigation landmark.
+
+Related: [top-nav](top-nav.md), [menubar](menubar.md)

package/dist/skill/references/components/page-header.md

@@ -0,0 +1,64 @@
+# Page Header
+
+The top of a page: title, description, breadcrumb and actions.
+
+- Package: `@nexub/react` · Category: Layout · Status: stable
+- Import: `import { PageHeader } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/page-header
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` |  | The page title. Truncates on one line. |
+| `description` | `ReactNode` |  | A line under the title. |
+| `actions` | `ReactNode` |  | Buttons on the end side; they wrap under the title on narrow screens. |
+| `breadcrumb` | `ReactNode` |  | A `Breadcrumb` above the title. |
+| `level` | `1 \| 2 \| 3` |  | Heading level of the title. Use 2 or 3 when the page already has an h1. |
+
+## Example: Default
+
+```tsx
+import { Button, PageHeader } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <PageHeader
+      className="w-full"
+      level={2}
+      title="Projects"
+      description="Everything your team is working on."
+      actions={<><Button variant="outlined">Import</Button><Button>New project</Button></>}
+    />
+  );
+}
+```
+
+## Example: With breadcrumb
+
+```tsx
+import { Breadcrumb, Button, PageHeader } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <PageHeader
+      className="w-full"
+      level={2}
+      breadcrumb={
+        <Breadcrumb.Root>
+          <Breadcrumb.List>
+            <Breadcrumb.Item><Breadcrumb.Link href="#">Projects</Breadcrumb.Link></Breadcrumb.Item>
+            <Breadcrumb.Separator />
+            <Breadcrumb.Item><Breadcrumb.Page>Billing service</Breadcrumb.Page></Breadcrumb.Item>
+          </Breadcrumb.List>
+        </Breadcrumb.Root>
+      }
+      title="Billing service"
+      description="Updated 2 hours ago"
+      actions={<Button variant="outlined">Settings</Button>}
+    />
+  );
+}
+```
+
+Related: [breadcrumb](breadcrumb.md), [app-shell](app-shell.md), [heading](heading.md)

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

@@ -0,0 +1,43 @@
+# Section
+
+A full-width page band with vertical padding and a background tone; put a `Container` inside.
+
+- Package: `@nexub/react` · Category: Layout · Status: stable
+- Import: `import { Section } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/section
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `paddingY` | `'sm' \| 'md' \| 'lg'` |  | Vertical padding: 48, 80 or 128 px. |
+| `tone` | `'default' \| 'subtle' \| 'muted' \| 'inverse'` |  | Background: the surface, two container tints, or the inverse surface. |
+| `asChild` | `boolean` |  | Apply the classes to the child element instead of a `<section>`. |
+
+## Example: Tones
+
+```tsx
+import { Container, Section, Text } from '@nexub/react';
+
+const tones = ['default', 'subtle', 'muted', 'inverse'] as const;
+
+export default function Example() {
+  return (
+    <div className="w-full overflow-hidden rounded-shape-container border border-[var(--color-outline-variant)]">
+      {tones.map((tone) => (
+        <Section key={tone} tone={tone} paddingY="sm" aria-label={`${tone} tone`}>
+          <Container size="sm">
+            <Text size="body-sm" className="text-inherit">tone=&quot;{tone}&quot;</Text>
+          </Container>
+        </Section>
+      ))}
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+- A `<section>` is a region landmark only when it has an accessible name: give it `aria-labelledby` pointing at its heading.
+
+Related: [container](container.md), [box](box.md)

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

@@ -0,0 +1,78 @@
+# Sidebar
+
+Vertical app navigation: a header, grouped items with icons, and a pinned footer. Collapses to icons.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { Sidebar } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/sidebar
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `collapsed` | `boolean` |  | Icon-only width. Labels stay for screen readers and show as a native tooltip. |
+| `aria-label` | `string` |  | Name of the nav landmark. Defaults to the localised "Sidebar". |
+| `SidebarHeader status` | `ReactNode` |  | Trailing element next to the logo (`Sidebar.Header` children), e.g. a `Badge`. Moves under the logo when they don’t fit. |
+| `SidebarGroup label` | `string` |  | Heading above a group of items. |
+| `SidebarItem icon` | `ReactNode` |  | Leading icon; the only thing shown when collapsed. |
+| `SidebarItem active` | `boolean` |  | Marks the current page (`aria-current="page"`). |
+| `SidebarItem asChild` | `boolean` |  | Use your router `<Link>` as the item; pass it as the only child. |
+| `Sidebar.Separator / Footer` | `compound` |  | A divider, and a footer that stays pinned while the items scroll. |
+
+## Example: Default
+
+```tsx
+import { Badge, Logo, Sidebar } from '@nexub/react';
+import { BarChart3, Folder, Home, Settings, Users } from '@nexub/icons';
+
+export default function Example() {
+  return (
+    <div className="h-[380px]">
+      <Sidebar.Root aria-label="Workspace" className="rounded-shape-container">
+        <Sidebar.Header status={<Badge variant="soft" size="sm">Beta</Badge>}>
+          <Logo size="sm" />
+        </Sidebar.Header>
+        <Sidebar.Group>
+          <Sidebar.Item href="#" icon={<Home size="sm" />} active>Overview</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<Folder size="sm" />}>Projects</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<BarChart3 size="sm" />}>Reports</Sidebar.Item>
+        </Sidebar.Group>
+        <Sidebar.Group label="Admin">
+          <Sidebar.Item href="#" icon={<Users size="sm" />}>Members</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<Settings size="sm" />}>Settings</Sidebar.Item>
+        </Sidebar.Group>
+        <Sidebar.Footer className="text-body-sm text-[var(--color-on-surface-muted)]">v2.4.0</Sidebar.Footer>
+      </Sidebar.Root>
+    </div>
+  );
+}
+```
+
+## Example: Collapsed
+
+```tsx
+import * as React from 'react';
+import { Button, Sidebar } from '@nexub/react';
+import { BarChart3, Folder, Home, Settings } from '@nexub/icons';
+
+export default function Example() {
+  const [collapsed, setCollapsed] = React.useState(true);
+  return (
+    <div className="flex h-[280px] items-start gap-4">
+      <Sidebar.Root aria-label="Workspace" collapsed={collapsed} className="rounded-shape-container">
+        <Sidebar.Group>
+          <Sidebar.Item href="#" icon={<Home size="sm" />} active>Overview</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<Folder size="sm" />}>Projects</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<BarChart3 size="sm" />}>Reports</Sidebar.Item>
+          <Sidebar.Item href="#" icon={<Settings size="sm" />}>Settings</Sidebar.Item>
+        </Sidebar.Group>
+      </Sidebar.Root>
+      <Button variant="outlined" onClick={() => setCollapsed((c) => !c)} aria-pressed={!collapsed}>
+        {collapsed ? 'Expand' : 'Collapse'}
+      </Button>
+    </div>
+  );
+}
+```
+
+Related: [app-shell](app-shell.md), [navigation-rail](navigation-rail.md), [top-nav](top-nav.md)

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

@@ -0,0 +1,72 @@
+# Toolbar
+
+A row of buttons and toggles with one tab stop and arrow-key movement, built on Radix.
+
+- Package: `@nexub/react` · Category: Actions · Status: stable
+- Import: `import { Toolbar } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/toolbar
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `floating` | `boolean` |  | A glass capsule for the control layer above content, e.g. editor or selection actions. |
+| `placement` | `'bottom'` |  | With `floating`: pin it to the bottom centre of the viewport. |
+| `orientation / loop / dir` | `Radix Toolbar props` |  | Arrow-key direction and wrapping. |
+| `aria-label` | `string` |  | Name the toolbar, e.g. "Text formatting". |
+| `Toolbar.Button` | `compound` |  | An action button. |
+| `Toolbar.ToggleGroup / ToggleItem` | `compound` |  | A set of toggles (`type="single" \| "multiple"`, `value`). Icon-only items need `aria-label`. |
+| `Toolbar.Separator` | `compound` |  | A divider between groups. |
+
+## Example: Default
+
+```tsx
+import { Toolbar } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <Toolbar.Root aria-label="Text formatting">
+      <Toolbar.ToggleGroup type="multiple" aria-label="Text style">
+        <Toolbar.ToggleItem value="bold" aria-label="Bold"><strong>B</strong></Toolbar.ToggleItem>
+        <Toolbar.ToggleItem value="italic" aria-label="Italic"><em>I</em></Toolbar.ToggleItem>
+        <Toolbar.ToggleItem value="underline" aria-label="Underline"><span className="underline">U</span></Toolbar.ToggleItem>
+      </Toolbar.ToggleGroup>
+      <Toolbar.Separator />
+      <Toolbar.ToggleGroup type="single" defaultValue="left" aria-label="Alignment">
+        <Toolbar.ToggleItem value="left" aria-label="Align left">L</Toolbar.ToggleItem>
+        <Toolbar.ToggleItem value="center" aria-label="Align centre">C</Toolbar.ToggleItem>
+        <Toolbar.ToggleItem value="right" aria-label="Align right">R</Toolbar.ToggleItem>
+      </Toolbar.ToggleGroup>
+      <Toolbar.Separator />
+      <Toolbar.Button>Clear formatting</Toolbar.Button>
+    </Toolbar.Root>
+  );
+}
+```
+
+## Example: Floating
+
+```tsx
+import { Toolbar } from '@nexub/react';
+import { Copy, Pencil, Trash2 } from '@nexub/icons';
+
+export default function Example() {
+  return (
+    <Toolbar.Root floating aria-label="Selection">
+      <Toolbar.Button><Pencil size="sm" aria-hidden="true" />Edit</Toolbar.Button>
+      <Toolbar.Button><Copy size="sm" aria-hidden="true" />Duplicate</Toolbar.Button>
+      <Toolbar.Separator />
+      <Toolbar.Button><Trash2 size="sm" aria-hidden="true" />Delete</Toolbar.Button>
+    </Toolbar.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: toolbar
+- `Tab`: Moves into and out of the toolbar (one tab stop).
+- `Arrow Left / Right`: Moves between controls.
+- `Enter / Space`: Activates a button or toggles an item.
+
+Related: [toggle-group](toggle-group.md), [button-group](button-group.md), [action-bar](action-bar.md)

package/dist/skill/references/components/top-nav.md

@@ -0,0 +1,48 @@
+# Top Nav
+
+A sticky app header: logo, main navigation links and trailing actions.
+
+- Package: `@nexub/react` · Category: Navigation · Status: stable
+- Import: `import { TopNav } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/top-nav
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `surface` | `'solid' \| 'glass'` |  | Glass material on the bar — see Foundations → Materials. |
+| `scrollEdge` | `'soft' \| 'hard'` |  | `soft` dissolves scrolling content under the bar (no divider); `hard` is an opaque band. Default: a divider. |
+| `TopNav.Logo / Menu / Actions` | `compound` |  | The logo slot, the `<nav>` of links (scrolls sideways on narrow screens) and the end-aligned actions. |
+| `TopNavItem active` | `boolean` |  | Marks the current page (`aria-current="page"`). |
+| `TopNavItem asChild` | `boolean` |  | Use your router `<Link>` instead of an `<a>`. |
+
+## Example: Default
+
+```tsx
+import { Avatar, IconButton, Logo, TopNav } from '@nexub/react';
+import { Bell } from '@nexub/icons';
+
+export default function Example() {
+  return (
+    <TopNav.Root className="static w-full">
+      <TopNav.Logo><Logo size="sm" /></TopNav.Logo>
+      <TopNav.Menu>
+        <TopNav.Item href="#" active>Overview</TopNav.Item>
+        <TopNav.Item href="#">Projects</TopNav.Item>
+        <TopNav.Item href="#">Reports</TopNav.Item>
+      </TopNav.Menu>
+      <TopNav.Actions>
+        <IconButton variant="ghost" label="Notifications"><Bell size="sm" /></IconButton>
+        <Avatar size="sm" name="Jane Smith" />
+      </TopNav.Actions>
+    </TopNav.Root>
+  );
+}
+```
+
+## Accessibility
+
+- Roles: banner, navigation
+- `TopNav.Root` is a `<header>`; `TopNav.Menu` is a `<nav>` named with the localised "Main navigation".
+
+Related: [app-shell](app-shell.md), [sidebar](sidebar.md), [navigation-menu](navigation-menu.md), [logo](logo.md)

package/dist/skill/references/components/visually-hidden.md

@@ -0,0 +1,40 @@
+# Visually Hidden
+
+Content for screen readers only: hidden on screen but still read out (Radix).
+
+- Package: `@nexub/react` · Category: Inline Primitives · Status: stable
+- Import: `import { VisuallyHidden } from '@nexub/react';`
+- Docs: https://nexub-ds-docs.pages.dev/components/visually-hidden
+
+## When to use
+
+- Extra context a sighted user gets from layout, e.g. "(opens in a new tab)"
+
+## When not to use
+
+- Naming an icon button: `IconButton` takes a `label`
+- Hiding content from everyone: use `hidden`
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` |  | The text to read out. |
+| `asChild` | `boolean` |  | Hide your own element instead of a `<span>`. |
+
+## Example: Label an icon
+
+```tsx
+import { Link, VisuallyHidden } from '@nexub/react';
+
+export default function Example() {
+  return (
+    <Link href="https://example.com" target="_blank" rel="noreferrer">
+      Status page
+      <VisuallyHidden> (opens in a new tab)</VisuallyHidden>
+    </Link>
+  );
+}
+```
+
+Related: [icon-button](icon-button.md)