Migration

Move from other UI kits to Velkin, or upgrade Velkin with MCP diffs.

Overview

Velkin is Lit custom elements with thin React and Vue wrappers. Most migrations are mapping habits — events, slots, and appearance props — not rewriting your product. Use this page as a checklist; use MCP get_velkin_component_docs for each component you port.

Mental model shifts

Habit elsewhere	In Velkin
`onChange` / `e.target.value`	`onVuChange` / `e.detail` (Vue: `v-model:*` or `@vu-change`)
`className` / utility CSS for look	`variant`, `color` or `tone`, `size`, `radius` — then tokens / `::part()`
`items={[…]}` config arrays	Compose host + item tags with named slots
Inline SVG icons	`VuIcon` / `vu-icon` with `ion:` ids
`pill` / capsule radius prop	`radius="full"`
Root package barrel imports	Subpaths only — `@velkin/react/button`

From React UI kits

Keep your app structure. Swap the control, wire Velkin events, and wrap once with VuThemeProvider.

Typical before → after for a controlled field and a button:

// Before (generic React kit)
<input value={email} onChange={(e) => setEmail(e.target.value)} />
<button className="btn-primary" onClick={save}>Save</button>

// After (Velkin)
import { VuInput } from "@velkin/react/input";
import { VuButton } from "@velkin/react/button";

<VuInput
  label="Email"
  value={email}
  onVuChange={(e) => setEmail(String(e.detail.value ?? ""))}
/>
<VuButton variant="solid" color="primary" onClick={save}>
  Save
</VuButton>

Next.js App Router: add "use client" on files that use onVu* or React state with Velkin.

Deeper mapping: Events, Slots, Appearance.

From copy-paste registries

If you currently paste component source into the repo (registry-style kits), Velkin is the opposite: install packages and import subpaths. You keep upgrades via npm instead of re-copying files.

Replace pasted primitives with @velkin/react/… (or Vue / Lit) imports
Move look-and-feel into Theming tokens and appearance props — not one-off utility classes on every call site
Keep product layout in your app; only swap the interactive primitives

npx create-velkin-app my-app --template next
# or wire an existing app: see /docs/installation

From HTML / design tokens only

Keep your CSS tokens where possible, then map brand seeds into VuThemeProvider. Prefer documented --vu-* variables and CSS parts over piercing shadow DOM.

Wrap the tree once — see Theming
Style chrome via Styling parts and tokens
Forms stay form-associated — see Forms

Upgrading Velkin

Bump packages on the same line — see Versions
Read Changelog for the releases you skipped
For each touched component, call MCP diff_component_migration, then get_velkin_component_docs (compact: true)
Run validate_component_usage / velkin_lint before merging agent-generated UI

Connect MCP first: MCP servers. Keep AGENTS.md in the repo so agents follow the same contract after upgrades.

Porting checklist

Theme provider at the root
Subpath imports only
Events use e.detail / Vue models
Named slots — no invented items props
Actions use color; surfaces use tone — not both on one element
Icons via ion: ids
Pro components: @velkin/*-pro + license — Pro license

Next steps