# gnexus-ui-kit Integration Notes

Repository:

```text
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`.