From 6736e834a4d58443294be9ce5ec182664fd70528 Mon Sep 17 00:00:00 2001 From: policyengine-bot Date: Sat, 9 May 2026 13:17:24 +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 guidance for repos transitioning from deprecated @policyengine/design-system to the /legacy subpath in ui-kit. The /legacy export in ui-kit 0.8.0+ provides API compatibility with design-system, enabling pure import-path rename migrations. This pattern was validated in PolicyEngine/snap-bbce-repeal#5. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../policyengine-design-skill/SKILL.md | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/skills/documentation/policyengine-design-skill/SKILL.md b/skills/documentation/policyengine-design-skill/SKILL.md index 13af36f..b1966bf 100644 --- a/skills/documentation/policyengine-design-skill/SKILL.md +++ b/skills/documentation/policyengine-design-skill/SKILL.md @@ -44,6 +44,29 @@ The theme CSS has three layers: 2. **`@theme inline`** — Bridges `:root` vars to Tailwind utilities (`bg-primary`, `text-foreground`) 3. **`@theme`** — Brand palette (`bg-teal-500`, `text-gray-600`), font sizes, spacing, breakpoints +## Migrating from @policyengine/design-system + +**The `@policyengine/design-system` package is deprecated.** All projects should migrate to `@policyengine/ui-kit`. + +For projects using the old design-system's component API (not just CSS tokens), use the `/legacy` subpath as a drop-in replacement: + +```bash +# Replace +import { Button, Input } from "@policyengine/design-system"; + +# With +import { Button, Input } from "@policyengine/ui-kit/legacy"; +``` + +The `/legacy` export in ui-kit 0.8.0+ mirrors design-system's API exactly. This is a pure import-path rename — no code changes required beyond the import statements. + +**Migration steps:** +1. Update `package.json`: Replace `@policyengine/design-system` with `@policyengine/ui-kit` +2. Find-and-replace all imports: `@policyengine/design-system` → `@policyengine/ui-kit/legacy` +3. No other code changes needed + +**Note:** The `/legacy` subpath is transitional. New code should use ui-kit's modern components directly (see `policyengine-ui-kit-consumer-skill`). The legacy path exists to enable gradual migration without breaking existing projects. + ## Colors ### Primary — teal