@synergy-design-system/metadata 1.0.0 → 3.0.1

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

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

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

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

package/data/layers/full/setup/setup:tokens-package/tokens/BREAKING_CHANGES.md

@@ -0,0 +1,180 @@
+# Handling breaking changes between major versions
+
+This guide holds the required information for migrating from one major version of `@synergy-design-system/tokens` to the next.
+
+> ⚠️ Migrations **must** always be done from one major version to the next to prevent issues (e.g. with types and property changes)
+> This means when moving from `@synergy-design-system@tokens` v1.x to v3.x,
+> you will **have to apply** the changes from v1.x to v2.x first!
+
+---
+
+## Version 3.0
+
+<h3 id="theme-sick2025-v3">Theme: SICK 2025</h3>
+
+#### ⚠️ New default theme SICK 2025
+
+**Associated Ticket(s)**:
+
+- [#1149](https://github.com/synergy-design-system/synergy-design-system/issues/1149)
+
+**Reason**:
+
+With the migration from Synergy version 2 to Synergy version 3, we are adjusting the default export.
+The `light.css` and `dark.css` theme imports now point to `SICK 2025` instead of `SICK 2018`.
+
+This also means that the classes `.syn-theme-light` and `.syn-theme-dark` are now also set for the `SICK 2025` theme instead on the `SICK 2018` theme which was the old default.
+
+**Migration Steps**:
+
+> These steps are only needed if you want to stay on `SICK 2018` **and** have imported `light.css` or `dark.css`!
+
+- Make sure to load the `sick2018_light.css` or `sick2018_dark.css` files instead of `light.css` and `dark.css`.
+
+**Example (before)**:
+
+```css
+/* Points to sick2018_light.css in version 2.x */
+@import "@synergy-design-system/tokens/dist/themes/light.css";
+
+/* Points to sick2018_dark.css in version 2.x */
+@import "@synergy-design-system/tokens/dist/themes/dark.css";
+```
+
+```html
+<!-- Points to syn-sick2018-light in version 2.x  -->
+<div class="syn-theme-light">...</div>
+
+<!-- Points to syn-sick2018-dark in version 2.x  -->
+<div class="syn-theme-dark">...</div>
+```
+
+**Example (after)**:
+
+```css
+/* Adjust to this path to still load the SICK 2018 theme in version 3.x */
+@import "@synergy-design-system/tokens/dist/themes/sick2018_light.css";
+
+/* Adjust to this path to still load the SICK 2018 theme in version 3.x */
+@import "@synergy-design-system/tokens/dist/themes/sick2018_dark.css";
+```
+
+```html
+<!-- Points to syn-sick2025-light in version 3.x  -->
+<div class="syn-theme-light">...</div>
+
+<!-- Points to syn-sick2025-dark in version 3.x  -->
+<div class="syn-theme-dark">...</div>
+```
+
+---
+
+<h3 id="theme-sick2018-v3">Theme: SICK2018</h3>
+
+#### ⚠️ Future deprecation of the SICK 2018 theme
+
+**Associated Ticket(s)**:
+
+- [#1149](https://github.com/synergy-design-system/synergy-design-system/issues/1149)
+
+**Reason**:
+
+The SICK 2018 themes were the primary themes for Synergy version 2.x.
+With the release of Synergy version 3, new applications should use the SICK 2025 theme to be brand-compliant.
+
+> We plan to keep the SICK 2018 theme available until at least the beginning of 2027.
+> It will likely be removed in the first major release after 2027.
+
+**Migration Steps**:
+
+- Upgrade your application to use the new SICK 2025 theme.
+
+---
+
+<h3 id="token-studio-v3">Token Studio</h3>
+
+#### ⚠️ Future deprecation of outdated token studio code
+
+**Associated Ticket(s)**:
+
+- [#1149](https://github.com/synergy-design-system/synergy-design-system/issues/1149)
+
+**Reason**:
+
+TokenStudio is a Figma solution that was used initially for syncing design tokens from Figma to Code.
+With Synergy version 3, we are using Figma Variables for this task.
+The original metadata housed in `src/figma-tokens` is no longer used for Synergy and will therefore be removed.
+
+**Migration Steps**:
+
+- If you still need them, copy the assets located in `src/figma-tokens` to a local destination
+
+---
+
+<h3 id="token-syn-page-background-v3">`--syn-page-background`</h3>
+
+#### ⚠️ Future deprecation
+
+**Associated Ticket(s)**:
+
+- [#1149](https://github.com/synergy-design-system/synergy-design-system/issues/1149)
+
+**Reason**:
+
+The token `--syn-page-background` does not match the semantics of our other tokens. Therefore, we renamed it to `--syn-page-background-color`. The token still works, but will be removed in a future major release.
+
+**Migration Steps**:
+
+Just exchange all occurrences of `--syn-page-background` with `--syn-page-background-color`.
+
+**Example (before)**:
+
+```css
+body {
+  background-color: var(--syn-page-background);
+}
+```
+
+**Example (after)**:
+
+```css
+body {
+  background-color: var(--syn-page-background-color);
+}
+```
+
+---
+
+<!-- USE THIS AS A TEMPLATE FOR ADDITIONAL MIGRATION STEPS
+
+<h3 id="change-VERSION">`Change`</h3>
+
+#### ⚠️ DESCRIBE THE CHANGE HERE
+
+**Associated Ticket(s)**:
+
+- [#1](https://github.com/synergy-design-system/synergy-design-system/issues/1)
+
+**Reason**:
+
+DESCRIBE THE REASON FOR THIS CHANGE
+
+**Migration Steps**:
+
+MIGRATION IN TEXT FORM
+
+**Example (before)**:
+
+```css
+EXAMPLE BEFORE THE CHANGE
+```
+
+**Example (after)**:
+
+```css
+EXAMPLE AFTER THE CHANGE
+```
+
+---
+
+-->