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

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

Use this path if you already migrated your application to the SICK 2025 theme while staying on Synergy 2 (using the dedicated SICK 2025 migration guide) and now want to upgrade to Synergy 3.

> This guide assumes that SICK 2025 is already correctly configured in your Synergy 2 setup.
> If you are still on SICK 2018, use **Path B** instead.

---

## Migration Checklist: Quick Overview

- [ ] Confirm that your Synergy 2 application already follows the SICK 2025 migration guide.
- [ ] 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))
- [ ] Verify that SICK 2025 remains active after the upgrade (themes, icons, font).
- [ ] Test your application visually and functionally in both light and dark mode.

---

## Starting Point: Already on SICK 2025

Before you start, you should already have completed:

- The theme migration from SICK 2018 to SICK 2025 on Synergy 2, following
  [Migration to SICK 2025 on Synergy 2](?path=/docs/migration-v2-sick-2018-to-v2-sick-2025--docs).
- Your application:
  - Uses the `sick2025_light.css` and `sick2025_dark.css` theme files.
  - Uses the `.syn-sick2025-light` and `.syn-sick2025-dark` classes for theme switching.
  - Loads the SICK Intl font.
  - Has SICK 2025 icons configured (via direct setup or `setupIcons('sick2025')`).

If any of these are not yet true, complete the SICK 2025 migration first.

---

## Migration Steps: Detailed Guide

### 1. Prepare and review current setup

- Confirm your current Synergy versions (2.x) for all `@synergy-design-system/*` packages.
- Confirm that SICK 2025 is visually working as expected.
- Skim the package-level breaking change guides to understand the scope of the Synergy 3 upgrade:
  - Components: [BREAKING_CHANGES](?path=/docs/packages-components-breaking-changes--docs)
  - Tokens: [BREAKING_CHANGES](?path=/docs/packages-tokens-breaking-changes--docs)

---

### 2. 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 you update all packages together to avoid version drift.

---

### 3. Apply package-level breaking changes

With SICK 2025 already in place, your main work for this path is to align with the Synergy 3 API and behavioral changes.

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

- Remove deprecated attributes and properties that were dropped in Synergy 3.
- Adjust to new defaults (e.g., numeric input strategies, popup behavior, navigation variants).
- Review any changes in configuration utilities or default settings.

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

- Verify that your theme imports still point to the correct SICK 2025 theme files.
- Check for deprecated or renamed tokens and adjust usages accordingly.

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

- Confirm that asset paths and CSS utilities still match your build setup.
- Apply any required changes to your bundler configuration.

Work through these changes systematically to keep the codebase compiling and tests passing.

---

### 4. Verify SICK 2025 configuration on Synergy 3

Because SICK 2025 is the primary theme in Synergy 3, your existing SICK 2025 setup should mostly carry over, but verify the following:

- **Theme files**: Your imports reference SICK 2025 theme files compatible with Synergy 3.
- **Theme classes**: You still use `.syn-sick2025-light` and `.syn-sick2025-dark` consistently.
- **Icons**: Any utilities you used on Synergy 2 (such as `setupIcons('sick2025')` or `setSystemIconLibrary`) are still called at the right time.
- **Fonts**: The SICK Intl font is loaded through your preferred method.

Adjust only if the breaking change documentation suggests changes.

---

### 5. Test and verify

- Test the application in all key scenarios and supported browsers.
- Pay attention to:
  - Controls with changed defaults or removed attributes.
  - Components that rely on the Popover API or similar platform features.
  - Visual differences due to adjustments in spacing, radii, and typography.
- Run your automated test suite and any visual regression checks.

---

## Migration: Breaking Changes & Details

This path is intentionally focused on the **upgrade from Synergy 2 to Synergy 3** with SICK 2025 already in place.
For detailed, package-specific changes, consult:

- 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)

Combine this path guide with those references to implement and review changes in your codebase.

---

## 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)
