# Vue Adapter Migration Policy

The Vue adapter is the compatibility layer for Vue projects using GNexus UI Kit. Downstream projects should update this package rather than keeping local wrappers.

## Source Of Truth

- Visual design and class contracts live in `src/scss/components/`.
- Plain HTML behavior lives in `src/js/components/`.
- Vue behavior lives in `src/vue/`.
- Vue usage guidance lives in `docs/vue/`.

The Vue adapter must render GNexus UI Kit classes. It should not introduce a parallel visual system.

## Breaking Changes

These changes are breaking and require a migration note:

- renaming or removing a Vue component;
- changing a prop, emit, or slot name;
- changing `v-model` semantics;
- changing rendered class contracts in a way that affects styling;
- removing an exported component from `gnexus-ui-kit/vue`;
- requiring a new global setup step in host apps.

## Non-Breaking Changes

These are usually non-breaking:

- adding new optional props;
- adding new named exports;
- adding new slots while preserving old slots;
- improving keyboard/focus behavior without changing public API;
- adding docs and examples.

## Downstream Rules

Vue projects should not:

- copy demo partial markup for interactive components;
- monkey-patch GNexus component classes in scoped Vue styles;
- call plain HTML initializers such as `Overlays.init()` from Vue components;
- create project-local wrappers when a component belongs in `src/vue`.

If a project needs a missing component, add it to this repository and consume it through `gnexus-ui-kit/vue`.

## Adapter Update Checklist

When changing a base kit component:

1. Check the corresponding Vue component.
2. Update props/events/slots only when needed.
3. Update `docs/vue/component-map.md`.
4. Update `docs/vue/ai-usage-guide.md` if usage rules change.
5. Run:

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

Vite warnings about `/assets/fonts/...` are expected while the CSS asset contract uses absolute `/assets` paths.