# Vue AI Usage Guide

This document is for AI agents working inside Vue projects that consume GNexus UI Kit.

## Rule

Prefer `gnexus-ui-kit/vue` components over hand-written kit markup.

Do not recreate modal, drawer, tab, toast, form, button, or table markup manually unless the adapter does not expose the needed component yet.

## Required Imports

At app root:

```js
import "gnexus-ui-kit/dist/css/kit.css";
import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css";
```

Use named imports:

```js
import { GnButton, GnInput, GnModal } from "gnexus-ui-kit/vue";
```

Or global registration:

```js
import { GnexusUiVue } from "gnexus-ui-kit/vue";
app.use(GnexusUiVue);
```

## Component Selection

Use these mappings:

- button command: `GnButton`
- icon-only command: `GnIconButton`
- status label: `GnBadge`
- message block: `GnAlert`
- framed content: `GnCard`
- page title/actions: `GnPageHeader`
- text field: `GnInput`
- multiline field: `GnTextarea`
- select field: `GnSelect`
- boolean control: `GnCheckbox` or `GnSwitch`
- view switcher: `GnTabs`
- disclosure group: `GnAccordion`
- dialog: `GnModal`
- side panel: `GnDrawer`
- global notification: `GnToastProvider` + `useToast`
- confirmation: `GnConfirmDialog`
- structured rows: `GnTable`
- toolbar/action row: `GnToolbar`
- input addon layout: `GnInputGroup`
- search input: `GnSearchField`
- pagination: `GnPagination`
- empty result panel: `GnEmptyState`
- loading placeholders: `GnSkeleton`
- key-value metadata: `GnDescriptionList`
- determinate progress: `GnProgress`
- wizard/staged process: `GnSteps`
- chips/filters: `GnChip`, `GnChipGroup`
- user or entity identity: `GnAvatar`, `GnIdentity`, `GnAvatarStack`
- activity timeline/log: `GnTimeline`, `GnActivityLog`
- dropdown menu: `GnDropdown`
- contextual panel: `GnPopover`
- compact hint: `GnTooltip`
- navigation list: `GnNavList`
- application shell navigation: `GnNavigationShell`

## Do Not

- Do not copy raw modal markup from demo partials into Vue apps.
- Do not call `GNexusUIKit.Modals.create()` from Vue components.
- Do not call `GNexusUIKit.Overlays.init()` or `GNexusUIKit.NavigationShell.init()` in Vue projects.
- Do not run `Accordion.init()` or `Tabs.init()` inside Vue components.
- Do not invent new variant names.
- Do not duplicate GNexus CSS in Vue component scoped styles.
- Do not bundle Vue into the UI-kit adapter.

## Acceptable Raw Markup

Raw classes are acceptable for layout-only wrappers and content that has no Vue adapter yet:

```html
<div class="form-grid">...</div>
<div class="demo-actions">...</div>
```

For interactive components, add or extend the adapter first.

## Update Policy

When the base kit changes markup for a component, update the Vue adapter in this repository. Downstream projects should receive compatibility through dependency updates, not local rewrites.

## Smoke Checks

Before claiming Vue adapter compatibility, run:

```bash
npm run build
npm run build:example:vue
```

Warnings about `/assets/fonts/...` in Vite builds are expected with the current CSS contract. They mean the host app must serve GNexus UI Kit assets at `/assets`.