From 4c1f2042e4cae04195d1bb4454203e9c90e634bd Mon Sep 17 00:00:00 2001 From: policyengine-bot Date: Sat, 9 May 2026 13:15:06 +0000 Subject: [PATCH] Document migration from @policyengine/design-system to @policyengine/ui-kit/legacy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add migration guide for repos transitioning from the deprecated @policyengine/design-system package to @policyengine/ui-kit/legacy. The /legacy subpath provides a drop-in replacement with identical API, allowing for seamless migration without code changes beyond import paths. Changes: - Add migration-from-design-system.md reference guide - Update ui-kit consumer skill to link to migration guide - Update design skill to mention ui-kit/legacy option for legacy projects - Clarify that @policyengine/design-system is deprecated 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../policyengine-design-skill/SKILL.md | 4 +- .../SKILL.md | 5 + .../migration-from-design-system.md | 112 ++++++++++++++++++ 3 files changed, 120 insertions(+), 1 deletion(-) create mode 100644 skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md diff --git a/skills/documentation/policyengine-design-skill/SKILL.md b/skills/documentation/policyengine-design-skill/SKILL.md index 13af36f..ac79bb2 100644 --- a/skills/documentation/policyengine-design-skill/SKILL.md +++ b/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 diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md index 8e7021b..87d7f08 100644 --- a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md +++ b/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 diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md b/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md new file mode 100644 index 0000000..ac53cf6 --- /dev/null +++ b/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