Fork: 0
root / vmk-ui-kit
Transfer to URL with SHA Find file
Newer
Older
vmk-ui-kit / CLAUDE.md
@Eugene Sukhodolskiy Eugene Sukhodolskiy 1 day ago 4 KB Scaffold vmk-ui-kit build system, docs, and compatibility contract
Raw Blame History

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