Migration guides

These guides help you move from legacy libraries or upgrade between major versions of design system packages. Pick the guide that matches your starting point.

---

Adopting @volvo-cars/css

If you’re coming from a different component library, start here:

• Migrating from VCC UI — Adoption strategy and decision framework for teams currently on VCC UI.
• Migrating from Material UI — Component mapping table and codemods for MUI to EDLS migration.

Package upgrades

Guides for upgrading between major versions of individual packages:

• CSS 0.x → 1.0 — Renamed classes, removed exports, and automated migration steps.
• react-icons 0.x → 1.0 — New icon API, BrandedIcon component, and codemods.
• react-accordion 1.x → 2.0 — Native <details>/<summary> API and renamed props.
• react-overlay → CSS dialog — Replacing react-overlay with the native <dialog> element.

Component-level guides

• VCC UI Text → CSS typography — Mapping old <Text variant="..."> names to the current typographic classes.

---

General migration advice

1. Migrate incrementally. @volvo-cars/css is designed to work alongside VCC UI and other libraries. You don’t need to migrate everything at once.
2. Enable linting. Add @volvo-cars/eslint-plugin-css with the deprecated-class rule to catch outdated class names automatically.
3. Use screenshot testing. Tools like Percy help you spot unintended visual regressions during migration.
4. One PR per component. Smaller, focused pull requests are easier to review and less risky to ship.

Need help? Reach out on Slack in #design-system-web.