ui-kit/MIGRATION.md

Migration — adopting @jason/ui-kit in existing apps

You don't rewrite anything. The kit is additive: install it, adopt it screen by screen, and delete local duplicates as you go. Most of your apps are already React + Vite + Tailwind, so this is low-friction.

Priority order (by payoff)

Best-fit apps first — they already have clsx/tailwind-merge and clean tokens, so they're the natural reference implementations:

1. delta and rack-planner — pilots. Prove the pattern here.
2. memer, codedump, fabdash, family-planner, mrp — React + Vite + Tailwind; direct swap.
3. qms, inven, mrp-qrcode — Next.js; same kit, add "use client" where needed.
4. relay — has MPM brand fonts already; align tokens, adopt AppShell + Table.
5. qrknit, goto — vanilla/PHP; use the kit for React islands or new marketing pages, or borrow the tokens as CSS variables.
6. pnger — Svelte; not a React consumer. Reuse tokens.ts values + the color/type/motion rules from DESIGN.md manually.

Steps per app

1. Install + npmrc

   cp node_modules/@jason/ui-kit/.npmrc.example .npmrc   # then set GITEA_NPM_TOKEN
   npm install @jason/ui-kit
   

2. Adopt the preset. Replace the app's hand-rolled color block in tailwind.config.js with presets: [require("@jason/ui-kit/preset")]. Add the kit's dist to content. Import @jason/ui-kit/styles.css in your entry.
3. Reconcile tokens. If the app had different colors, either map them to the shared tokens or override the CSS variables in your local globals.css for a per-app skin. Goal: one system, small per-app deltas.
4. Swap primitives. Replace local <button>/modal/input/table/toast with kit components. Delete the local copies. Standardize on cn() and toast().
5. Add depth + motion. Wrap page sections in FadeIn/Stagger; use SpotlightCard for feature/stat cards; AnimatedNumber on dashboard metrics.
6. Add the shell. Move dashboards onto AppShell + CommandPalette (⌘K).
7. Guard it. npx impeccable install in the app, run /impeccable init once, then /impeccable audit and /impeccable polish per screen. Add the detector to the app's CI (copy .gitea/workflows/ci.yml).

Rules of thumb

• Don't fork kit components in-app. If one needs changing, change it here and bump the version — every app benefits.
• If a pattern shows up in 2+ apps, promote it into src/blocks/.
• New apps: start from the kit on day one. No hand-rolled buttons ever again.

Path forward for NEW apps

Baseline stack going forward: **React + Vite + TypeScript + Tailwind (this preset)

• @jason/ui-kit + Impeccable**, backed by your usual Express/Prisma or Next + better-sqlite3, Dockerized for Unraid. sonner and motion are defaults, not per-app decisions.