feat: git-installable (prepare build), ship design docs in package, add ADOPT.md for Claude Code

2026-07-16 00:45:42 -05:00
parent b75012525d
commit 78fa3f03c4
2 changed files with 85 additions and 2 deletions
@@ -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).
+```