Create migration guide

blog/2025-10-01-release-4/index.md

@@ -0,0 +1,88 @@
+---
+authors: [felixleist]
+tags: [release]
+---
+
+# Release V4.0.0
+
+![banner](./2510_blog_4-0.png)
+
+The next chapter of the Industrial Experience Design System is here. This version brings together thoughtful feature enhancements and essential style refinements, offering greater flexibility while reinforcing design consistency.
+
+<!-- truncate -->
+
+# How to start?
+
+- Install `@siemens/ix` (`@siemens/ix-angular`, `@siemens/ix-react`, `@siemens/ix-vue`) via the `latest` tag
+- Review detailed changelog [here](/docs/home/releases/changelog)
+- Make sure you're using the latest published version of our Figma library
+
+# Button update
+
+![button](./2510_blog_buttons.png)
+
+The time of confusing button naming is officially behind us. With this release, we’ve introduced a clear and intuitive naming convention: primary, secondary, and tertiary [buttons](/docs/components/button/guide). Now labeled exactly as such. This change improves clarity, making it easier to choose the right button for the right context.
+
+To implement this improvement, we had to introduce a breaking change. Existing variant names will need to be updated manually. Please refer to our [migration guide](/docs/home/migration/4_0_0) for detailed instructions.
+
+In line with brand consistency efforts, all buttons now feature slightly rounded corners, offering a more modern and approachable look. Additionally, we’ve added support for placing icons to the right of the label. Especially useful for “Next” actions, where a left-aligned arrow often felt visually off.
+
+# New app header options
+
+![appheaderoptions](./2510_blog_appheader.png)
+
+The [app header](/docs/components/application-header/guide) is now more flexible than before. With the introduction of an additional secondary slot, teams can tailor the header to better fit their application needs.
+
+We’ve also updated the documentation to showcase all available configuration options, including:
+
+- Displaying a user avatar
+- Using a secondary slot
+- Enabling the borderless variant
+- Showing an app icon
+- Adding a sub-label to the app name
+
+These enhancements come as additions to the existing header component, giving teams more options without disrupting current implementation.
+
+# Elevation principle
+
+![elevation](./2510_blog_elevation.png)
+
+Elevation helps create depth in the user interface. A simple elevation principle makes it easier for users to understand which elements sit above others, improving both hierarchy and interactivity.
+
+With this major release, we are reducing the use of semi-transparent colors in favor of solid tones. This change improves visual separation between layers and aligns with our goal of a consistent design language.
+
+The new colors are applied automatically when migrating to this version. Therefore, we recommend teams visually review their interfaces. To support this, our migration guide includes an overview where switching to outline variants is needed for good layer separation.
+
+# Angular 20
+
+![angular20](./2510_blog_angular.png)
+
+This release brings full compatibility with Angular 20 and up, helping teams keep their projects aligned with the latest framework improvements.
+
+To reflect this, the Angular specific peer dependencies have been updated to require at least version 20. Projects using this package will need to upgrade to Angular 20 or higher before migrating to the latest version of iX. See more in the [migration guide](/docs/home/migration/4_0_0).
+
+# AG Grid update
+
+![aggrid](./2510_blog_aggrid.png)
+
+We are now publishing a separate Figma library based on the [official AG Grid design system](https://www.figma.com/community/file/1360600846643230092) styled with the iX theme. This gives designers direct access to AG Grid’s native components and layout logic. Developers benefit from AG Grid’s new [theming API](https://blog.ag-grid.com/introducing-our-new-theming-api/), which makes styling grids easier and more flexible. Together, this change makes design and development faster, clearer, and better aligned.
+
+# New section within UX writing guidelines: Formatting
+
+We’ve just released a brand-new section in our [UX writing guidelines](/docs/guidelines/language/writing-style-guide-getting-started), designed to bring clarity, consistency, and user-friendliness to some of the most commonly used — and often overlooked — elements in digital communication. This update covers:
+
+- Addresses
+- Dates
+- Measurements and units
+- Money and currency
+- Names and titles
+- Numbers and percentages
+- Software versions
+- Time and time zones
+
+# Any questions or feedback?
+
+Please reach out to us at [[email protected]](mailto:[email protected]) and tell us about your migration experience.
+If you encounter any issues, we are here to support you every step of the way.
+
+We greatly appreciate your contributions.

docs/components/overview.md

@@ -97,7 +97,7 @@ import { CategoryButton } from '@site/src/components/CategoryButton';
 | [Card list](./card-list/index.mdx)     | Card lists display a large number of cards or items of the same type in a lightweight, grouped manner.                       |
 | [Flip](./flip/index.mdx)               | Flips are containers that flip when clicked to reveal additional content.                                                    |
 | [Event list](./event-list/index.mdx)   | Event lists display a list of any type of element with additional details.                                                   |
-| [Drawer](legacy/drawer/index.mdx)      | Drawers are containers that open on the click of a button to show additional content.                                        |
+| [Drawer](legacy/drawer/index.mdx)           | Drawers are containers that open on the click of a button to show additional content.                                        |
 | [Layout auto](./layout-auto/index.mdx) | Auto-layouts are containers that automatically adjust the size of their columns based on the content.                        |
 | [Layout grid](./layout-grid/index.mdx) | Layout grids are used to structure the layout of a page or screen responsively.                                              |
 | [Modal](./modal/index.mdx)             | Modals present information prominently and are useful for gathering essential user input without navigating to another page. |

docs/home/migration/4_0_0/index.md

@@ -1,73 +1,180 @@
 ---
 sidebar_position: 0
-sidebar_title: Upgrade to v4
-title: Upgrade to v4
+sidebar_title: Upgrade to V4
+title: Upgrade to V4
 doc-type: banner
-description: Welcome to the migration guide for upgrading from Siemens Industrial Experience design system v3 to v4. This guide introduces all major changes.
+description: Welcome to the migration guide for upgrading from Siemens Industrial Experience design system V3 to V4. This guide supports you through all the major changes.
 ---
-# Upgrade to v4.0.0
+
+# Upgrade to V4.0.0
 
 ## TL;DR
-- We renamed the [button variants](#ix-button) to better reflect their usage.
-- Map and basic navigation have been removed in favor of the [application](../../../components/application/guide.md) component.
-- Drawer has been deprecated in favor of [panes](../../../components/panes/index.mdx).
 
-## Icons renamed or removed
+- We upgraded to [Angular 20](#angular-20).
+- We renamed the [button variants](#ix-button-variants) to better reflect their usage.
+- Map and basic navigation have been removed in favor of the [application](#removed-basic-navigation-and-map-navigation) component.
+- Drawer has been [deprecated](#drawer) in favor of [panes](/docs/components/panes/guide).
+- We made changes to the [elevation principle](#updated-elevation-principle) which means teams need to check whether their components need an outline.
+
+## Updated dependencies
+
+### Angular 20
+
+Important: Projects using `@siemens/ix-angular` must upgrade to Angular 20 or higher before updating to this version. Some APIs deprecated in previous Angular versions may have been removed; review the Angular 20 changelog for migration steps. Ensure all third-party Angular libraries are compatible with at least V20 to avoid runtime issues.
+
+## Renamed or removed icons
 
-TO BE DONE
+<div class="table-full-width table-column-equal-width">
+| ❌ **Deprecated** | ✅ **Replace with**       |
+| :----------------- | :------------------------- |
+| `cam`             | Replace with `output-cam` |
+</div>
 
 ## Deprecated and removed components
 
-- Map and basic navigation
-- Drawer
+### Removed basic navigation and map navigation
 
-### Removed map and basic navigation
+Use the [ix-application](/docs/components/application/guide) with the following components to replace the basic and map navigation:
 
-TO BE DONE
+- [Application header](/docs/components/application-header/guide) containing the previous `application name`
+- [Application menu](/docs/components/application-menu/guide)
+- [Pane (inline)](/docs/components/panes/guide) replacing the map navigation's left sidebar
+- [Pane (floating)](/docs/components/panes/guide) or original overlay content replacing the map navigation's right overlay
 
-### Deprecated drawer
+### Drawer
 
-The drawer component has been deprecated and will be removed in the next major release. We recommend using [panes](../../../components/panes/index.mdx) instead, which provide similar functionality with improved performance and usability. Use this configuration for a similar experience:
+The drawer component has been deprecated and will be removed in the next major release. We recommend using [panes](/docs/components/panes/index.mdx) instead, which provide similar functionality with improved performance and usability. Use this configuration for a similar experience:
 
 ```html
 <ix-pane
-	heading="Title"
-	variant="floating"
-	composition="right"
-	borderless="true"
-	size="320px"
-	close-on-click-outside="true"
-	hide-on-collapse>
-	My content
+heading="Title"
+variant="floating"
+composition="right"
+borderless="true"
+size="320px"
+close-on-click-outside="true"
+hide-on-collapse
+>
+My content
 </ix-pane>
 ```
 
 Here is a comparison of the properties and events between the drawer and pane components:
 
-| **Drawer**        | **Pane**             |
-| ----------------- | -------------------- |
+<div class="table-full-width table-column-equal-width">
+| ❌ **Drawer**     | ✅ **Pane**          |
+| :----------------- | :-------------------- |
 | `expanded`        | `show`               |
 | `width`           | `size`               |
 | `min-width`       | (not available)      |
 | `max-width`       | (not available)      |
 | `full-height`     | (not available)      |
 | `on-drawer-close` | `on-expanded-change` |
 | `on-open`         | `on-expanded-change` |
+</div>
 
 Additional changes you need to consider when migrating from drawers to panes:
+
 - You may need to adjust your content layout accordingly since pane contents have a default padding of `16px`.
 - You now need to define a title for the pane using the `heading` property.
 
 ## Component updates
 
-### ix-button
+### ix-application
+
+- `min-width: 0` has been added to the content-area in `ix-application` to prevent the flex container from growing beyond the screen width.
+- If you have implemented a workaround for this behavior, your application's layout might be affected by this change.
+
+### ix-application-header
+
+- Changed height from `2.75rem` (44px) to `3rem` (48px).
+
+### ix-button variants
+
+Affected components:
+
+- ix-button
+- ix-dropdown-button
+- ix-icon-button
+- ix-split-button
+- ix-toggle-button
+- ix-icon-toggle-button
+
+- Renamed variant `secondary` to `subtle`
+- Removed the property `outline` in favor of new `secondary` variants
+- Removed the property `ghost` in favor of new `tertiary` variants
+
+![Buttons](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=6708-52302&t=bGky2tHjBPC9fOGT-4)
+
+To take over the changes, rename all button variants according to this table. Start with renaming `secondary` to `subtle-*` variants to avoid unwanted overriding.
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `secondary`    | `false`        | `false`      | `subtle-primary`   |
+| `secondary`    | `true`         | `false`      | `subtle-secondary` |
+| `secondary`    | `false`        | `true`       | `subtle-tertiary`  |
+| `primary`      | `false`        | `false`      | `primary`          |
+| `primary`      | `true`         | `false`      | `secondary`        |
+| `primary`      | `false`        | `true`       | `tertiary`         |
+| `danger`       | `false`        | `false`      | `danger-primary`   |
+| `danger`       | `true`         | `false`      | `danger-secondary` |
+| `danger`       | `false`        | `true`       | `danger-tertiary`  |
+</div>
+
+For buttons without an explicity set variant, the default is used. As defaults differ between the button components, the renaming should be component-specific.
+
+#### Button with default variant
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `default`      | `false`        | `false`      | `primary`          |
+| `default`      | `true`         | `false`      | `secondary`        |
+| `default`      | `false`        | `true`       | `tertiary`         |
+</div>
 
-- Removed `outline` and `ghost`.
-- Replaced `variant` names:
-	- `primary` → `primary`
-	- `primary` `outline` → `primary`
-	- `secondary` → `outline`
-	- `tertiary` → `ghost`
+#### Dropdown button with default variant
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `default`      | `false`        | `false`      | `primary`          |
+| `default`      | `true`         | `false`      | `secondary`        |
+| `default`      | `false`        | `true`       | `tertiary`         |
+</div>
+
+#### Icon button with default variant
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `default`      | `false`        | `false`      | `subtle-primary`   |
+| `default`      | `true`         | `false`      | `subtle-secondary` |
+| `default`      | `false`        | `true`       | `subtle-tertiary`  |
+</div>
+
+#### Split button with default variant
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `default`      | `false`        | `false`      | `primary`          |
+| `default`      | `true`         | `false`      | `secondary`        |
+| `default`      | `false`        | `true`       | `tertiary`         |
+</div>
+
+#### Toggle button and icon toggle button with default variant
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Variant** | ❌ **Outline** | ❌ **Ghost** | ✅ **New variant** |
+| :-------------- | :-------------- | :------------ | :------------------ |
+| `default`      | `false`        | `false`      | `subtle-primary`   |
+| `default`      | `true`         | `false`      | `subtle-secondary` |
+| `default`      | `false`        | `true`       | `subtle-tertiary`  |
+</div>
+
+We recommend to visually review your changes. Ensure that `subtle-*` variants are not mixed with the default variant.
 
 ### ix-pane
 
@@ -76,9 +183,46 @@ Additional changes you need to consider when migrating from drawers to panes:
 - Added `aria-label-expand-button` property.
 - Added `aria-label-collapse-button` property.
 
+### ix-aggrid
+
+We are updating to the latest AG Grid version and are providing a new brand-aligned iX theme.
+
+#### Design
+
+- Published a new 'AG Grid theme' library
+- Deprecated AG Grid components from 'iX components' Figma library
+
+Note: Manual replacement effort needed, there is no automated replacement possible.
+
+<div class="table-full-width table-column-equal-width">
+| ❌ **Deprecated**                     | ✅ **Replace with**                 |
+| :------------------------------------- | :----------------------------------- |
+| AG Grid Building Blocks / Data Cell   | Grid Cell                           |
+| AG Grid Building Blocks / Header Cell | Grid Header                         |
+| AG Grid Building Blocks / Header Row  | not needed                          |
+| AG Grid Building Blocks / Row         | not needed                          |
+| AG Grid component / AG Grid Column    | -                                   |
+| AG Grid component / AG Grid Row       | -                                   |
+| AG Grid component / AG Grid Table     | iX AG Grid Table                    |
+| AG Grid component / AG Grid Table Example    | iX AG Grid Table Example            |
+</div>
+
+#### Implementation
+
+TBD
+
 ## Global style updates
 
-Lorem ipsum
+### Updated elevation principle
+
+With the updated elevation principle, some components require a visual outline if they are placed on `color-2` or `component-1`. See more in the styles chapter on [elevation](/docs/styles/elevation).
+
+![Elevation principle](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=6707-50604&t=bGky2tHjBPC9fOGT-4)
+
+If you have used the `filled` variant of following components on `color-2` or `component-1`, please change their variant to `outline`:
+- [Blind](/docs/components/blind/guide)
+- [Card, Push card, Action card](/docs/components/card/guide)
+- [Event list](/docs/components/event-list/)
 
 ## Questions ❓🙋‍♀️
 

sidebars.ts

@@ -1047,7 +1047,6 @@ const sidebars: SidebarsConfig = {
 
       label: 'Charts',
       items: [
-        'components/charts-overview/index',
         {
           id: 'components/charts-overview/index',
           type: 'doc',
@@ -1107,16 +1106,6 @@ const sidebars: SidebarsConfig = {
             },
           ],
         }),
-        createTabItem({
-          id: 'legacy/drawer/index',
-          label: 'Drawer',
-          items: [
-            {
-              id: 'legacy/drawer/code',
-              label: 'Code',
-            },
-          ],
-        }),
         'legacy/checkbox',
         'legacy/input',
         'legacy/radiobutton',