chore(docs): common installation instruction for web components (#6514)

leagrdv · web-flow · commit bee164a6fdc9 · 2025-10-31T10:01:35.000+01:00
## 📄 Description - Removed all of the repetitive installation instructions on web components and created a common section for it. - Added the instruction on web components that didn't have any. ## 🚀 Demo If applicable, please add a screenshot or video to illustrate the changes. --- ## 🔮 Design review - [ ] Design review done - [X] No design review needed ## 📝 Checklist - ✅ My code follows the style guidelines of this project - 🛠️ I have performed a self-review of my own code - 📄 I have made corresponding changes to the documentation - ⚠️ My changes generate no new warnings or errors - 🧪 I have added tests that prove my fix is effective or that my feature works - ✔️ New and existing unit tests pass locally with my changes
diff --git a/.changeset/tired-horses-kick.md b/.changeset/tired-horses-kick.md
@@ -0,0 +1,5 @@
+---
+'@swisspost/design-system-documentation': patch
+---
+
+Added common installation instructions on every web component documentation page.
diff --git a/packages/documentation/src/shared/components-package-install.mdx b/packages/documentation/src/shared/components-package-install.mdx
@@ -0,0 +1,11 @@
+## Installation
+
+<>
+  {/* eslint-disable-next-line no-undef */}
+  {props.subtitle && <h3>{props.subtitle}</h3>}
+
+{/* eslint-disable-next-line no-undef */}
+The <code>{props.component}</code> 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).
+
+</>
diff --git a/packages/documentation/src/stories/components/accordion/accordion.docs.mdx b/packages/documentation/src/stories/components/accordion/accordion.docs.mdx
@@ -2,6 +2,7 @@ import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as accordionStories from './accordion.stories';
 import * as accordionItemStories from './accordion-item.stories';
 import SampleCustomTrigger from './accordion-custom-trigger.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={accordionStories} />
 
@@ -27,10 +28,7 @@ It is used to manage how content is shown and hidden across a set of collapsible
 
 <Controls of={accordionItemStories.Default} />
 
-## Installation
-
-The `<post-accordion>` 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).
+<ComponentsPackageInstall component="<post-accordion>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/components/avatar/avatar.docs.mdx b/packages/documentation/src/stories/components/avatar/avatar.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as AvatarPictureStories from './avatar.stories';
 import AvatarSample from './avatar.sample.scss?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={AvatarPictureStories} />
 
@@ -17,6 +18,8 @@ import AvatarSample from './avatar.sample.scss?raw';
 <Canvas of={AvatarPictureStories.Default} sourceState="shown" />
 <Controls of={AvatarPictureStories.Default} />
 
+<ComponentsPackageInstall component="<post-avatar>" />
+
 ## Interactive Wrapper Element
 
 ### Anchor
diff --git a/packages/documentation/src/stories/components/back-to-top/back-to-top.docs.mdx b/packages/documentation/src/stories/components/back-to-top/back-to-top.docs.mdx
@@ -1,6 +1,7 @@
 import { Meta, Source } from '@storybook/addon-docs/blocks';
 import * as BackToTopStories from './back-to-top.stories.ts';
 import BackToTop from './back-to-top.sample.html?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={BackToTopStories} />
 
@@ -22,10 +23,7 @@ import BackToTop from './back-to-top.sample.html?raw';
   the Back to Top button.
 </post-banner>
 
-## Installation
-
-The `<post-back-to-top>` 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).
+<ComponentsPackageInstall component="<post-back-to-top>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/components/banner/banner.docs.mdx b/packages/documentation/src/stories/components/banner/banner.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as BannerStories from './banner.stories';
 import BannerDismissSample from './banner-dismiss.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={BannerStories} />
 
@@ -19,10 +20,7 @@ import BannerDismissSample from './banner-dismiss.sample?raw';
 
 <Controls of={BannerStories.Default} />
 
-## Installation
-
-The `<post-banner>` 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).
+<ComponentsPackageInstall component="<post-banner>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/components/breadcrumb/breadcrumbs.mdx b/packages/documentation/src/stories/components/breadcrumb/breadcrumbs.mdx
@@ -1,5 +1,6 @@
 import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
 import * as BreadcrumbsStories from './breadcrumbs.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={BreadcrumbsStories} />
 
@@ -20,6 +21,8 @@ The `<post-breadcrumbs>` is a container for `<post-breadcrumb-item>` components,
 <Canvas of={BreadcrumbsStories.Default} sourceState="shown" />
 <Controls of={BreadcrumbsStories.Default} />
 
+<ComponentsPackageInstall component="<post-breadcrumbs>" />
+
 ## Concatenated Breadcrumbs
 
 When space is constrained, the `<post-breadcrumbs>` concatenates middle items into a dropdown menu.
diff --git a/packages/documentation/src/stories/components/button-close/button-close.docs.mdx b/packages/documentation/src/stories/components/button-close/button-close.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as CloseButtonStories from './button-close.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={CloseButtonStories} />
 
@@ -20,3 +21,5 @@ The value inside the `<post-closebutton>` element will be rendered inside the bu
 <div className="hide-col-default">
   <Controls of={CloseButtonStories.Default} />
 </div>
+
+<ComponentsPackageInstall component="<post-closebutton>" />
diff --git a/packages/documentation/src/stories/components/card-control/card-control.docs.mdx b/packages/documentation/src/stories/components/card-control/card-control.docs.mdx
@@ -6,6 +6,7 @@ import firefoxFallbackSnippet from './standard-html/card-control-firefox-fallbac
 
 import * as CardControlStories from './web-component/card-control.stories';
 import SampleCardControlMethods from './web-component/card-control-methods.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={CardControlStories} />
 
@@ -80,9 +81,7 @@ import SampleCardControlMethods from './web-component/card-control-methods.sampl
 <Canvas of={CardControlStories.Default} sourceState="shown" />
 <Controls of={CardControlStories.Default} />
 
-    ## Installation
-
-    The `<post-card-control>` element is part of the `@swisspost/design-system-components` package. For more information, read the <a href="/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs">getting started with components guide</a>.
+    <ComponentsPackageInstall component="<post-card-control>" />
 
     ## Examples
 
diff --git a/packages/documentation/src/stories/components/collapsible/collapsible.docs.mdx b/packages/documentation/src/stories/components/collapsible/collapsible.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as CollapsibleStories from './collapsible.stories';
 import SampleCustomTrigger from './collapsible-custom-trigger.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={CollapsibleStories} />
 
@@ -14,6 +15,8 @@ Collapsing an element will animate the height from its current value to 0.
 <Canvas sourceState="shown" of={CollapsibleStories.Default} />
 <Controls of={CollapsibleStories.Default} />
 
+<ComponentsPackageInstall component="<post-collapsible>" />
+
 ## Examples
 
 The following examples show different use cases for the `<post-collapsible>` component.
diff --git a/packages/documentation/src/stories/components/dialog/dialog.stories.ts b/packages/documentation/src/stories/components/dialog/dialog.stories.ts
@@ -4,6 +4,7 @@ import { html, nothing } from 'lit-html';
 const meta: Meta = {
   id: '562eac2b-6dc1-4007-ba8e-4e981cef0cbc',
   title: 'Components/Dialog',
+  tags: ['package:Styles'],
   parameters: {
     design: {
       type: 'figma',
diff --git a/packages/documentation/src/stories/components/footer/footer.docs.mdx b/packages/documentation/src/stories/components/footer/footer.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as FooterStories from './footer.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={FooterStories}/>
 
@@ -15,5 +16,6 @@ Internally the `<post-footer>` component has a fix structure, but it offers a nu
 
 
 <Canvas of={FooterStories.Default} />
+<Controls of={FooterStories.Default} />
 
-<Controls of={FooterStories.Default} />
+<ComponentsPackageInstall component="<post-footer>" />
diff --git a/packages/documentation/src/stories/components/header/header.docs.mdx b/packages/documentation/src/stories/components/header/header.docs.mdx
@@ -2,6 +2,7 @@ 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 ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={HeaderStories} />
 
@@ -30,10 +31,7 @@ It is divided into two sections:
   <Controls of={HeaderStories.Default} />
 </div>
 
-## Installation
-
-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).
+<ComponentsPackageInstall component="<post-header>" />
 
 <StylesPackageImport components={['header', 'list', 'button']} />
 
diff --git a/packages/documentation/src/stories/components/language-switch/language-switch.docs.mdx b/packages/documentation/src/stories/components/language-switch/language-switch.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as languageSwitchStories from './language-switch.stories';
 import { PostBanner } from '@swisspost/design-system-components-react';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={languageSwitchStories} />
 
@@ -29,10 +30,7 @@ import { PostBanner } from '@swisspost/design-system-components-react';
   </p>
 </PostBanner>
 
-## Installation
-
-The `<post-language-switch>` 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).
+<ComponentsPackageInstall component="<post-language-switch>" />
 
 ## Links
 
diff --git a/packages/documentation/src/stories/components/linkarea/linkarea.docs.mdx b/packages/documentation/src/stories/components/linkarea/linkarea.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as linkareaStories from './linkarea.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={linkareaStories} />
 
@@ -14,6 +15,4 @@ The <code>post-linkarea</code> component allows only one interactive element to
   <Controls of={linkareaStories.Default} />
 </div>
 
-## Installation
-
-The `<post-linkarea>` 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).
+<ComponentsPackageInstall component="<post-linkarea>" />
diff --git a/packages/documentation/src/stories/components/popover/popover.docs.mdx b/packages/documentation/src/stories/components/popover/popover.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as PopoverStories from './popover.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={PopoverStories} />
 
@@ -16,8 +17,4 @@ import * as PopoverStories from './popover.stories';
 <Canvas sourceState="shown" of={PopoverStories.Default} />
 <Controls of={PopoverStories.Default} />
 
-## Installation
-
-<div>
-  The `<post-popover>` 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).
-</div>
+<ComponentsPackageInstall component="<post-popover>" />
diff --git a/packages/documentation/src/stories/components/rating/post-rating.docs.mdx b/packages/documentation/src/stories/components/rating/post-rating.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as RatingStories from './post-rating.stories';
 import SampleEvents from './post-rating.events.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={RatingStories} />
 
@@ -17,10 +18,7 @@ interactive and visually appealing way to gather and display user feedback.</p>
 <Canvas of={RatingStories.Default} sourceState='shown'/>
 <Controls of={RatingStories.Default} />
 
-## Installation
-
-The `<post-rating/>` element is part of the `@swisspost/design-system-components` package.
-For more information, read the <a href="/?path=/docs/edfb619b-fda1-4570-bf25-20830303d483--docs">getting started with components guide</a>.
+<ComponentsPackageInstall component="<post-rating>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/components/tabs/tabs.docs.mdx b/packages/documentation/src/stories/components/tabs/tabs.docs.mdx
@@ -2,6 +2,7 @@ import { Canvas, Controls, Meta, Source } from '@storybook/addon-docs/blocks';
 import * as TabStories from './tabs.stories';
 import SampleTabChange from './tabs-tab-change.sample?raw';
 import SampleCustomTrigger from './tabs-custom-trigger.sample?raw';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={TabStories} />
 
@@ -18,6 +19,8 @@ import SampleCustomTrigger from './tabs-custom-trigger.sample?raw';
 
 <Controls of={TabStories.Default} />
 
+<ComponentsPackageInstall component="<post-tabs>" />
+
 ## Examples
 
 ### Initially Active Tab
diff --git a/packages/documentation/src/stories/components/togglebutton/togglebutton.docs.mdx b/packages/documentation/src/stories/components/togglebutton/togglebutton.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as toggleButtonStories from './togglebutton.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={toggleButtonStories} />
 
@@ -12,9 +13,7 @@ import * as toggleButtonStories from './togglebutton.stories';
   <Controls of={toggleButtonStories.Default} />
 </div>
 
-## Installation
-
-The `<post-togglebutton>` 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).
+<ComponentsPackageInstall component="<post-togglebutton>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/components/tooltip/tooltip.docs.mdx b/packages/documentation/src/stories/components/tooltip/tooltip.docs.mdx
@@ -1,6 +1,7 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as TooltipStories from './tooltip.stories';
 import * as TooltipTriggerStories from './tooltip-trigger.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={TooltipStories} />
 
@@ -14,6 +15,8 @@ import * as TooltipTriggerStories from './tooltip-trigger.stories';
 <Canvas sourceState="shown" of={TooltipStories.Default} />
 <Controls of={TooltipStories.Default} />
 
+<ComponentsPackageInstall component="<post-tooltip>" />
+
 ## `<post-tooltip-trigger>`
 
 The `<post-tooltip-trigger>` component enables you to show tooltips with customizable delay.
diff --git a/packages/documentation/src/stories/foundations/icons/icon.docs.mdx b/packages/documentation/src/stories/foundations/icons/icon.docs.mdx
@@ -3,6 +3,7 @@ import * as IconStories from './icon.stories';
 import SampleMixin from './mixin.sample.scss?raw';
 import { POST_ICONS_COUNT, UI_ICONS_COUNT, Search } from './search/search-icons.blocks';
 import './icon.styles.scss';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={IconStories} />
 
@@ -19,12 +20,7 @@ import './icon.styles.scss';
 <post-tabs active-panel="search">
   <post-tab-header panel="installation">Installation</post-tab-header>
   <post-tab-panel name="installation">
-    ## Installation
-
-    ### Icon Component
-
-    The `<post-icon>` 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).
+    <ComponentsPackageInstall subtitle="Icon Component" component="<post-icon>" />
 
     ### Icon SVGs
 
diff --git a/packages/documentation/src/stories/raw-components/language-option/language-option.docs.mdx b/packages/documentation/src/stories/raw-components/language-option/language-option.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as languageOptionStories from './language-option.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={languageOptionStories} />
 
@@ -15,10 +16,7 @@ import * as languageOptionStories from './language-option.stories';
 
 <Controls of={languageOptionStories.Default} />
 
-## Installation
-
-The `<post-language-option>` 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).
+<ComponentsPackageInstall component="<post-language-option>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/raw-components/list/list.docs.mdx b/packages/documentation/src/stories/raw-components/list/list.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/addon-docs/blocks';
 import * as ListStories from './list.stories';
+import ComponentsPackageInstall from '@/shared/components-package-install.mdx';
 
 <Meta of={ListStories} />
 
@@ -15,10 +16,7 @@ The `<post-list>` is a container for `<post-list-item>` components.
 
 <Controls of={ListStories.Default} />
 
-## Installation
-
-The `<post-list>` 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).
+<ComponentsPackageInstall component="<post-list>" />
 
 ## Examples
 
diff --git a/packages/documentation/src/stories/raw-components/logo/logo.docs.mdx b/packages/documentation/src/stories/raw-components/logo/logo.docs.mdx
diff --git a/packages/documentation/src/stories/raw-components/megadropdown/megadropdown.docs.mdx b/packages/documentation/src/stories/raw-components/megadropdown/megadropdown.docs.mdx
diff --git a/packages/documentation/src/stories/raw-components/menu-button/menu-button.docs.mdx b/packages/documentation/src/stories/raw-components/menu-button/menu-button.docs.mdx

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@swisspost/design-system-documentation': patch
 +---
++
 +Added common installation instructions on every web component documentation page.