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**
   ```bash
   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.