swisspost · alizedebray · Oct 3, 2025 · Sep 22, 2025 · Sep 22, 2025 · Sep 26, 2025
@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': minor
+---
+
+Added usage examples for the header component.
@@ -1,8 +1,7 @@
-import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
+import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as HeaderStories from './header.stories';
 import './header.styles.scss';
 import StylesPackageImport from '@/shared/styles-package-import.mdx';
-import HeaderSelectedClass from './header-selected-class.sample.html?raw';
 
 <Meta of={HeaderStories} />
 
@@ -13,38 +12,70 @@ import HeaderSelectedClass from './header-selected-class.sample.html?raw';
 
 </div>
 
-<div className="lead">The header of the Post.</div>
+<div className="lead">
+  Allow users to navigate through your application.
+</div>
+
+The Header adapts to your needs and can contain a variety of sub-components depending on your use case.
+
+It is divided into two sections:
+
+1. **Global Header** (Yellow Background): provides navigation links and information that are global to the entire organization.
+2. **Application Header** (White Background): displays navigation links and information specific to the current application.
 
-<Canvas sourceState="shown" of={HeaderStories.Default} style={{ height: '700px' }} />
+<div className="main-story">
+  <Canvas sourceState="shown" of={HeaderStories.Default} />
+</div>
 <div className="hide-col-default">
   <Controls of={HeaderStories.Default} />
 </div>
 
-## Styling Active Navigation Items with `aria-current="page"`
+## Installation
 
-<p><b>The `aria-current="page"` attribute highlights the active navigation items.</b> It should be applied by application logic to the `<a>` element inside the active `<post-list-item>` of the `<post-mainnavigation>`. Once an element has `aria-current="page"`, its hierarchical parent will also inherit the same styling automatically.</p>
+The `<post-header>` element is part of the `@swisspost/design-system-components` package.
+For more information, read the [getting started with components guide](/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs).
 
-### Example
+<StylesPackageImport components={['header', 'list', 'button']} />
 
-<Source code={HeaderSelectedClass} language="html" />
+### CSS Properties
 
-## CSS Properties
+The `<post-header>` styles expose several custom properties on the `:root` element:
 
-The `<post-header>` component exposes the following custom properties to the `:root` element:
+- `--post-header-height`: the current visible height of the header
+- `--post-header-expanded-height`: the height of the header when expanded
+- `--post-header-reduced-height`: the height of the header when reduced
 
-<ul>
-  <li>
-    `--post-header-height`: This property represents the height of the header that is currently
-    visible in the viewport.
-  </li>
-  <li>`--post-header-expanded-height`: This property represents the actual size of the header.</li>
-</ul>
-Additionally, it sets the `scroll-padding-top` property to equal the visible header height, which can
-be useful for pages that use scroll navigation.
+In addition, the `<post-header>` styles set the `scroll-padding-top` property on the `<body>` element to match the currently visible header height.
+This ensures that when using scroll navigation (e.g. jumping to anchors), content is positioned correctly below the header.
 
-## Installation
+## Active Navigation Items
 
-The `<post-header>` element is part of the `@swisspost/design-system-components` package.
-For more information, read the [getting started with components guide](/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs).
+**The `aria-current="page"` attribute highlights the active navigation items**
 
-<StylesPackageImport components={['header', 'list', 'button']} />
+This attribute is not added automatically,
+it must be applied by your application logic to the `<a>` element of the `<post-mainnavigation>` that represents the page currently being viewed.
+Once applied, parent items in the navigation automatically inherit the correct selected styling.
+
+<Canvas sourceState="shown" of={HeaderStories.ActiveNavigationItem} />
+
+## Examples
+
+### Post Portal
+
+The Header for the Post Portal (post.ch) is a consistently available interface element that provides a consistent navigation experience across the whole Post Portal and other portals.
+
+It not only contains globally available key elements (such as Language), it also provides a first content selection via the target group buttons. They define the further navigation.
+
+<Canvas of={HeaderStories.Portal} inline="false" />
+
+### Microsite
+
+The Microsite Header is a consistently available interface element that provides a consistent navigation experience across the whole Microsite.
+
+<Canvas of={HeaderStories.Microsite} inline="false" />
+
+### One Pager
+
+The One Pager Header is a consistently available interface element that provides a consistent navigation experience across the whole One Pager.
+
+<Canvas of={HeaderStories.OnePager} inline="false" />