From f080264580f33fc3cab62ee820b402adcef5156a Mon Sep 17 00:00:00 2001 From: policyengine-bot Date: Sat, 9 May 2026 13:23:01 +0000 Subject: [PATCH] Document migration from @policyengine/design-system to ui-kit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive migration guide covering the /legacy subpath introduced in ui-kit 0.8.0. This path allows gradual migration from the deprecated design-system package with minimal code changes. Learned from uk-land-value-tax PR #12 migration work. Changes: - New migration-from-design-system.md reference guide - Updated skill triggers to include design-system migration keywords - Documents both legacy subpath (quick) and modern (recommended) paths - Includes specific example from uk-land-value-tax dashboard 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../SKILL.md | 11 +- .../migration-from-design-system.md | 232 ++++++++++++++++++ 2 files changed, 241 insertions(+), 2 deletions(-) create mode 100644 skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md diff --git a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md index 8e7021b..c5f8e35 100644 --- a/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md +++ b/skills/frontend/policyengine-ui-kit-consumer-skill/SKILL.md @@ -4,10 +4,12 @@ description: | This skill should be used when setting up a new project that uses @policyengine/ui-kit, debugging CSS or styling issues in a consumer app, or when Tailwind utility classes are not being generated. Also use when creating globals.css, configuring PostCSS, or troubleshooting - "no styles", "no spacing", or "no layout" problems. + "no styles", "no spacing", or "no layout" problems. Also use when migrating from the deprecated + @policyengine/design-system package. Triggers: "ui-kit import", "globals.css setup", "Tailwind not working", "styles not applying", "utility classes missing", "setup ui-kit", "PostCSS config", "no styling", "CSS broken", - "import ui-kit", "theme.css", "no layout", "no spacing", "@tailwindcss/postcss" + "import ui-kit", "theme.css", "no layout", "no spacing", "@tailwindcss/postcss", + "migrate from design-system", "design-system to ui-kit", "/legacy subpath" --- # Consuming @policyengine/ui-kit @@ -244,3 +246,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 Guides + +- `references/migration-from-design-system.md` — Migrate from deprecated @policyengine/design-system to ui-kit +- `references/migration-from-broken-setup.md` — Fix 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..1cdbf48 --- /dev/null +++ b/skills/frontend/policyengine-ui-kit-consumer-skill/references/migration-from-design-system.md @@ -0,0 +1,232 @@ +# Migrating from @policyengine/design-system to @policyengine/ui-kit + +Guide for migrating projects that use the deprecated `@policyengine/design-system` package to the canonical `@policyengine/ui-kit`. + +## Background + +`@policyengine/design-system` is deprecated. All PolicyEngine projects should use `@policyengine/ui-kit` as the canonical design system (per `PolicyEngine/CLAUDE.md`). + +For projects that need a gradual migration, ui-kit 0.8.0+ provides a `/legacy` subpath that mirrors the design-system API exactly. + +## Migration Paths + +There are two migration strategies: + +### Path A: Legacy Subpath (Quick Migration) + +Use this for projects that need immediate migration with minimal changes. + +**What changes:** +- Import paths only (source imports and CSS imports) +- Package dependency in `package.json` +- No code changes needed + +**Migration steps:** + +1. **Update package.json** + ```diff + - "@policyengine/design-system": "^X.Y.Z" + + "@policyengine/ui-kit": "^0.8.0" + ``` + +2. **Update source imports** + ```diff + - import { colors } from '@policyengine/design-system/tokens/colors' + + import { colors } from '@policyengine/ui-kit/legacy/tokens/colors' + ``` + +3. **Update CSS imports** + + The legacy subpath does NOT re-export the CSS variables file. You need to inline the CSS custom properties that your app uses. + + **Before:** + ```css + @import "@policyengine/design-system/tokens.css"; + ``` + + **After:** + ```css + /* Inline the relevant CSS custom properties */ + :root { + --pe-color-teal-50: #e6fffa; + --pe-color-teal-100: #b2f5ea; + --pe-color-teal-500: #319795; + /* ... other variables your app uses ... */ + } + ``` + + Check what variables your app actually uses (grep for `var(--pe-`) and only inline those. + +4. **Update lockfile** (if switching to bun) + ```bash + rm package-lock.json + bun install + ``` + +5. **Test** + ```bash + bun install + bun run build + ``` + +**Why inline CSS?** + +`@policyengine/ui-kit/legacy` provides the JavaScript exports (color objects, spacing, etc.) but not the CSS file. This is because: +- ui-kit uses the new `theme.css` with shadcn-style variable names (`--primary`, `--background`) +- The old `--pe-color-*` naming is legacy and shouldn't be in the main theme +- Inlining forces you to be explicit about which tokens you depend on + +### Path B: Full Modern Migration (Recommended for New Work) + +Use this for new projects or when doing significant refactoring. + +**What changes:** +- Import paths become `@policyengine/ui-kit/theme.css` +- Variable names change to shadcn-style (`--primary` instead of `--pe-color-teal-500`) +- Setup requires Tailwind v4 + PostCSS config + +**Migration steps:** + +See the main `policyengine-ui-kit-consumer-skill` SKILL.md for full setup instructions. + +**Quick summary:** +1. Install: `bun add @policyengine/ui-kit` + `bun add -D @tailwindcss/postcss postcss` +2. Create `postcss.config.mjs` with `@tailwindcss/postcss` +3. Create `globals.css`: + ```css + @import "tailwindcss"; + @import "@policyengine/ui-kit/theme.css"; + ``` +4. Use Tailwind classes (`bg-primary`, `text-teal-500`) instead of CSS vars + +## When to Use Which Path + +| Scenario | Recommended Path | Reason | +|----------|-----------------|--------| +| Standalone tool with minimal CSS | Legacy subpath | Quick migration, minimal changes | +| Tool in active development | Modern migration | Future-proof, Tailwind utilities | +| Quick fix needed | Legacy subpath | Unblocks immediately | +| New greenfield project | Modern migration | Start with best practices | +| Large refactor planned | Modern migration | Do it right once | + +## Common Issues + +### Issue: CSS variables not working after migration + +**Symptom:** `var(--pe-color-teal-500)` returns nothing + +**Fix:** The legacy subpath doesn't export the CSS file. You must inline the variables you use: + +```css +:root { + --pe-color-teal-500: #319795; + /* ... other vars ... */ +} +``` + +### Issue: Module not found '@policyengine/ui-kit/legacy' + +**Fix:** Ensure you're using ui-kit 0.8.0 or later: + +```bash +bun add @policyengine/ui-kit@^0.8.0 +``` + +### Issue: Import works but types are wrong + +**Fix:** The legacy subpath preserves the exact types from design-system. If types are wrong, check: +1. TypeScript is using the right version (`bun install`) +2. Editor is using workspace TypeScript (Cmd+Shift+P > "Select TypeScript Version") + +## Examples + +### Example 1: uk-land-value-tax (Standalone Dashboard) + +**Before:** +```tsx +// src/components/BaselineTab.jsx +import { colors } from '@policyengine/design-system/tokens/colors'; +``` + +```css +/* app/globals.css */ +@import "@policyengine/design-system/tokens.css"; +``` + +```json +// package.json +{ + "dependencies": { + "@policyengine/design-system": "^1.0.0" + } +} +``` + +**After (legacy path):** +```tsx +// src/components/BaselineTab.jsx +import { colors } from '@policyengine/ui-kit/legacy/tokens/colors'; +``` + +```css +/* app/globals.css */ +:root { + --pe-color-teal-50: #e6fffa; + --pe-color-teal-100: #b2f5ea; + --pe-color-teal-200: #81e6d9; + --pe-color-teal-300: #4fd1c5; + --pe-color-teal-400: #38b2ac; + --pe-color-teal-500: #319795; + --pe-color-teal-600: #2c7a7b; + --pe-color-teal-700: #285e61; + --pe-color-teal-800: #234e52; + --pe-color-teal-900: #1d4044; + + --pe-color-gray-50: #f7fafc; + --pe-color-gray-100: #edf2f7; + --pe-color-gray-200: #e2e8f0; + --pe-color-gray-300: #cbd5e0; + --pe-color-gray-400: #a0aec0; + --pe-color-gray-500: #718096; + --pe-color-gray-600: #4a5568; + --pe-color-gray-700: #2d3748; + --pe-color-gray-800: #1a202c; + --pe-color-gray-900: #171923; + + --pe-color-blue-50: #ebf8ff; + --pe-color-blue-100: #bee3f8; + --pe-color-blue-200: #90cdf4; + --pe-color-blue-300: #63b3ed; + --pe-color-blue-400: #4299e1; + --pe-color-blue-500: #3182ce; + --pe-color-blue-600: #2b6cb0; + --pe-color-blue-700: #2c5282; + --pe-color-blue-800: #2a4365; + --pe-color-blue-900: #1a365d; + + --pe-font-family-sans: Inter, system-ui, -apple-system, sans-serif; + --pe-font-size-xs: 0.75rem; + --pe-font-size-sm: 0.875rem; + --pe-font-size-base: 1rem; + --pe-font-size-lg: 1.125rem; + --pe-font-size-xl: 1.25rem; + --pe-font-size-2xl: 1.5rem; + --pe-font-size-3xl: 1.875rem; + --pe-font-size-4xl: 2.25rem; +} +``` + +```json +// package.json +{ + "dependencies": { + "@policyengine/ui-kit": "^0.8.0" + } +} +``` + +## Related Skills + +- `policyengine-ui-kit-consumer-skill` — Full modern ui-kit setup +- `policyengine-design-skill` — Design token reference +- `policyengine-tailwind-shadcn-skill` — Tailwind v4 mechanics