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. Import @jason/ui-kit/fonts.css first when the app should use the shared fonts.
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 and theme. Wrap the app in ThemeProvider, place ThemeScript before app CSS when SSR is involved, and move dashboards onto responsive 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.