Document migration from @policyengine/design-system to @policyengine/ui-kit/legacy

skills/documentation/policyengine-design-skill/SKILL.md

@@ -256,8 +256,9 @@ https://raw.githubusercontent.com/PolicyEngine/policyengine-app-v2/main/app/publ
 |-------------|-------------|------------|
 | **Standalone tool** | `@import "@policyengine/ui-kit/theme.css"` | Google Fonts: Inter |
 | **app-v2** | `import { colors } from '@/designTokens'` | Built-in (Mantine + Inter) |
-| **Python chart** | Hardcode or load `tokens.json` from `@policyengine/design-system` | Inter for Plotly |
+| **Python chart** | Hardcode hex values with CSS var comments | Inter for Plotly |
 | **Blog HTML** | Hardcode from token values | Google Fonts: Inter |
+| **Legacy projects** | `@policyengine/ui-kit/legacy` (drop-in replacement for deprecated `@policyengine/design-system`) | Google Fonts: Inter |
 
 ## Accessibility
 
@@ -269,6 +270,7 @@ https://raw.githubusercontent.com/PolicyEngine/policyengine-app-v2/main/app/publ
 
 ## Related skills
 
+- `policyengine-ui-kit-consumer-skill` — Modern ui-kit setup and migration from `@policyengine/design-system`
 - `policyengine-interactive-tools-skill` — Building standalone tools that use these tokens
 - `policyengine-vercel-deployment-skill` — Deploying standalone tools
 - `policyengine-app-skill` — app-v2 development

skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md

@@ -244,3 +244,8 @@ After the two-line import, these are available:
 - `policyengine-tailwind-shadcn-skill` — `@theme` namespace mechanics, SVG var() usage
 - `policyengine-interactive-tools-skill` — Full tool scaffolding checklist
 - `policyengine-vercel-deployment-skill` — Deploying consumer apps
+
+## Related References
+
+- `migration-from-design-system.md` — Migrating from deprecated `@policyengine/design-system` to `@policyengine/ui-kit/legacy`
+- `migration-from-broken-setup.md` — Fixing broken Tailwind + ui-kit configurations

skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md

@@ -0,0 +1,112 @@
+# Migrating from @policyengine/design-system to @policyengine/ui-kit
+
+Guide for migrating repositories from the deprecated `@policyengine/design-system` package to `@policyengine/ui-kit/legacy`.
+
+## Why Migrate
+
+- `@policyengine/design-system` is deprecated and being phased out
+- `@policyengine/ui-kit` is the canonical PolicyEngine design system going forward
+- The `/legacy` subpath provides a drop-in replacement with identical API
+
+## Migration Steps
+
+### 1. Update package.json
+
+Replace the design-system dependency with ui-kit:
+
+```bash
+# Remove old package
+bun remove @policyengine/design-system
+
+# Add new package
+bun add @policyengine/ui-kit
+```
+
+### 2. Update imports
+
+Replace all imports from `@policyengine/design-system` with `@policyengine/ui-kit/legacy`.
+
+This is a pure import path change - no code changes needed:
+
+```tsx
+// Before
+import { colors, spacing, typography } from '@policyengine/design-system';
+
+// After
+import { colors, spacing, typography } from '@policyengine/ui-kit/legacy';
+```
+
+### 3. Search and replace
+
+Use find-and-replace across your codebase:
+
+```bash
+# Find all occurrences
+grep -r "@policyengine/design-system" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"
+
+# Or use your editor's find-and-replace:
+# Find: @policyengine/design-system
+# Replace: @policyengine/ui-kit/legacy
+```
+
+### 4. Verify the build
+
+```bash
+bun run build
+```
+
+The migration should be transparent - no type errors, no runtime changes.
+
+## Why `/legacy`?
+
+The `/legacy` subpath in ui-kit mirrors the old design-system API exactly, allowing for a seamless migration without code changes.
+
+Once migrated to `/legacy`, you can optionally migrate to the modern ui-kit patterns (Tailwind v4, CSS custom properties) when ready. See the main `policyengine-ui-kit-consumer-skill` for modern setup.
+
+## What Stays the Same
+
+After migration to `/legacy`:
+- All exported values (colors, spacing, typography, etc.) remain identical
+- TypeScript types remain compatible
+- Runtime behavior is unchanged
+- This is purely a dependency replacement
+
+## Common Scenarios
+
+### Monorepo with local design-system package
+
+If your repo has `packages/design-system/` as a local package:
+
+1. Keep the local package if needed for legacy code
+2. Migrate new code to `@policyengine/ui-kit/legacy`
+3. Eventually remove the local package when all code is migrated
+
+### Re-export layers
+
+If you have re-export convenience layers like:
+
+```tsx
+// app/src/designTokens/index.ts
+export * from '@policyengine/design-system';
+```
+
+Update them to:
+
+```tsx
+// app/src/designTokens/index.ts
+export * from '@policyengine/ui-kit/legacy';
+```
+
+This allows the rest of your codebase to keep using the convenience import (`@/designTokens`).
+
+## Next Steps
+
+After migrating to `/legacy`, consider:
+
+1. **Stay on `/legacy`** - Perfectly fine for stable codebases. No urgency to migrate.
+2. **Migrate to modern ui-kit** - Use Tailwind v4 classes and CSS custom properties. See `policyengine-ui-kit-consumer-skill` for setup.
+
+## Related Skills
+
+- `policyengine-ui-kit-consumer-skill` — Modern ui-kit setup with Tailwind v4
+- `policyengine-design-skill` — Token reference and usage guidelines