docs: usage guide for new application header

.env.pullrequest

@@ -0,0 +1,3 @@
+DOCS_BRANCH='release-4.0.0'
+DOCS_BRANCH_TYPE='pull request' # Check if the branch is a pull request
+DOCS_PR_NUMBER='2068'

docs/components/application-header/guide.md

@@ -3,90 +3,131 @@ doc-type: 'tab-item'
 ---
 # Application header - Usage
 
-![Application header with different options](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1634-56424&mode=design&t=4XzscFw57dE7McUX-11)
+In its simplest version, application headers only show the company logo and the application name.
 
-1. Application switch (optional)
-2. Brand logo
-3. Application name
-4. Slot for additional elements (optional)
-5. Avatar (optional)
+![Application header simple](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39093&mode=design)
+
+1. Company logo
+2. Application name
+
+The **company logo** (1) identifies the brand. For Siemens applications, the Siemens logo with the brand theme is the default combination. Contractual agreements may allow partner logos under certain conditions.
+The logo adapts its width automatically, height remains fixed. It is colored at runtime based on the selected theme if the following prerequisites are met:
+- Logo is provided as SVG
+- Color of SVG elements are set to `currentcolor`
+
+Without meeting these prerequisites, the logo appears without any color adaption.
+
+The **application name** (2) shows the official name of the application. Its width adjusts dynamically but may be truncated if space is limited by other header elements.
 
 ## Options
 
-- **Show menu:** If the application is hosted inside a framework that comes with its own header, you can omit the entire application header to avoid having two headers on top of each other. The framework’s header then provides the brand identity, the application name and other information.
-- **Name:** The application name shows the official name of the application. To show additional information use the pipe character "|" and 2 spaces before and after to separate both.
-- **Logo:** Provide the brand logo as SVG. The logo must be monochromatic and cannot contain strokes as it is colored during runtime depending on your chosen theme. For Siemens applications, only the Siemens logo with the brand theme is allowed.
-- **Application switch:** Use the [application switch](../application/guide.md#application-switch) to allow users to navigate across applications. When clicking the application switch a modal with a list of available applications opens.
-- **Avatar:**
-	- **Top:** Defines the first line of the additional user information. We typically use this to show primary user information (first and last name or username), depending on the available information. Overflows are clipped with an ellipsis (…).
-	- **Bottom:** Defines the second line of additional user information, used to show secondary information, for example user role. Overflows are clipped with an ellipsis (…).
-	- **Initials:** Shows avatar with initials.
-	- **Image:** Shows avatar with images.
-- **Slot:** Use the slot to provide additional high-level information or actions and functions which may impact the application context, e.g. mode switching. Note that overflows are not handled automatically; at breakpoint `sm` the slot collapses and is only accessible via the overflow icon.
+The app header component offers great flexibility through optional elements, but each addition should be considered carefully. Adding too many elements can reduce usability and introduce challenges, especially regarding responsiveness and overflow behavior. We recommend keeping the header clean and lean.
 
-![Examples of slot usages](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1679-19526&mode=design&t=UPXhDWuRHtygtfFI-11)
+### Avatar
 
-We typically use the slot for:
+![Avatar and avatar dropdown](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39231&mode=design)
+
+1. User avatar
+2. Avatar dropdown
+
+The avatar indicates the currently logged in user and provides access to user-related actions and settings. Its position in the application header ensures visibility of security-relevant information across all breakpoints.
+
+Clicking the avatar opens a dropdown with additional user information and actions such as log out, user profile, or user settings. If the application does not support multiple users or user profiles, do not use the avatar.
+
+For applications that allow usage without login, consider alternative approaches:
+- Show a login button in the [slot for additional elements](#slot-for-right-aligned-content) and hide the avatar
+- Display the avatar with a placeholder image and provide login-related information and actions in the dropdown
+
+### Application switch
+
+![Application switch](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39460&mode=design)
+
+Use the application switch (see [application](../application)) to launch and navigate between related applications. Clicking the application switch (1) opens a modal (2) with a list of available applications.
 
-- Log in button, if the application runs without a logged in user
-- Changing the top level data context like environment, workspace, tenant or similar
-- Important contextual information users should be aware of (like local times in remote access use cases)
+### Application icon
+
+![Application icon](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39393&mode=design)
+
+The application icon (1) is a non-interactive visual element placed in the header to represent the application. It is displayed within a fixed size and uses a defined border radius. The standard web image formats are supported. The provided image is scaled if necessary while maintaining the aspect ratio.
+
+An optional outline (2) can be added to visually separate the icon from the background when needed. It should only be used when contrast or clarity requires it.
+
+### Suffix for application name
+
+![Application name suffix](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39713&mode=design)
+
+The application name suffix (1) appears to the right of the application name. It provides additional information or context. For Siemens applications, we use it for contractually regulated additions in partner branding scenarios, e.g. "powered by Siemens".
+
+### Slot for right-aligned content
+
+![Slot](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39744&mode=design)
+
+The slot (1) provides space for placing functions and information aligned to the right side of the application header. We use this slot for high-level information or actions impacting the application context, e.g. mode switching.
+
+We typically use the slot for:
+- Log in button, if the application runs without a logged-in user
+- Changing the top-level data context like environment, workspace, or tenant
+- Displaying important contextual information, e.g. local times in remote access scenarios
 - Access to application-wide actions like global search
 
-## Behavior in context
+Overflow behavior is not handled automatically. At breakpoint sm, the slot collapses and its content becomes accessible via an overflow icon. See [behavior](#behavior) for details.
 
-The header automatically adapts the breakpoints defined in the [application](../application).
+### Secondary slot for left-aligned content
 
-![Application header at breakpoints lg/md and sm](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1636-62980&mode=design&t=4XzscFw57dE7McUX-11)
+![Secondary slot](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A39911&mode=design)
 
-10. Layout at breakpoint lg and md
-11. Layout at breakpoint (sm)
-12. Application menu icon
-13. Overflow icon to access the slot content
-14. Slot content
-15. Close icon to close the application menu
-16. Application menu with the application switch icon at the top
+The secondary slot (1) allows the placement of functions aligned to the left side of the application header.
+We typically use the secondary slot for:
+- Lean elements such as toolbars, which offer compact access to key actions and can be easily adapted for overflow behavior.
+- While primary navigation tabs can also be placed here, they consume more space and are less flexible in responsive layouts.
 
-At breakpoints "lg" and "md" the application header behaves identically. At breakpoint "sm" the layout changes in the following way:
+Overflow behavior is not handled automatically. At breakpoint sm, the slot collapses and its content becomes accessible via an overflow icon. See [behavior](#behavior) for details.
 
-- The application menu hides, displaying the application menu icon (12), a click opens the application menu (16).
-- The application switch (if used) moves to the application menu (16).
-- The brand logo disappears.
-- The slot for additional elements (if used) moves to the overflow dropdown that opens on click on the overflow icon (13).
+### Borderless
 
-### Avatar
+![Borderless](https://www.figma.com/file/wEptRgAezDU1z80Cn3eZ0o?type=design&node-id=6427%3A40378&mode=design)
+
+The borderless option sets the existing bottom border (1) of the header to a transparent color. Using the same background color, this creates a visual connection between the header and the following element, making them appear as a unified block.
 
-With the new modular application frame, we moved the avatar from the navigation menu to the application header. This ensures the avatar has security-relevant information available at all breakpoints.
+### Window controls
 
-![Avatar and avatar dropdown](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1635-60462&mode=design&t=UPXhDWuRHtygtfFI-11)
+![OS specific window controls](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=6599-45912&t=07oqeGxwT0wAyLin-11)
 
-1. Avatar dropdown
-2. User avatar
-3. Top text line
-4. Bottom text line
+If the applications runs in a desktop framework like Electron, we recommend the following approach to avoid an additional OS-specific window header above the application header:
+- Place a container (2) beside the actual application header (1), while considering the OS specifics.
+- Place the window controls inside and consider applying the OS specific style and behavior.
+- Use same height, background and border properties for this container.
 
-The avatar is an optional element and indicates the current logged in user. If your application doesn’t support different users or user profiles, the avatar can be removed.
 
-Clicking the avatar opens a dropdown (1) with additional user information (2, 3, 4) and possibly other user related actions like log out, profile settings or user settings.
+### Framework header
 
-![Examples of access login](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1636-62468&mode=design&t=4XzscFw57dE7McUX-11)
+If the application is hosted inside a framework that comes with its own header, you can omit the entire application header to avoid having two headers on top of each other. The framework’s header then provides the brand identity, the application name and other information.
 
-If your application is accessible without a specific user or profile log in, you can offer alternative ways of logging in without needing to specify a user or showing the avatar. Alternative approaches can be:
+## Behavior
 
-- Show a log in button in the slot for additional elements and hide the avatar.
-- Show the avatar with a placeholder image and show text in the user information section.
+The header automatically adapts the breakpoints defined in the [application](../application) layout.
 
-:::info
+![Application header at breakpoints lg/md and sm](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=6427-40565&t=S6lUQ3W9x7i87i8E-4)
 
-The deprecated [basic navigation](../../legacy/basic-navigation) and [map navigation](../../legacy/map-navigation) use the avatar in the [application menu](../application-menu).
+At breakpoints "lg" and "md" the application header remains unchanged, truncation applies to the application name (1). When its minimum width is, reached truncation is applied to the secondary slot.
 
-:::
+At breakpoint "sm" the layout changes in the following way:
+- The application menu is hidden and replaced by a menu icon (2) in the header, clicking it opens the menu.
+- The company logo and a possibly used application name suffix is not shown.
+- If the application switch (3) is used, it moves to the application menu.
+- If slots are used, their elements move into dedicated sections in the overflow dropdown (4), accessible via the overflow icon (5).
+- If the manual overflow slot is used, its content appears at lowest position within the overflow dropdown (7).
 
-![Avatar dropdown menu](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?type=design&node-id=1013-70909&mode=design&t=Ch2wsi2EtQ3sPBpS-11)
+### Manual overflow menu
+- The overflow slot can be manually filled to trigger the overflow menu at any breakpoint.
+- When content is placed in the manual overflow slot, the overflow button appears even at medium (md) and large (lg) viewports.
+- This allows intentional placement of elements into the overflow menu (6), independent of automatic breakpoint behavior.
 
 ## Dos and Don’ts
 
 - Do align other slot usages for Siemens applications with our team to keep a consistent look and feel
 - Do use the avatar dropdown for actions related to the current logged in user
-- Don’t overload the slot with too many elements (overflows are not handled automatically)
-- Don’t use the avatar if your application does not support user profiles
+- Do test layout behavior at all breakpoints to ensure content remains accessible
+- Don’t overload the slots with too many elements to avoid losing clarity and hierarchy
+- Don’t use the avatar if your application does not support user profiles
+- Don’t rely on automatic overflow handling for complex layouts, instead reduce complexity

docs/components/application-header/index.mdx

@@ -1,6 +1,6 @@
 ---
 doc-type: "tabs"
-description: 'Application headers provide a structured area for key elements like brand logo, application name and user avatar.'
+description: 'Application headers provide a structured area for essential elements such as company logo and application name, while allowing flexibility through optional elements like the user avatar or application switch.'
 title: 'Application header'
 deprecated:
 ---