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):

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 published):

# .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)

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)

## 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).