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

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

Use this path if you want to benefit from Synergy 3 (APIs, fixes, and features) but **must keep the legacy SICK 2018 theme** for the time being.

> The SICK 2018 theme is planned for future deprecation.
> Use this path when you need more time before switching to SICK 2025.

---

## Migration Checklist: Quick Overview

- [ ] Confirm that your application is using the SICK 2018 theme on Synergy 2.
- [ ] Update all `@synergy-design-system/*` packages to their compatible Synergy 3 versions.
- [ ] Keep using the SICK 2018 theme files and classes where necessary.
- [ ] 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))
- [ ] Explicitly configure SICK 2018 theme imports to avoid accidentally switching to SICK 2025.
- [ ] Document that you plan to migrate to SICK 2025 later (Path B or C).

---

## Important Notes About SICK 2018 in Synergy 3

- The default theme behavior in Synergy 3 is oriented around SICK 2025.
- SICK 2018 remains available but is considered **legacy** and may be removed in a future major release.
- When using SICK 2018 on Synergy 3, you must:
  - Import the explicit SICK 2018 theme files.
  - Use the SICK 2018 theme classes in your theme switching logic.

See the tokens breaking change guide for details:

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

---

## Migration Steps: Detailed Guide

### 1. Prepare and review current setup

- Confirm your current Synergy 2 versions for all `@synergy-design-system/*` packages.
- Confirm that your application uses SICK 2018:
  - SICK 2018 theme files are imported.
  - Theme switching uses `.syn-sick2018-light` and `.syn-sick2018-dark`.
- Skim the package-level breaking changes for Synergy 3.

---

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

Update all packages together to avoid version mismatches.

---

### 3. Keep using SICK 2018 theme files

On Synergy 3, some generic theme entry points may now point to SICK 2025.
To **stay on SICK 2018**, make sure you:

- Import the explicit SICK 2018 theme files instead of any generic or default theme files.
- Continue to use the SICK 2018 theme classes for your theme switching logic.

For example (conceptually):

- Light theme: use a SICK 2018-specific light theme file and `.syn-sick2018-light`.
- Dark theme: use a SICK 2018-specific dark theme file and `.syn-sick2018-dark`.

See the tokens breaking change guide for the exact file names and recommendations:

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

---

### 4. Apply package-level breaking changes

Even though you keep SICK 2018, you still need to migrate to the Synergy 3 APIs and behaviors:

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

- Remove attributes that have been removed in Synergy 3.
- Adjust to changed defaults (e.g. numeric input strategies, popup behavior).
- Review any changes to default settings or configuration utilities.

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

- Confirm that your SICK 2018 theme imports are valid in Synergy 3.
- Check for deprecated or renamed tokens that may still be used in your CSS.

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

- Align asset paths and CSS utilities with Synergy 3.

Apply these changes systematically, running tests as you go.

---

### 5. Test and verify SICK 2018 on Synergy 3

- Test your application in both light and dark mode using SICK 2018.
- Pay attention to:
  - Any unintended switch to SICK 2025 assets or themes.
  - Components whose behavior changed between Synergy 2 and 3.
  - Layout changes that may result from new spacing or typography defaults.
- Run your automated tests and, if available, visual regression tests.

---

## Planning the Future Migration to SICK 2025

Staying on SICK 2018 on Synergy 3 is intended as a **temporary** solution.
To complete the brand migration later:

- Plan a follow-up migration from SICK 2018 to SICK 2025 on Synergy 3.
- When you are ready, you can:
  - Follow the same conceptual steps as in the SICK 2025 guide, but applied to your Synergy 3 setup.
  - Or, if you skipped the SICK 2025 migration on Synergy 2, follow the recommended **Path B** directly in a Synergy 3-compatible way.

---

## Migration: Breaking Changes & Details

This path focuses on **staying on the legacy SICK 2018 theme** while upgrading to Synergy 3.
For full details, use the technical package guides:

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

---

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