feat: initial @jason/ui-kit — tokens, preset, components, motion, blocks, Impeccable

2026-07-16 00:36:53 -05:00
commit b75012525d
36 changed files with 1324 additions and 0 deletions
@@ -0,0 +1,52 @@
+# 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.
+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.