# Migrating from Synergy 2.x (SICK 2018) → Synergy 3.x (SICK 2025)

This guide describes how to migrate an application from **Synergy 2.x with the SICK 2018 theme** to **Synergy 3.x with the SICK 2025 theme**.

This is the **recommended** end state for new and actively maintained applications.

> This guide focuses on the _user perspective_ and high-level sequence.
> For low-level, package-specific changes, always consult the respective `BREAKING_CHANGES.md` documents.

---

## Migration Checklist: Quick Overview

- [ ] Review the [Migration to SICK 2025 on Synergy 2](?path=/docs/migration-v2-sick-2018-to-v2-sick-2025--docs) to understand the theme and icon changes.
- [ ] Decide whether you want to migrate the theme **before** or **together with** the Synergy 3 upgrade.
- [ ] Update all `@synergy-design-system/*` packages to their compatible Synergy 3 versions.
- [ ] Apply all relevant breaking changes for:
  - [ ] `@synergy-design-system/components` ([BREAKING_CHANGES](?path=/docs/packages-components-breaking-changes--docs))
  - [ ] `@synergy-design-system/tokens` ([BREAKING_CHANGES](?path=/docs/packages-tokens-breaking-changes--docs))
  - [ ] `@synergy-design-system/assets` ([BREAKING_CHANGES](?path=/docs/packages-assets-breaking-changes--docs))
  - [ ] `@synergy-design-system/styles` ([BREAKING_CHANGES](?path=/docs/packages-styles-breaking-changes--docs))
- [ ] Enable the SICK 2025 theme (tokens, theme classes, icons, font).
- [ ] Test your application visually and functionally in both light and dark mode.

---

## Recommended Strategy

There are two practical ways to perform this migration:

1. **Two-step migration** (less risk, more control)
   - Step 1: Stay on Synergy 2 but migrate to SICK 2025 using the existing theme migration guide.
   - Step 2: Upgrade from Synergy 2 to Synergy 3 while already using SICK 2025.

2. **One-step migration** (fewer intermediate states, more changes at once)
   - Update all packages directly to Synergy 3.
   - Apply package breaking changes and enable SICK 2025 in one go.

This guide is written so it works for both strategies. When in doubt, prefer the **two-step** approach.

---

## Migration Steps: Detailed Guide

### 1. Prepare and review current setup

- Confirm your current versions of all `@synergy-design-system/*` packages.
- Confirm that your application is currently using the **SICK 2018** theme (legacy theme files and theme classes).
- Skim through the package-specific breaking change guides to understand the scope of changes:
  - Components: [BREAKING_CHANGES](?path=/docs/packages-components-breaking-changes--docs)
  - Tokens: [BREAKING_CHANGES](?path=/docs/packages-tokens-breaking-changes--docs)

---

### 2. (Optional but recommended) First migrate SICK 2018 → SICK 2025 on Synergy 2

If you prefer a **safer**, staged migration, first migrate your theme while staying on Synergy 2:

- Follow the guide [Migration to SICK 2025 on Synergy 2](?path=/docs/migration-v2-sick-2018-to-v2-sick-2025--docs).
- Verify:
  - New SICK 2025 icon assets are available and copied by your build.
  - `setSystemIconLibrary('sick2025')` (or `setupIcons('sick2025')`) is called as appropriate.
  - `sick2025_light.css` and `sick2025_dark.css` are imported.
  - Theme switching uses `.syn-sick2025-light` and `.syn-sick2025-dark`.
  - The **SICK Intl** font is loaded.

Once this is working, you are effectively in the same state as **Path C** and can continue as in that path when upgrading to Synergy 3.

---

### 3. Update Synergy packages to version 3

Update your dependencies to the compatible Synergy 3 versions:

- `@synergy-design-system/components` → latest **3.x**
- `@synergy-design-system/tokens` → latest **3.x**
- `@synergy-design-system/assets` → latest **2.x** (or the version recommended in the release notes)
- `@synergy-design-system/styles` → latest **2.x** (or the version recommended in the release notes)

Make sure all `@synergy-design-system/*` packages are updated together to avoid version mismatches.

---

### 4. Apply package-level breaking changes

Go through the breaking change guides and adjust your code accordingly.
Focus especially on:

-- **Components** ([BREAKING_CHANGES](?path=/docs/packages-components-breaking-changes--docs))

- Removed or renamed attributes (e.g. deprecated attributes on dropdowns, tooltips, popups, etc.).
- Changes in defaults (e.g. numeric input behavior).
- Updated settings utilities.

-- **Tokens** ([BREAKING_CHANGES](?path=/docs/packages-tokens-breaking-changes--docs))

- New default theme behavior (SICK 2025 becoming the default for certain theme imports).
- The planned deprecation of legacy tokens (e.g. page background tokens).

-- **Assets & Styles** ([BREAKING_CHANGES](?path=/docs/packages-assets-breaking-changes--docs), [BREAKING_CHANGES](?path=/docs/packages-styles-breaking-changes--docs))

- Any changes in asset paths, build configuration, or CSS utility classes.

Handle these changes package by package so that your code compiles and your tests pass.

---

### 5. Ensure SICK 2025 is active on Synergy 3

On Synergy 3, SICK 2025 becomes the **primary** theme. To ensure your application is correctly configured:

- Confirm that your theme imports reference the SICK 2025 theme files.
- Confirm that your runtime theme switching uses `.syn-sick2025-light` and `.syn-sick2025-dark`.
- Confirm that your icon setup uses the SICK 2025 icon library.
- Confirm that the SICK Intl font is loaded (via fonts package, CDN, or local hosting).

If you used the two-step strategy and already migrated the theme on Synergy 2, this step should mostly be a verification.

---

### 6. Test and verify

- Manually test key user flows in your application in both light and dark mode.
- Pay special attention to:
  - Layout changes due to new spacing, radii, and typography.
  - Numeric inputs and other controls with changed defaults.
  - Popovers, tooltips, dropdowns, and navigation components after API cleanups.
- Run your automated tests and visual regression tests (if available).

---

## Migration: Breaking Changes & Details

This path-level guide is intentionally high level.
For exact API changes, always work with the package-specific documents:

- Components: [@synergy-design-system/components BREAKING CHANGES](?path=/docs/packages-components-breaking-changes--docs)
- Tokens: [@synergy-design-system/tokens BREAKING CHANGES](?path=/docs/packages-tokens-breaking-changes--docs)
- Assets: [@synergy-design-system/assets BREAKING CHANGES](?path=/docs/packages-assets-breaking-changes--docs)
- Styles: [@synergy-design-system/styles BREAKING CHANGES](?path=/docs/packages-styles-breaking-changes--docs)

You can combine this path guide with those documents to form a project-specific migration plan.

---

## References & Further Reading

- Overall migration paths overview: [Synergy Migration Overview](?path=/docs/migration--docs)
- SICK 2025 theme migration for Synergy 2: [Migration to SICK 2025 on Synergy 2](?path=/docs/migration-v2-sick-2018-to-v2-sick-2025--docs)
- Additional Synergy documentation: [Synergy Docs](?path=/docs/welcome--docs)
