ui-kit/ADOPT.md

# 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, FormField, Input, Select, Checkbox, Switch, Tabs,
  Tooltip, Badge, Dialog, DropdownMenu, Table, Pagination, 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).
```