# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository overview

`vmk-ui-kit` is a new UI kit that must be visually based on a Figma mockup while remaining compatible with the existing [`gnexus-ui-kit`](https://git.gnexus.space/git/root/gnexus-ui-kit.git). Existing projects that consume `gnexus-ui-kit` should be able to switch to this package with minimal or no code changes.

A read-only clone of the reference kit is kept at `/home/gmikcon/Projects/gnexus-ui-kit-reference` for inspection. Do not edit that repository.

## Compatibility contract

The primary consumer contract of `gnexus-ui-kit` is its Vue 3 adapter (`gnexus-ui-kit/vue`). The secondary contract is the browser JS bundle (`gnexus-ui-kit` main/module) and CSS. Preserve these public surfaces:

- Package name and entry points should match or alias the reference package exports:
  - `main`: `dist/js/gnexus-ui-kit.js`
  - `module`: `dist/js/gnexus-ui-kit.esm.js`
  - `style`: `dist/css/kit.css`
  - `exports["."]` (import/require/default)
  - `exports["./vue"]` and `exports["./vue/*"]`
  - `exports["./dist/css/kit.css"]` / `exports["./css/kit.css"]`
  - `exports["./dist/assets/*"]`
- Vue adapter exports all `Gn*` components plus `useToast`, `tryUseRouter`, `tryUseRoute`, `isRouteActive`, and the `GnexusUiVue` plugin.
- Browser bundle exposes `window.GNexusUIKit` with `Helper`, `Toasts`, `Modals`, `advancedSelect`, `editableString`, `confirmPopup`, `Drawer`, `NavigationShell`, `Overlays`, `InputPatterns`, `Accordion`, `Tabs`.
- CSS classes and markup patterns in the reference `demo/partials/*.html` are the source of truth for adapter component output.
- Icons must always carry the `ph` class and icon props must use the `ph-` prefix (Phosphor Icons only).
- Supported variant names: `primary`, `secondary`, `accent`, `success`, `warning`, `danger`, `error`, `info`.

## Reference architecture

The reference kit uses:

- Gulp 5 build pipeline:
  - Sass (modern Dart Sass API, `@use`/`@forward`) → PostCSS/autoprefixer → clean-css
  - esbuild for browser IIFE, ESM, and Vue adapter ESM bundles
  - `gulp-file-include` for HTML partials
  - BrowserSync dev server on `http://localhost:3000`
- `src/scss/kit.scss` — main CSS entry.
- `src/js/index.js` — browser bundle entry.
- `src/vue/index.js` — Vue adapter entry; components are render-function `.js` files.
- `demo/index.html` + `demo/partials/*.html` — component documentation/demo page.
- `public/assets/` — fonts (IBM Plex Mono), Phosphor Icons, highlight.js, images.
- `dist/` — generated build output, ignored by git.

## Design tokens (reference)

The reference visual style is dark cyber/terminal with Tokyo Night influence. Tokens to keep aligned if the new mockup changes them:

- Fonts: IBM Plex Mono base + Phosphor Icons.
- Palette: `$color-black` (#16161E), `$color-dark` (#1F2335), `$color-grey` (#414868), `$color-cyan` (#7DCFFF), `$color-magenta` (#FF00CC), `$color-hot-pink` (#FF1492), `$color-electric-blue` (#7AA2F7), `$color-orange` (#FF9E64), `$color-purple` (#BB9AF7), `$color-indigo` (#565F89), `$color-teal` (#73DACA), `$color-neon-yellow` (#E0AF68), `$color-neon-green` (#9ECE6A), `$color-text-light` (#C0CAF5), `$color-text-medium` (#A9B1D6), `$color-text-dark` (#787C99).
- UI states: `$color-primary` (text-light), `$color-secondary` (electric-blue), `$color-accent` (orange), `$color-success` (neon-green), `$color-warning` (neon-yellow), `$color-error` (#F7768E), `$color-info` (purple).
- Surfaces: `$surface-page` (#16161E), `$surface-panel` (#1F2335), `$surface-panel-muted`, `$surface-panel-strong`.
- Spacing: `$space-0` … `$space-12`.
- Control sizes: sm 38px, md 46px, lg 54px.

## Common commands

No build, lint, test, or development commands are defined yet because the project has no `package.json` or tooling configuration. Once the build stack is chosen, update this section with the actual commands.

## Verification

Before claiming compatibility, run the equivalent of the reference release checks:

- Production build.
- Vue adapter smoke build against a consumer app that imports `gnexus-ui-kit/vue` components.
- Package smoke build from a packed tarball.
- Visual comparison between vanilla demo and Vue demo for any changed components.