76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
|
# 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).
|
||
|
|
```
|