Fork: 0
root / smart-home-server
Transfer to URL with SHA Find file
Newer
Older
smart-home-server / webclient-vue / docs / ui-kit-integration.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 7 hours ago 5 KB Document Vue client migration plan
Raw Blame History

gnexus-ui-kit Integration Notes

Repository:

https://git.gnexus.space/root/gnexus-ui-kit

The repository content was not available during this documentation pass, so this document defines the expected integration strategy rather than exact import paths.

Integration Principles

  • gnexus-ui-kit is a live design dependency and may update often.
  • The new client should stay compatible with current UI-kit releases.
  • Prefer consuming UI-kit directly as an updatable dependency, not as a copied snapshot.
  • Domain components should remain independent from visual implementation details.
  • Local adapters should be thin compatibility boundaries, not a forked design system.
  • Do not mirror UI-kit CSS variables/design tokens unless there is no other stable integration path.

Adapter Components

Create thin wrappers for the primitives the smart-home client needs:

Adapter Required Capability
UiButton variants, size, icon slot, loading, disabled.
UiBadge variants for success/warning/error/info/neutral.
UiCard clickable action-card layout.
UiDialog title, body, footer/actions, close behavior.
UiInput text input with label, error, hint.
UiTextarea multiline input with label, error, hint.
UiSelect searchable select/autocomplete.
UiTable caption, header, body slots, empty state, footer/meta.
UiToast success/error/warning/info notifications.
UiConfirmDialog confirmation for dangerous actions.

Variant Mapping From Current Client

Current button classes:

  • btn-primary
  • btn-secondary
  • btn-accent
  • btn-info
  • btn-danger
  • btn-warning
  • btn-success

Target semantic variants:

Current Target Variant
primary primary
secondary secondary
accent accent
info info
danger danger
warning warning
success success

Current badge classes:

  • badge-success
  • badge-warning
  • badge-error
  • badge-primary
  • badge-primary-outline

Target semantic variants:

Current Target Variant
badge-success success
badge-warning warning
badge-error danger
badge-primary primary
badge-primary-outline primary-outline

Smart-Home Specific Wrappers

Build domain wrappers on top of UI adapters:

  • DeviceConnectionBadge
  • DeviceStateBadges
  • ScriptStateBadge
  • ActionScriptCard
  • AreaTreeNode
  • PlaceInArea

These wrappers should hide backend-specific state names from low-level UI components. They should preserve UI-kit semantics and props as much as possible.

Dependency Strategy

Acceptable integration options, in preferred order:

  1. Install as package/git dependency if it exposes Vue components or CSS assets.
  2. Use a git dependency pinned by commit/tag in the lockfile.
  3. Add as git submodule only if package/git dependency is not viable.
  4. Copying a release into the project is a last resort and should be avoided because it breaks live design updates.

Application code should usually import local adapters, not UI-kit internals directly. The adapters exist for app-specific defaults and compatibility.

Allowed exception:

  • If UI-kit provides stable Vue components with a clear public API, feature code may import those components directly for simple cases. Complex domain components should still use local wrappers to centralize smart-home behavior.

Update Compatibility Policy

The client should support routine UI-kit updates.

Requirements:

  • Keep UI-kit as a dependency with a lockfile.
  • Do not copy UI-kit source files into app components.
  • Do not override UI-kit internals by selector unless explicitly documented.
  • Prefer documented CSS variables, component props, and public classes.
  • Keep app-specific styles in a narrow namespace.
  • Add a smoke checklist for UI-kit updates.
  • Avoid local wrappers that permanently freeze old UI-kit markup.

Update workflow:

  1. Update gnexus-ui-kit dependency.
  2. Run build.
  3. Run UI smoke checklist.
  4. Fix adapter compatibility if public API changed.
  5. Commit dependency lockfile and adapter changes together.

Smoke checklist:

  • App shell and navigation.
  • Buttons and loading states.
  • Badges for device/script states.
  • Tables.
  • Dialogs/modals.
  • Toasts.
  • Inputs and validation errors.
  • Select/autocomplete.
  • Action cards.
  • Area tree layout.

Evaluation Checklist

Before committing to the UI-kit integration method, verify:

  • Does it provide Vue components or only CSS/assets?
  • Does it require a build step?
  • Does it expose CSS variables or SCSS sources?
  • Does it include icons?
  • Does it include modal/toast/select/table primitives?
  • Does it support tree-shaking?
  • Is it installable through npm/git URL?

Fallback Plan

If the UI-kit is CSS-only:

  • Use it for tokens, base classes, and layout primitives.
  • Implement Vue components locally in src/components/ui.
  • Keep adapter names the same so future migration to UI-kit Vue components is possible.
  • Keep wrappers thin and class-driven, so UI-kit CSS updates apply automatically.

If the UI-kit is not immediately usable:

  • Scaffold with local adapters using minimal styles.
  • Keep visual implementation intentionally thin.
  • Replace adapter internals when UI-kit access/API is clarified.
  • Do not build a parallel permanent design system in webclient-vue.