@synergy-design-system/metadata 1.0.0 → 3.0.1

package/data/layers/full/setup/setup:synergy-migrations/migration/index.md

@@ -0,0 +1,57 @@
+# Synergy Migration Overview
+
+This overview describes the main migration paths from Synergy version 2 to Synergy version 3 and the SICK 2025 theme.
+
+If you are unsure which guide to follow, start here and choose the path that matches your current setup and your target.
+
+---
+
+## Migration Paths
+
+### Path A: Stay on Synergy 2, move from SICK 2018 to SICK 2025
+
+- **Current state:** Synergy **2.x**, theme **SICK 2018**
+- **Target state:** Synergy **2.x**, theme **SICK 2025**
+- **Use when:** You want the new SICK 2025 brand look but are not ready to upgrade to Synergy 3 yet.
+- **Guide:** See [Path A: Upgrade from Synergy 2 (SICK 2018) to Synergy 2 (SICK 2025)](?path=/docs/migration-v2-sick-2018-to-v2-sick-2025--docs).
+
+---
+
+### Path B: Synergy 2.x + SICK 2018 → Synergy 3.x + SICK 2025 (recommended)
+
+- **Current state:** Synergy **2.x**, theme **SICK 2018**
+- **Target state:** Synergy **3.x**, theme **SICK 2025**
+- **Use when:** You want to fully adopt Synergy 3 and the new SICK 2025 brand.
+- **Guide:** See [Path B: Upgrade from Synergy 2 (SICK 2018) to Synergy 3 (SICK 2025)](?path=/docs/migration-v2-sick-2018-to-v3-sick-2025--docs).
+
+---
+
+### Path C: Synergy 2.x + SICK 2025 → Synergy 3.x + SICK 2025
+
+- **Current state:** Synergy **2.x**, theme **SICK 2025** (already migrated using the v2 guide)
+- **Target state:** Synergy **3.x**, theme **SICK 2025**
+- **Use when:** You already use SICK 2025 on Synergy 2 and now want to upgrade to Synergy 3.
+- **Guide:** See [Path C: Upgrade from Synergy 2 to Synergy 3 with SICK 2025](?path=/docs/migration-v2-sick-2025-to-v3-sick-2025--docs).
+
+---
+
+### Path D: Synergy 2.x + SICK 2018 → Synergy 3.x + SICK 2018 (stay on old theme)
+
+- **Current state:** Synergy **2.x**, theme **SICK 2018**
+- **Target state:** Synergy **3.x**, theme **SICK 2018**
+- **Use when:** You want to benefit from Synergy 3, but must keep the SICK 2018 theme for now.
+- **Guide:** See [Path D: Upgrade from Synergy 2 to Synergy 3 while staying on SICK 2018](?path=/docs/migration-v2-sick-2018-to-v3-sick-2018--docs).
+
+---
+
+## Package-Level Technical Details
+
+Each path focuses on the _user perspective_ and high-level steps.
+For package-specific breaking changes and code changes, always consult the dedicated 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)
+
+Use these together with the path-specific guides to plan and execute your migration.

package/data/layers/full/setup/setup:synergy-migrations/migration/v2-2018-to-v2-2025.md

@@ -0,0 +1,481 @@
+# Migrating from Synergy 2.x (SICK 2018) → Synergy 2.x (SICK 2025)
+
+This guide details all steps that are needed to migrate from the SICK 2018 to the new SICK 2025 theme.
+This guide assumes you are using Synergy version 2.
+Synergy version 3 will apply most manual steps outlined in this guide automatically.
+
+---
+
+## Migration Checklist: Quick Overview
+
+- [ ] Update `@synergy-design-system/components` to the latest stable 2.x version (e.g. `"^2.0.0"`)
+- [ ] Update `@synergy-design-system/tokens` to the latest stable 2.x version (e.g. `"^2.0.0"`)
+- [ ] Update `@synergy-design-system/assets` to the latest stable 1.x version (e.g. `"^1.0.0"`)
+- [ ] Update `@synergy-design-system/styles` to the latest stable 1.x version (e.g. `"^1.0.0"`)
+- [ ] Call `setSystemIconLibrary('sick2025')` before rendering components
+- [ ] Copy new icons to `/assets/icons/`
+- [ ] Import new CSS themes (`sick2025_light.css`, `sick2025_dark.css`)
+- [ ] Update theme switching logic to use new class names
+- [ ] Add SICK Intl font (via `@synergy-design-system/fonts`, CDN, or brand portal)
+
+---
+
+## Release Highlights: SICK 2025
+
+- **Brand appearance:** Updated colors, roundings, and overall look
+- **Fonts:** New SICK Intl font replaces Open Sans
+- **Icon library:** New outline and filled icons, new naming
+- **CSS tokens/themes:** New theme files and class names
+
+---
+
+## Migration Steps: Detailed Guide
+
+### 1. Update Synergy packages
+
+Use your package manager to update all `@synergy-design-system/*` packages.
+Also make sure to install `@synergy-design-system/fonts` for the new `SICK Intl` font.
+
+---
+
+### 2. Set the system icon library
+
+Call `setSystemIconLibrary('sick2025')` before rendering any Synergy components.
+
+**Example:**
+
+```js
+import { setSystemIconLibrary } from "@synergy-design-system/components";
+setSystemIconLibrary("sick2025");
+```
+
+---
+
+### 3. Copy new icons to your build output
+
+Use your bundler (e.g., Vite) to copy icons from `@synergy-design-system/assets` to `/assets/icons/`.
+
+**Example (Vite):**
+
+```js
+viteStaticCopy({
+  targets: [
+    {
+      src: "node_modules/@synergy-design-system/assets/src/sick2025/outline/*",
+      dest: "./assets/icons/",
+    },
+    {
+      src: "node_modules/@synergy-design-system/assets/src/sick2025/fill/*",
+      dest: "./assets/icons/",
+    },
+  ],
+});
+```
+
+---
+
+### 4. Import new CSS themes
+
+Replace old theme imports with:
+
+```js
+import "@synergy-design-system/tokens/themes/sick2025_light.css";
+import "@synergy-design-system/tokens/themes/sick2025_dark.css";
+```
+
+---
+
+### 5. Update theme switching logic
+
+Use new class names: `syn-sick2025-light` and `syn-sick2025-dark`.
+
+**Example:**
+
+```js
+// Theme switcher
+const { body } = document;
+if (body.classList.contains("syn-sick2025-dark")) {
+  body.classList.remove("syn-sick2025-dark");
+  body.classList.add("syn-sick2025-light");
+} else {
+  body.classList.remove("syn-sick2025-light");
+  body.classList.add("syn-sick2025-dark");
+}
+```
+
+---
+
+### 6. Add the SICK Intl font
+
+Use one of the following options:
+
+**Synergy fonts package (recommended):**
+
+```javascript
+import "@synergy-design-system/fonts";
+```
+
+**SICK CDN:**
+
+```css
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 400;
+  src: url("https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Regular.woff2")
+    format("woff2");
+}
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 600;
+  src: url("https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Semibold.woff2")
+    format("woff2");
+}
+```
+
+**Brand portal:** Download and host the font yourself, then use a local path in `@font-face`.
+
+---
+
+## Migration: Breaking Changes & Details
+
+### Breaking Changes: Icons
+
+- **System icon library:** Synergy now ships two system icon libraries for compatibility. Use `setSystemIconLibrary` to switch to the new set.
+- **New SICK 2025 icons:** Outline and filled icons, new naming. Use `<syn-icon name="home">` and `<syn-icon name="home_fill">`.
+- **Migration utilities:** Use `setupIcons("sick2025")` for easy migration, or `migrateIconName` for custom setups.
+
+### Breaking Changes: Tokens & Themes
+
+- New theme files: `sick2025_light.css`, `sick2025_dark.css`
+- New theme class names: `.syn-sick2025-light`, `.syn-sick2025-dark`
+- Significant visual changes: colors, roundings, font
+
+### Breaking Changes: SICK Intl Fonts
+
+- New font: SICK Intl (Regular 400, Semi Bold 600)
+- Provided directly by Synergy via `@synergy-design-system/fonts`, CDN, or brand portal
+
+---
+
+## Migration: Troubleshooting
+
+- **Icons not showing?** Check asset paths and icon names.
+- **Fonts not loading?** Verify font-face URLs and file locations.
+- **Theme not switching?** Check class names and CSS imports.
+
+---
+
+## Migration: References & Further Reading
+
+- [Synergy Docs](https://synergy-design-system.github.io/)
+- [SICK Brand Portal](https://brand.sick.com/document/145#/basiselemente/typografie/sick-intl)
+- [GitHub migration board](https://github.com/orgs/synergy-design-system/projects/2/views/37)
+
+### Reference: Icons
+
+#### Reference: System Icon Library
+
+Some Synergy components depend on a set of icons that must always be available. To make sure those components display correctly, even if the `@synergy-design-system/assets` package is not installed or configured properly, these icons are baked into Synergies core directly.
+
+Components that use those icons include:
+
+- `<syn-header>`: Uses the SICK logo if not told otherwise
+- `<syn-select>`: Shows a caret sign to indicate the possibility to open the select box.
+- `<syn-alert>`: Shows an "x" icon to be able to close the alert dialog.
+
+As Synergy transitions to the new SICK brand, the icon library has been updated to include a new iconset.
+For backwards compatibility, Synergy will ship two system icon libraries during the 2.0 support cycle.
+For applications that plan to continue using Synergy 2.0, there **are no changes needed** to the icon library.
+For applications that want to use the new icon library, we have added a new utility function `setSystemIconLibrary`.
+After calling this function, the system icon library will be set to the new iconset.
+
+> Make sure to call this function before rendering any components that use the system icon library!
+
+```javascript
+import { setSystemIconLibrary } from "@synergy-design-system/components";
+setSystemIconLibrary("sick2025");
+```
+
+#### Reference: New SICK 2025 Icons
+
+The new SICK 2025 theme comes with an updated icon library that includes both outline and filled versions of icons. These icons are available in the `@synergy-design-system/assets` package and can be used with the `<syn-icon>` or `<syn-icon-button>` component.
+
+The new icon library provides two main styles:
+
+- **Outline icons**: These are the standard outlined icons, which are the default
+- **Filled icons**: These are filled versions of the same icons. The icons have the same name as the outline icons but with a suffix of `_fill`
+
+To use the new SICK 2025 icons in your application, you have several options:
+
+The outline and fill version can be used simultaneously.
+
+```html
+<!-- Outline version -->
+<syn-icon name="home"></syn-icon>
+
+<!-- Filled version -->
+<syn-icon name="home_fill"></syn-icon>
+```
+
+```javascript
+// Example vite config
+import { defineConfig } from "vite";
+import { viteStaticCopy } from "vite-plugin-static-copy";
+
+export default defineConfig({
+  plugins: [
+    viteStaticCopy({
+      targets: [
+        {
+          src: "node_modules/@synergy-design-system/assets/src/sick2025/outline/*",
+          dest: "./assets/icons/",
+        },
+        {
+          src: "node_modules/@synergy-design-system/assets/src/sick2025/fill/*",
+          dest: "./assets/icons/",
+        },
+      ],
+    }),
+  ],
+});
+```
+
+#### Reference: Migrating Icon Names
+
+Applications that are migrating from Synergy 2 may have used icons that have been renamed in the migration process.
+Those icons will **not** show up after the switch to the new icon library.
+For this reason, Synergy provides some new utilities that help migrating your applications:
+
+##### Example 1: Easy migration via `setupIcons`
+
+The easiest type of migration. If you have an icon setup as recommended in this documentation (e.g. copying the assets to a default location), you may just use the new `setupIcons` function and call it:
+
+```javascript
+import { setupIcons } from "@synergy-design-system/components";
+setupIcons("sick2025");
+```
+
+This will make sure to set the system icons to the new `sick2025` theme and also sets up a new `default` icon library that includes a static map from old icon names to the new ones.
+
+> Note you will **not** have to call `setSystemIconLibrary` as Synergy will do this internally!
+
+##### Custom setup: Using `migrateIconName` directly
+
+Synergy now ships with a new basic utility function `migrateIconName`.
+This function is able to map an icons name from the `sick2018` to the new `sick2025` icon set. It does so via a static map, returning the new names for icons.
+
+You may use this directly, if you have overwritten the default icon library via the `registerIconLibrary` method:
+
+```javascript
+import {
+  registerIconLibrary,
+  setSystemIconLibrary,
+  // Default icon set (outline)
+  migrateIconName,
+  // Alternative icon set (filled)
+  migrateIconNameFilled,
+} from "@synergy-design-system/components";
+
+// Manually override the default icon library to use migrateIconName
+// This is the default for the outline icon set.
+const customIconLibrary = {
+  name: "default",
+  resolver: name => {
+    const mappedName = migrateIconName(name);
+    return getBasePath(`assets/icons/${mappedName}.svg`);
+  },
+};
+
+// If you want to use filled icons instead, you may also append
+// "_fill" to the svg name to use those icons instead.
+const customIconLibraryFilled = {
+  name: "default",
+  resolver: name => {
+    const mappedName = migrateIconNameFilled(name);
+    return getBasePath(`assets/icons/${mappedName}.svg`);
+  },
+};
+
+// Enable your new library.
+// Do not forget to set the system icon library!
+registerIconLibrary("default", customIconLibrary);
+setSystemIconLibrary("sick2025");
+```
+
+### Reference: Tokens & Themes
+
+The Synergy tokens package introduces new CSS theme files that implement the updated SICK brand appearance:
+
+- **`sick2025_light.css`**: The new light theme featuring the SICK 2025 brand identity
+- **`sick2025_dark.css`**: The new dark theme featuring the SICK 2025 brand identity
+
+These new themes include significant visual changes compared to the existing themes e.g. changed colors and new color palettes, components with roundings, new font etc.
+
+We added new css class selectors, so it is easy to switch between different themes.
+
+- SICK 2018 light theme: `.syn-sick2018-light`
+- SICK 2018 dark theme: `.syn-sick2018-dark`
+- SICK 2025 light theme: `.syn-sick2025-light`
+- SICK 2025 dark theme: `.syn-sick2025-dark`
+
+To use the new themes in your application:
+
+1. **Replace theme imports** in your HTML or CSS:
+
+   ```javascript
+   // New Synergy SICK 2025 themes
+   import "@synergy-design-system/tokens/themes/sick2025_light.css";
+   import "@synergy-design-system/tokens/themes/sick2025_dark.css";
+   ```
+
+2. **Update theme switching logic** if you support runtime theme changes:
+
+   ```javascript
+   // Rename the class names for theme switching
+   const switchTheme = () => {
+     const { body } = document;
+     const currentTheme = body.classList.contains("syn-sick2025-dark")
+       ? "dark"
+       : "light";
+
+     if (currentTheme === "light") {
+       // Light theme
+       body.classList.remove("syn-sick2025-light");
+       body.classList.add("syn-sick2025-dark");
+     } else {
+       // Dark theme
+       body.classList.remove("syn-sick2025-dark");
+       body.classList.add("syn-sick2025-light");
+     }
+   };
+   ```
+
+### Reference: SICK Intl Fonts
+
+The SICK 2025 theme introduces a new typeface called **SICK Intl** that replaces the previously used Open Sans font. When migrating to the SICK 2025 theme, you'll need to ensure this font is properly loaded in your application.
+
+> **Important**: The SICK Intl font is now provided via the dedicated `@synergy-design-system/fonts` package for easy integration.
+
+#### Font Requirements
+
+The SICK 2025 theme requires the following font weights:
+
+- **Regular (400)**: Used for standard text content
+- **Semi Bold (600)**: Used for emphasized text and headings
+
+For detailed information about when and how to use the different font styles, refer to the [SICK Brand Portal](https://brand.sick.com/document/145#/basiselemente/typografie/sick-intl).
+
+#### Usage
+
+You have several options to include the SICK Intl font in your project.
+Each of those has its own advantages.
+
+| Option            | Advantages                                                                         | Disadvantages                                                                                                                                                                                 |
+| :---------------- | :--------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Fonts Package     | Easy integration, works offline, updates under your control, automatic CSS imports | Requires npm package installation.                                                                                                                                                            |
+| CDN               | Fast delivery when online, automatic update via CDN                                | Only works for services that have online connection, font updates may break application layouts.                                                                                              |
+| Brand&nbsp;Portal | Installation from the official source                                              | File exports (other than the original TTF) from the official source are currently misaligned, leading to issues with vertical alignment, especially for components that support or use icons. |
+
+> If you are not sure, we recommend you to use Option 1 as outlined below.
+
+##### Option 1: Using @synergy-design-system/fonts (Recommended!)
+
+Synergy now provides the SICK Intl font via the dedicated `@synergy-design-system/fonts` package.
+
+**Installation:**
+
+```bash
+npm install @synergy-design-system/fonts
+```
+
+**Usage:**
+
+```javascript
+import "@synergy-design-system/fonts";
+```
+
+This automatically imports all required font-face declarations and makes the SICK Intl font available in your application.
+
+##### Option 2: Using the SICK CDN
+
+For the quickest setup, load the fonts directly from the SICK CDN:
+
+```css
+/* Regular */
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 400;
+  src: url("https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Regular.woff2")
+    format("woff2");
+}
+
+/* Semi Bold */
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 600;
+  src: url("https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Semibold.woff2")
+    format("woff2");
+}
+```
+
+For better performance, you can also preload the font:
+
+```html
+<link
+  rel="preload"
+  href="https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Regular.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+<link
+  rel="preload"
+  href="https://www.sick.com/media/fonts/sickintl-v2/SICKIntl-Semibold.woff2"
+  as="font"
+  type="font/woff2"
+  crossorigin
+/>
+```
+
+##### Option 3: Local Installation from brand portal (not recommended!)
+
+1. Download the `SICK Intl` font from the [SICK Brand Portal](https://brand.sick.com/document/145#/basiselemente/typografie/sick-intl)
+2. Extract the ZIP file to a location accessible by your project (e.g., a `public` folder)
+3. Add the following CSS to your project (replace `PUBLIC_PATH` with your actual path):
+
+```css
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 400;
+  src: url("/PUBLIC_PATH/SICKIntl/SICKIntl-Regular.ttf") format("truetype");
+}
+
+@font-face {
+  font-display: swap;
+  font-family: "SICK Intl";
+  font-style: normal;
+  font-weight: 600;
+  src: url("/PUBLIC_PATH/SICKIntl/SICKIntl-Semibold.ttf") format("truetype");
+}
+```
+
+## Migration Steps
+
+These steps are only needed when switching to the new SICK 2025 theme.
+
+1. Always make sure to use the latest versions of the Synergy packages. You can check for updates using your package manager.
+2. Call `setSystemIconLibrary` with `sick2025` to enable the new system icons.
+3. Adjust your bundler to copy the new icons to your build output. This is necessary to ensure that the new icons are available in your application.
+4. **Update CSS theme imports** to use the new `sick2025_light.css` and `sick2025_dark.css` files instead of the legacy theme files.
+5. **Update theme class names** in your JavaScript theme switching logic to use `syn-sick2025-light` and `syn-sick2025-dark`.
+6. **Add the SICK Intl font** by either using the dedicated `@synergy-design-system/fonts` package (recommended), using the SICK CDN, or downloading it locally. The fonts package automatically provides all required font-face declarations for Regular (400) and Semi Bold (600) weights.

package/data/layers/full/setup/setup:synergy-migrations/migration/v2-2018-to-v3-2018.md

@@ -0,0 +1,147 @@
+# 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)