Fork: 0
root / gnexus-ui-kit
Transfer to URL with SHA Find file
Newer
Older
gnexus-ui-kit / docs / vue / ai-usage-guide.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 4 KB Add GnLoginCard component for standardized login forms
Raw Blame History

Vue AI Usage Guide

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

Rule

The Vue adapter is the primary contract for Vue projects. Always use gnexus-ui-kit/vue components instead of writing raw kit markup by hand.

Do not recreate modal, drawer, tab, toast, form, button, or table markup manually unless the adapter does not expose the needed component yet. Raw classes are acceptable only for layout wrappers and content that has no Vue adapter component.

Required Imports

At app root:

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

Use named imports:

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

Or global registration:

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

Component Selection

Use these mappings:

  • button command: GnButton
  • icon-only command: GnIconButton
  • copy to clipboard: GnCopyButton
  • status label: GnBadge
  • message block: GnAlert
  • framed content: GnCard
  • horizontal content card: GnHorizontalCard
  • login form card: GnLoginCard
  • page title/actions: GnPageHeader
  • text field: GnInput
  • multiline field: GnTextarea
  • select field: GnSelect
  • boolean control: GnCheckbox or GnSwitch
  • radio choice: GnRadio or GnRadioGroup
  • range slider: GnRange
  • file upload: GnFileUpload
  • searchable option input: GnCombobox
  • view switcher: GnTabs
  • router-driven tabs: GnRouterTabs
  • 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
  • usage/limit card: GnUsageMeter
  • staged progress strip: GnProgressStages
  • wizard/staged process: GnSteps
  • chips/filters: GnChip, GnChipGroup
  • user or entity identity: GnAvatar, GnIdentity, GnAvatarStack
  • activity timeline/log: GnTimeline, GnActivityLog
  • basic/definition/action lists: GnList, GnDefinitionList, GnActionList
  • loaders: GnLoader
  • specialized cards: GnStatusCard, GnMetricCard, GnActionCard
  • 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 use the legacy advancedSelect() helper in Vue; use GnCombobox.
  • Do not use InputPatterns.init() for Vue file upload previews; use GnFileUpload.
  • 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.
  • Do not pass icon names without the ph- prefix (e.g. icon="house" is wrong; use icon="ph-house").
  • Do not use non-Phosphor icon classes in any icon prop.

Acceptable Raw Markup

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

<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:

npm run build
npm run test:vue-adapter

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.

The local example clears examples/vue/node_modules/.vite before build because gnexus-ui-kit is linked from the repository root and Vite can otherwise reuse stale optimized metadata after dist/vue changes.

Behavior Contracts

  • GnModal and GnDrawer handle Escape, focus return, and Tab focus trapping.
  • GnToastProvider is single-toast by design: a new toast replaces the current one.
  • GnCombobox owns combobox/listbox ARIA and keyboard movement.
  • GnFileUpload owns preview object URLs and cleans them up on remove/unmount.
  • GnRouterTabs drives active state from the current vue-router route and calls router.push() on tab activation. Requires vue-router in the host app.
  • GnNavList detects item.to (router target) and renders accessible links with resolved href. If vue-router is present, clicking navigates via the router and active state is computed from the current route.