From 78fa3f03c43cdb69c7bc992d622ca4063dc323ae Mon Sep 17 00:00:00 2001
From: Jason <jason@messagepoint.tv>
Date: Thu, 16 Jul 2026 00:45:42 -0500
Subject: [PATCH] feat: git-installable (prepare build), ship design docs in
 package, add ADOPT.md for Claude Code

---
 ADOPT.md     | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 package.json | 12 +++++++--
 2 files changed, 85 insertions(+), 2 deletions(-)
 create mode 100755 ADOPT.md

diff --git a/ADOPT.md b/ADOPT.md
new file mode 100755
index 0000000..1bdae24
--- /dev/null
+++ b/ADOPT.md
@@ -0,0 +1,75 @@
+# Adopting @jason/ui-kit with Claude Code
+
+Copy this file into a repo you're upgrading (or paste its "Agent context" block into
+that repo's `CLAUDE.md`). It gives Claude Code the two things it needs: **the package**
+(to import) and **the design context** (to plan the upgrade well).
+
+---
+
+## 1. Give Claude Code the package
+
+Pick ONE install path. Run it in the forked repo before starting Claude Code.
+
+**Option A — straight from git (no registry setup, recommended to start):**
+```bash
+npm install "git+https://git.alwisp.com/jason/ui-kit.git"
+# builds automatically via the package's `prepare` script
+```
+
+**Option B — from the Gitea npm registry (once you've `npm publish`ed):**
+```bash
+# .npmrc in the repo:
+#   @jason:registry=https://git.alwisp.com/api/packages/jason/npm/
+#   //git.alwisp.com/api/packages/jason/npm/:_authToken=${GITEA_NPM_TOKEN}
+export GITEA_NPM_TOKEN=<gitea token with read:package scope>
+npm install @jason/ui-kit
+```
+
+Either way the package lands in `node_modules/@jason/ui-kit/`, including its
+`DESIGN.md`, `PRODUCT.md`, and `MIGRATION.md` — so Claude Code can read the design
+system directly.
+
+## 2. Give Claude Code the design skill (optional but recommended)
+
+```bash
+npx impeccable install     # installs the /impeccable skill + anti-slop detector into .claude
+```
+Then inside Claude Code run `/impeccable init` once. Now Claude has `/impeccable
+audit`, `/polish`, `/animate`, etc., and will avoid AI-slop patterns.
+
+## 3. Plan the upgrade
+
+Start Claude Code in the repo (`claude`) and paste:
+
+> Read `node_modules/@jason/ui-kit/DESIGN.md` and `node_modules/@jason/ui-kit/MIGRATION.md`,
+> and `node_modules/@jason/ui-kit/README.md` for the API. Then inventory this app's UI:
+> its Tailwind config, global CSS, and every hand-rolled button, input, modal, dropdown,
+> table, toast, and layout. Produce a **migration plan** (don't change code yet) that:
+> 1. swaps our Tailwind color block for `presets: [require("@jason/ui-kit/preset")]` and imports `@jason/ui-kit/styles.css`;
+> 2. lists each local component to replace with a kit component, file by file;
+> 3. flags any tokens/colors we must reconcile or override;
+> 4. identifies where to add depth + motion (FadeIn/Stagger/SpotlightCard/AnimatedNumber) and the AppShell + ⌘K CommandPalette;
+> 5. orders the work smallest-blast-radius first.
+> Present the plan for approval before editing anything.
+
+After approval: `/impeccable audit` per screen as you convert, `/impeccable polish`
+before opening the PR back to the upstream repo.
+
+---
+
+## Agent context (paste into the fork's CLAUDE.md)
+
+```md
+## UI: @jason/ui-kit
+This app uses the shared design foundation `@jason/ui-kit`.
+- Design system + rules: `node_modules/@jason/ui-kit/DESIGN.md`
+- API/exports: `node_modules/@jason/ui-kit/README.md`
+- Tailwind: use `presets: [require("@jason/ui-kit/preset")]`; import `@jason/ui-kit/styles.css` once at entry.
+- Prefer kit components (Button, Card, Input, Badge, Dialog, DropdownMenu, Table, Toaster,
+  AppShell, CommandPalette, Hero, FeatureGrid, Pricing) over hand-rolled ones. Never fork a
+  kit component in-app — request the change upstream instead.
+- Use `cn()` for conditional classes and `toast()` for notifications.
+- Follow DESIGN.md: tinted neutrals, layered shadows, ease-out motion (no bounce),
+  focus-visible rings, no cards-in-cards, no gray text on colored fills.
+- Motion via FadeIn/Stagger; respect prefers-reduced-motion (kit already does).
+```
diff --git a/package.json b/package.json
index 0eeddef..bb1a306 100755
--- a/package.json
+++ b/package.json
@@ -8,7 +8,15 @@
   "repository": { "type": "git", "url": "https://git.alwisp.com/jason/ui-kit.git" },
   "publishConfig": { "registry": "https://git.alwisp.com/api/packages/jason/npm/" },
   "sideEffects": ["**/*.css"],
-  "files": ["dist", "tailwind-preset.cjs", "src/styles/globals.css"],
+  "files": [
+    "dist",
+    "tailwind-preset.cjs",
+    "src/styles/globals.css",
+    "DESIGN.md",
+    "PRODUCT.md",
+    "MIGRATION.md",
+    "README.md"
+  ],
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
     "./preset": "./tailwind-preset.cjs",
@@ -22,7 +30,7 @@
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "design:detect": "impeccable detect src/",
-    "prepublishOnly": "npm run build"
+    "prepare": "npm run build"
   },
   "dependencies": {
     "@radix-ui/react-dialog": "^1.1.4",