Fork: 0
root / gnexus-ui-kit
Transfer to URL with SHA Find file
Newer
Older
gnexus-ui-kit / CLAUDE.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 6 KB Improve Vue adapter usability, add router support, and fix animations
Raw Blame History

GNexus UI Kit — AI Agent Reference

When working on a Vue project that depends on gnexus-ui-kit, always use the official Vue adapter components instead of writing raw HTML/CSS markup. This document is the single source of truth for which components exist and when to use them.

Golden Rule

Prefer gnexus-ui-kit/vue components. Do not recreate modal, drawer, tab, toast, form, button, or table markup manually unless the adapter does not expose the needed component yet.

Required Setup (once per app)

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

Import Pattern

Named imports (preferred):

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

Global registration:

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

Icon Naming

All icon props must use the ph- prefix. Phosphor Icons are the only supported icon set.

// Correct
icon="ph-house"
icon="ph-plus"
icon="ph-bold ph-spinner"   // multiple classes allowed

// Wrong — will trigger a dev warning and may not render
icon="house"
icon="plus"

Component Catalog

Need Component Props you will use
Button GnButton variant, size, icon, loading, disabled
Icon-only button GnIconButton icon, label
Status label GnBadge variant, outline
Message block GnAlert variant
Card / panel GnCard title (slot), footer (slot)
Page title bar GnPageHeader kicker, title, subtitle, meta, actions (slot)
Text field GnInput v-model, label, icon, state, help
Textarea GnTextarea v-model, label, state, help
Select dropdown GnSelect v-model, label, options
Checkbox GnCheckbox v-model, label, disabled
Toggle switch GnSwitch v-model, label, disabled
Radio GnRadio / GnRadioGroup v-model, options
Range slider GnRange v-model, label, min, max
File upload GnFileUpload v-model, badge, multiple, accept
Searchable select GnCombobox v-model, label, options, placeholder
Tabs GnTabs v-model, items
Router tabs GnRouterTabs items (with to), activeMatch
Accordion GnAccordion items, v-model, multiple
Modal dialog GnModal v-model:open, title, closeOnBackdrop
Side drawer GnDrawer v-model:open, title, position
Toasts GnToastProvider + useToast Wrap app once; call toast.success({ title, text })
Confirm dialog GnConfirmDialog v-model:open, title, message, confirmVariant
Table GnTable columns, rows, caption, emptyText
Toolbar GnToolbar title, meta, actions (slot)
Input group GnInputGroup addon (slot), action (slot)
Search field GnSearchField v-model
Pagination GnPagination page, total-pages
Empty state GnEmptyState title, text, icon, actions (slot)
Skeleton loader GnSkeleton —
Key-value list GnDescriptionList items
Progress bar GnProgress value, label, animated
Usage meter card GnUsageMeter value, label, max
Staged progress GnProgressStages items
Wizard steps GnSteps items, current
Chip / tag GnChip variant, selected, removable
Chip group GnChipGroup —
Avatar GnAvatar initials, icon, image, size, status
Identity row GnIdentity title, meta, avatar props
Avatar stack GnAvatarStack items
Timeline GnTimeline items
Activity log GnActivityLog items
Basic list GnList items
Definition list GnDefinitionList items
Action list GnActionList items
Loader / spinner GnLoader —
Status card GnStatusCard variant, title, meta
Metric card GnMetricCard title, value, trend
Action card GnActionCard title, text, actions (slot)
Dropdown menu GnDropdown items, label, variant
Popover panel GnPopover title, text, label
Tooltip GnTooltip text
Navigation list GnNavList items
App shell GnNavigationShell brand, items, current, footerLeft, footerRight

Variants

Use only these variant names:

primary, secondary, accent, success, warning, danger, error, info

danger and error render the same color in most components.

What NOT to do

  • 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 scoped <style> blocks.
  • Do not write class="btn btn-primary" when GnButton exists.

Acceptable Raw Markup

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

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

For any interactive component, add or extend the adapter first.

Slot Conventions

  • GnTabs uses tab ids as slot names: <template #overview>...</template>
  • GnTable uses cell-${column.key}: <template #cell-status="{ value }"><GnBadge>{{ value }}</GnBadge></template>
  • GnModal uses default, title, footer, and actions (actions receives { close })

Behavior Contracts

  • GnModal and GnDrawer handle Escape, focus return, and Tab trapping automatically.
  • GnToastProvider shows one toast at a time: a new toast replaces the previous one.
  • GnCombobox owns combobox/listbox ARIA and keyboard navigation.
  • GnFileUpload owns preview object URLs and cleans them up on remove/unmount.

Verification

Before claiming Vue adapter compatibility in this repo, run:

npm run build
npm run test:vue-adapter