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 Add Divider, Accordion, Stepper and FileAttachment components
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

  • npm run build — production build (styles, scripts, Vue adapter, demo HTML).
  • npm run dev / npm start — BrowserSync dev server on http://localhost:3000.
  • npm run test:e2e — run the Playwright test suite.
  • npx playwright test tests/figma-match.spec.js — run Figma visual-regression comparisons.
  • npm run test:vue-adapter — build the Vue adapter and the example Vue consumer app.

Figma frames exported to figma design parts/frames/*.png are the visual source of truth. Baselines live in tests/figma-baselines/ and are compared against demo/figma/*.html screenshots in tests/figma-match.spec.js.

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.