Fork: 0
root / gnexus-ui-kit
Transfer to URL with SHA Find file
Newer
Older
gnexus-ui-kit / docs / vue / migration-policy.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 19 hours ago 2 KB Harden Vue adapter accessibility behavior
Raw Blame History

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.

Document behavior changes when they affect user expectations, even if they are not breaking. Examples: focus trapping, toast queueing policy, or file preview cleanup.

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:
npm run build
npm run test:vue-adapter

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