hr-design-system-handlebars 1.11.12 → 1.12.0

package/src/stories/conventions-and-datastructure.mdx

@@ -4,6 +4,18 @@ import { Meta, Canvas } from '@storybook/addon-docs'
 
 # Konventionen und Datenstrukturen
 
+-   [Übersicht](#übersicht)
+-   [Aufbau der Datenstruktur des Designsystems](#aufbau-der-datenstruktur-des-designsystems)
+-   [Namenskonventionen](#namenskonventionen)
+    -   [Stories](#stories)
+    -   [Handlebar-Komponenten](#handlebar-komponenten)
+    -   [JSON](#json)
+-   [Konventionen beim Bau von Komponenten](#konventionen-beim-bau-von-komponentenn)
+    -   [Styling von Komponenten](#styling-von-komponenten)
+    -   [Wiederverwendbarkeit und Erweiterbarkeit von Komponenten](#wiederverwendbarkeit-und-erweiterbarkeit-von-komponenten)
+
+## Übersicht
+
 Dieses Kapitel richtet sich vor allem an die Entwickler des Designsystems. Es erläutert den grundlegenden Aufbau der Datenstruktur und legt Konventionen für die Benennung von Dateien fest.
 
 ## Aufbau der Datenstruktur des Designsystems
@@ -159,7 +171,11 @@ svg_optimization.stories.mdx`}
     </pre>
 </div>
 
-### Handlebar Komponenten
+### Handlebar-Komponenten
+
+Bei der Erstellung von Handlebar-Komponenten müssen verschiedenen Namenskonvention eingehalten werden.
+
+#### Namen von Komponenten
 
 Für die Namen von Handlebar-Komponenten gelten die gleichen Regeln wie für Stories.
 
@@ -192,8 +208,11 @@ Namen und deren einzelnen Bestandteile sind immer auszuschreiben. Abkürzungen s
     <pre class="!bg-white !p-4 !leading-8">{`brand_navigation_item.hbs`}</pre>
 </div>
 
+#### Namen von Komponenten-Parametern
+
 Die Namen von Parametern in Handlebar-Komponenten sind, anders als der Datainame, in
-[Camel-Case](https://en.wikipedia.org/wiki/Camel_case) Notation zu schreiben.
+[Camel-Case](https://en.wikipedia.org/wiki/Camel_case) Notation zu schreiben und mit einem Unterstrich
+zu prefixen.
 
 <div class="bg-red-200 !mt-4 p-4">
     <h4 class="!text-red-900 font-bold">Falsch</h4>
@@ -204,11 +223,58 @@ Die Namen von Parametern in Handlebar-Komponenten sind, anders als der Datainame
 <div class="bg-green-200 !mt-4 p-4">
     <h4 class="!text-green-900 font-bold">Korrekt</h4>
     <pre class="!bg-white !p-4 !leading-8">
-        &#123;&#123;#>components/base/link cssClasses="" isAriaHidden=true
-        clickLabelPrefix2="mediaLink"&#125;&#125;
+        &#123;&#123;#>components/base/link _cssClasses="" _isAriaHidden=true
+        _clickLabelPrefix2="mediaLink"&#125;&#125;
     </pre>
 </div>
 
+#### Namen übergebener Komponenten-Parameter in Partial-Blocks und Inline-Partials
+
+Sollen an Subkomponenten, die in Partial-Blocks und/oder Inline-Partials aufgerufen werden Komponenten-Parameter der Parent-Komponente
+übergeben werden, muss an die Namen der zu übergebenden Parameter das Postfix `-adjust_context` angefügt werden.
+Dies ist leider notwendig, da [Handlebars.js](https://handlebarsjs.com) und [Handlebars.java](https://github.com/jknack/handlebars.java)
+innerhalb von Partial-Blocks und Inline-Partials die Datenkontexte anders auflösen. Der Wert des Parameters `_css` kann in
+Handlebars.js direkt, in Handlebars.java aber nur ausgelesen werden, wenn mittels `../../_css` zwei Ebenen nach oben gegangen wird.
+Durch setzen des Postfixes `-adjust_context` können mittels eines Gulp-Skriptes diese Vatriablen in Komponenten herausgefiltert werden
+und je nachdem wofür gerade gebaut wird der Kontext automatisiert angepasst werden oder nicht. Hierzu ein kurzes Beispiel.
+
+```handlebars
+{{#with this}}
+    {{> components/base/image/icon _icon="play_button" _addClass="text-media-button fill-white hover:fill-media-button w-10 h-10 inline"}}
+    {{#*inline "css"~}}
+        {{~> components/button/utilities/button_on_image_classes _isMobile1to1=_isMobile1to1-adjust_context}}
+    {{/inline}}
+{{/with}}
+```
+
+Dem Play-Button Icon werden hier in einem Inline-Partial mit der [Style-Komponente](#setzen-kontextabhängiger-css-klassen-mit-style-komponenten)
+`button_on_image_classes` zusätzliche CSS Klassen übergeben. Je nach Wert des Parameters `_isMobile1to1` werden darin unterschiedliche CSS Klassen gesetzt.
+Der Wert dieses Parameters kommt in diesem Beispiel aus einem Parameter gleichen Namens aus dem Parent-Kontext. Damit dieser korrekt von
+den unterschiedlichen Handlebars Implementierungen aufgelöst werden kann, hat er den Postfix `-adjust_context` erhalten. Das oben angesprochene
+Gulp-Skript filtert diesen Parameter jetzt heraus und macht daraus, wenn Storybook mit `yarn storybook` lokal ausgeführt wird wieder den Parameter `_isMobile1to1`.
+
+```handlebars
+{{#with this}}
+    {{> components/base/image/icon _icon="play_button" _addClass="text-media-button fill-white hover:fill-media-button w-10 h-10 inline"}}
+    {{#*inline "css"~}}
+        {{~> components/button/utilities/button_on_image_classes _isMobile1to1=_isMobile1to1}}
+    {{/inline}}
+{{/with}}
+```
+
+Anders verhält es sich, wenn mit `yarn build` das Designsystem für die Verwendung im Delivery gebaut wird (dieses Skript wird beim bauen eines Releases
+in Github aufgerufen). Der Parameter `_isMobile1to1-adjust_context` wird jetzt durch `../../_isMobile1to1` ersetzt, sodass auch im Kontext von Handlebars.java
+der Wert des Parameters korrekt ausgelesen werden kann.
+
+```handlebars
+{{#with this}}
+    {{> components/base/image/icon _icon="play_button" _addClass="text-media-button fill-white hover:fill-media-button w-10 h-10 inline"}}
+    {{#*inline "css"~}}
+        {{~> components/button/utilities/button_on_image_classes _isMobile1to1=../../_isMobile1to1}}
+    {{/inline}}
+{{/with}}
+```
+
 ### JSON
 
 Im Designsystem werden Testdaten für Komponenten mittels JSON-Dateien bereitgestellt. Auch diese Dateinamen werden in Snake-Case Notation
@@ -238,3 +304,150 @@ sofern sie aus mehreren Worten zusammengesetzt werden, mit Minus voneinander get
 |— navigation-flyout`}
     </pre>
 </div>
+
+## Konventionen beim Bau von Komponenten
+
+Bei der Entwicklung neuer Komponenten müssen einige Konventionen beachtet werden.
+
+### Styling von Komponenten
+
+Zum Styling von Komponenten verwenden wir das CSS Framework [Tailwind CSS](https://tailwindcss.com/). Tailwind CSS
+ist ein auf dem Utility-First Ansatz basierendes Framework. Für nahezu jede CSS Eigenschaft gibt es eine eigene
+Utility Klasse, mit deren Hilfe die Styles einer Komponente im HTML Markup zusammengesetzt werden. Anstatt
+wie üblich Klassen mit beliebig vielen CSS Eigenschaften zu erstellen, setzen Tailwind CSS Klassen in der Regel
+immer nur jeweils eine einzelne Style Eigenschaft. Auf diese Weise wird ein sehr hohes Maß an Wiederverwendung
+erreicht und die Dateigröße der ausglieferten CSS Dateien ist in der Regel deutlich kleiner als beim klassischen
+Ansatz mit mehreren CSS Eigenschaften pro Klasse.
+Nachteil ist jedoch, dass alle CSS Logik auf diese Weise in die Templates verlagert wird und diese auf den ersten
+Blick recht unübersichtlich wirken können.
+
+#### Definition eigener CSS Klassen
+
+Tailwind CSS gestattet es auch sehr einfach eigene CSS Klassen zu schreiben. Sollte es für eine bestimmte CSS Eigenschaft
+noch keine eigene Utility Klasse geben, kann diese problemlos in der Datei `custom-utilities.css` definiert werden.
+Auch ist es möglich in der Datei `custom-components.css` eigene, vom Utility-First Ansatz abweichende, Klassen zu schreiben.
+
+Von dieser Möglichkeit sollte aber nur in Ausnahmefällen gebrauch gemacht werden, da ansonsten der Vorteil der kleinen Dateigrößen
+sehr schnell zunichte gemacht werden kann.
+
+#### Setzen Kontextabhängiger CSS Klassen mit Style-Komponenten
+
+An vielen Stellen im Design System müssen CSS Klassen abhängig vom Kontext, in dem die zu stylende Komponente genutzt wird, gesetzt
+werden. Ein Beispiel dafür sind Teaser auf Übersichtsseiten. Wie diese auf der Webseite angezeigt werden sollen, können Redakteure
+auf der Webseite durch setzen entsprechender Parameter dynamisch festlegen.
+Mit der Verwendung von Tailwind CSS und dem Einsatz von Utility Klassen, verlagert sich die ganze Logik aus den CSS Dateien in die
+Komponenten. Als Best-Practice haben sich hierfür separate, ausschließlich CSS Klassen setzende, Handlebar-Komponenten (Style-Komponenten) herausgestellt.
+Diesen Komponenten werden die von den Redakteuren im CMS vorgenommenen Einstellungen als Parameter übergeben. Abhängig von deren Wert
+werden die entsprechenden CSS Utility Klassen gesetzt. Style-Komponenten können beliebig oft und an beliebigen Stellen wiederverwendet werden.
+
+### Wiederverwendbarkeit und Erweiterbarkeit von Komponenten
+
+Damit nicht bei jeder neuen Anforderung das Rad neu erfunden werden muss, ist es wichtig, dass
+beim Bau von Komponenten auf ein hohes Maß an Wiederverwendbarkeit sowie eine
+gute und einfache Erweiterbarkeit geachtet wird.  
+Komponenten sollten demgemäß möglichst einfach gehalten und nicht mit einer vielzahl an Features überladen werden.
+
+Ein gutes Beispiel, wie man es nicht machen sollte ist die Button-Komponente. Bei ihr wurde versucht alle Anforderungen,
+die an einen Button gestellt wurden in einer einzigen Komponente abzubilden. Dies ging bei den initialen Anforderungen
+noch halbwegs, aber je mehr zusätzliche Anforderungen und Features im Laufe der Zeit hinzukamen, desto unübersichtlicher
+und schlechter wartbar wurde die Komponente. Am Ende hatte die Komponente fast zwanzig Parameter, mit denen ihr Verhalten
+gesteuert werden konnte und sie war zu einem richtigen "Monster" angewachsen.
+Aus diesem Grund wurde sie umgebaut und vereinfacht. Gemäß dem Prinzip der "[Component Selfishness](https://www.smashingmagazine.com/2023/01/key-good-component-design-selfishness/)"
+rendert die Komponente nur noch den Rahmen eines Buttons. Alle Inhalte, wie das Label oder ein mögliches Icon,
+werden dem Button mit Hilfe von Subkomponenten hinzugefügt.
+
+#### Erweitern von Basis-Komponenten mit Subkomponenten
+
+Um einer Basis-Komponente weitere Inhalte mittels Subkomponenten hinzuzufügen, sieht Handlebars das Konzept der
+sogenannten "[Partial-Blocks}(https://handlebarsjs.com/guide/partials.html#partial-blocks)" vor. Mit `@partial-block`
+stellt Handlebars hierfür ein spezielles Partial bereit. Es erlaubt in einer Basis-Komponente, wie z.B. der Button-Komponente,
+an einer bestimmten Stelle im Markup einen Platzhalter für mögliche Subkomponenten anzugeben.
+Schauen wir uns das ganze anhand der Button-Komponente an.
+
+```handlebars
+<button>
+    {{> @partial-block }}
+</button>
+```
+
+Die Komponente rendert lediglich das Markup des Button-Elements (alle HTML-Properties des Button wurden der besseren Übersichtlichkeit halber an
+dieser Stelle weggelassen) und ruft das `@partial-block` Partial auf. Der Button Komponente können jetzt, wie nachfolgend gezeigt, Subkomponenten hinzugefügt
+werden.
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Icon rechts"}}
+    {{> components/button/components/button_icon _icon="arrow-right" _iconmap="icons"}}
+{{/components/button/button}}
+```
+
+Auf diese Weise ist es möglich neue Funktionen sehr einfach über Subkomponenten hinzuzufügen.
+
+#### Komponenten mit Inline-Partials um zusätzliche Eigenschaften Erweitern
+
+Wie im vorigen Abschnitt erläutert, können Basis-Komponenten mit Hilfe des `@partial-block` Partials
+sehr gut mit Hilfe von Subkomponenten erweitert werden. Sollen jedoch einem von einer Komponente gerenderten HTML-Element
+dynamisch weitere Eigenschaften (z.B. über Style-Komponenten bereitgestellte CSS-Klassen) übergeben werden,
+ist dies auf diesem Wege nicht möglich. Hierfür lassen sich in Handlebars sogenannte [`Inline-Partials`](https://handlebarsjs.com/guide/partials.html#inline-partials)
+nutzen. Deren Gebrauch lässt sich am besten mit einem Beispiel erläutern.
+
+Für den Abonieren-Button in der Podcast-Player-Komponente wird die Button-Komponente verwendet.
+Diese setzt standardmäßig verschiedenen HTML-Properties im HTML-Button-Element. Der Abonieren-Button
+benötigt darüber hinaus weitere HTML-Properties. Diese sind aber so speziell, dass sie nicht der
+Button-Komponente als weitere Standard-HTML-Properties hinzugefügt wurden. Stattdessen wurde mit einem
+`Inline-Partial` die Möglichkeit geschaffen der Button-Komponente dynamisch beliebige weitere HTML-Properties
+zu übergeben.
+
+```handlebars
+<button class="ds-button" {{#> html_properties}}{{/html_properties}}>
+    {{> @partial-block }}
+</button>
+```
+
+Das Beispiel zeigt eine vereinfachte (aus Gründen der Übersichtlichkeit wurden alle anderen HTML-Properties weggelassen)
+Ansicht der Button-Komponente. Innerhalb des HTML-Button-Elements wird hier das Inline-Partial `html_properties`
+aufgerufen. Der Inhalt dieses Partials kann, wie im folgenden Codebeispiel zu sehen, gesetzt werden.
+
+```handlebars
+{{#with this}}
+    {{#> components/button/button _size="md" _disableButtonPress=true}}
+        {{>components/button/components/button_label _label="Abonnieren" _css="flex-1 truncate mr-2" _type="button"}}
+        <span x-cloak x-show="open" class="w-3 h-3">
+            {{> components/base/image/icon _icon='arrow-up' _addClass="flex self-center w-3 h-3 fill-white" }}
+        </span>
+        <span x-show="!open" class="w-3 h-3">
+            {{> components/base/image/icon _icon='arrow-down' _addClass="flex self-center w-3 h-3 fill-white" }}
+        </span>
+    {{/components/button/button}}
+    {{#*inline "html_properties"}}
+    x-ref="button"
+    x-on:click="toggle()"
+    :aria-expanded="open"
+    :aria-controls="$id('dropdown-button')"
+    :class="open ? 'drop-shadow' : ''"
+    data-hr-click-tracking='{"settings": [{"type": "uxAction", "clickLabel": "podcastAbonnieren:ButtonClick"}]}'
+    {{/inline}}
+{{/with}}
+```
+
+Unterhalb des Aufrufs der Button-Komponente wird hier das Inline-Partial `html_properties` implementiert. Ein Inline-Partial
+muss immer in der Form `{{#*inline NAME_DES_PARTIALS}}` aufgerufen werden. Alle Inhalte die zwischen öffnendem und schließenden
+`inline` stehen, werden in der Komponente in der dieses Inline-Partial aufgerufen wird gerendert.
+
+Zu Beachten ist, dass, wie hier im Codebeispiel zu sehen, der Aufruf der Komponente und die Definition des Inline-Partials Von
+einem `with` Block umschlossen werden sollten. Auf diese Weise wird sichergestellt, dass ausschließlich die hier aufgerufene
+Button-Komponente die zusätzlichen Eigenschaften erhält. Würde der `with` Block weggelassen und irgendwo im weitere
+Verlauf der Seite ein weiteres Mal die Button-Komponente aufgerufen, würde auch das HTML-Button-Element in dieser Komponente
+diese zuätzlichen HTML-Properties rendern.
+
+<div class="bg-blue-200 !mt-4 p-4">
+    <h4 class="!text-stone-950 font-bold">Wichtig</h4>
+    <p>
+        Sollen beim Aufruf von Subkomponenten in einem Partial-Block oder einem Inline-Partial
+        Hash-Parameter (`_NAME_DES_PARAMETERS`) der umliegenden Komponente übergeben werden, muss
+        die [hier](#namen-übergebener-komponenten-parameter-in-partial-blocks-und-inline-partials)
+        beschriebene Namenskonvention zwingend eingehalten werden. Aufgrund von Unterschieden beim
+        Auflösen der Kontexte zwischen Handlebars.js und Handlebars.java können andernfalls die
+        Werte der Parameter nicht ausgelesen werden.
+    </p>
+</div>

package/src/stories/views/components/base/image/icon.hbs

@@ -40,7 +40,7 @@ Erklärung / Hinweise / Best Practices für "Accessible SVG":
 
 --}}
 {{#if _icon}}
-<svg class="sb-icon {{~#if _addClass }} {{_addClass}}{{/if}} {{#if _webview}} -webview{{/if}}" role="presentation" aria-hidden="{{defaultIfEmpty _ariaHidden true}}"
+<svg class="sb-icon {{~#if _addClass }} {{_addClass}}{{/if}} {{#if _webview}} -webview{{/if}} {{#>css}}{{/css}}" role="presentation" aria-hidden="{{defaultIfEmpty _ariaHidden true}}"
 {{# if brand}} data-brand="{{brand}}"{{/if}}
         {{~#if _iconTitle }} {{changeRandom~}}
             aria-labelledby="iconTitle--{{getRandom}}"

package/src/stories/views/components/base/link.hbs

@@ -1,3 +1,13 @@
-{{> components/base/link_open _clickLabelPrefix1=_clickLabelPrefix1 _clickLabelPrefix2=_clickLabelPrefix2 _clickLabelType=_clickLabelType _css=_css _doNavigationTracking=_doNavigationTracking _isAriaHidden=_isAriaHidden _isSelected=_isSelected _selectedCssClass=_selectedCssClass}}
+<a {{#with this.link.webviewUrl}}data-webviewurl="{{this}}"{{/with}} href="{{this.link.url}}{{#if this.hasComments}}#commentList{{/if}}"
+    class="sb-link ds-link js-load{{#if _css}} {{_css}}{{/if}} {{#if _isSelected}} {{defaultIfEmpty _selectedCssClass "-current"}}{{/if}}"
+    {{#if _doNavigationTracking}}
+    data-hr-click-tracking='{"settings": [{"type":"uxAction","secondLevelId": "1","clickLabel":"{{_clickLabelType}}{{#if _clickLabelPrefix1}}::{{_clickLabelPrefix1}}{{/if}}::{{_clickLabelPrefix2}}-Link geklickt"}]}'
+    {{/if}}
+    {{#if this.isFileDownload}}
+        {{#with this.trackingData}}data-hr-click-tracking='{"settings": [{"type":"download","secondLevelId": "{{this.link.secondLevelId}}","clickLabel": "{{this.link.pageName}}"}]}'{{/with}}
+    {{/if}}
+    {{#if this.link.isTargetBlank}} target="_blank"  rel="noopener{{#if this.link.hasNoReferrerFlag}} noreferrer{{/if}}"{{/if}}
+    {{#if _isAriaHidden}} aria-hidden="true" tabindex="-1"{{/if}}
+>
     {{~ decorator_body ~}}   
 </a>

package/src/stories/views/components/base/link_open.hbs

@@ -1,13 +1,12 @@
-{{#with this.link}}
-    <a {{#with this.webviewUrl}}data-webviewurl="{{this}}"{{/with}} href="{{this.url}}{{#if ../this.hasComments}}#commentList{{/if}}"
-        class="sb-link js-load{{#if ../_css}} {{../_css}}{{/if}} {{#if ../_isSelected}} {{defaultIfEmpty ../_selectedCssClass "-current"}}{{/if}}"
-        {{#if ../_doNavigationTracking}}
-        data-hr-click-tracking='{"settings": [{"type":"uxAction","secondLevelId": "1","clickLabel":"{{../_clickLabelType}}{{#if ../_clickLabelPrefix1}}::{{../_clickLabelPrefix1}}{{/if}}::{{../_clickLabelPrefix2}}-Link geklickt"}]}'
-        {{/if}}
-        {{#if ../this.isFileDownload}}
-            {{#with ../this.trackingData}}data-hr-click-tracking='{"settings": [{"type":"download","secondLevelId": "{{this.secondLevelId}}","clickLabel": "{{this.pageName}}"}]}'{{/with}}
-        {{/if}}
-        {{#if this.isTargetBlank}} target="_blank"  rel="noopener{{#if this.hasNoReferrerFlag}} noreferrer{{/if}}"{{/if}}
-        {{#if ../_isAriaHidden}} aria-hidden="true" tabindex="-1"{{/if}}
-    >
-{{/with}}  
+<a {{#with this.link.webviewUrl}}data-webviewurl="{{this}}"{{/with}} href="{{this.link.url}}{{#if this.hasComments}}#commentList{{/if}}"
+    class="sb-link ds-link js-load {{#if _isSelected}} {{defaultIfEmpty _selectedCssClass "-current"}}{{/if}}{{#if _css}} {{_css}}{{/if}} {{#> css}}{{/css}}"
+    {{#if _doNavigationTracking}}
+    data-hr-click-tracking='{"settings": [{"type":"uxAction","secondLevelId": "1","clickLabel":"{{_clickLabelType}}{{#if _clickLabelPrefix1}}::{{_clickLabelPrefix1}}{{/if}}::{{_clickLabelPrefix2}}-Link geklickt"}]}'
+    {{/if}}
+    {{#if this.isFileDownload}}
+        {{#with this.trackingData}}data-hr-click-tracking='{"settings": [{"type":"download","secondLevelId": "{{this.link.secondLevelId}}","clickLabel": "{{this.link.pageName}}"}]}'{{/with}}
+    {{/if}}
+    {{#if this.link.isTargetBlank}} target="_blank"  rel="noopener{{#if this.link.hasNoReferrerFlag}} noreferrer{{/if}}"{{/if}}
+    {{#if _isAriaHidden}} aria-hidden="true" tabindex="-1"{{/if}}
+>
+ 

package/src/stories/views/components/base/link_v2.hbs

@@ -0,0 +1,14 @@
+<a {{#with this.link.webviewUrl}}data-webviewurl="{{this}}"{{/with}} href="{{this.link.url}}{{#if this.hasComments}}#commentList{{/if}}"
+    class="sb-link ds-link js-load {{#if _isSelected}} {{defaultIfEmpty _selectedCssClass "-current"}}{{/if}}{{#if _css}} {{_css}}{{/if}} {{#> css}}{{/css}}"
+    {{#if _doNavigationTracking}}
+    data-hr-click-tracking='{"settings": [{"type":"uxAction","secondLevelId": "1","clickLabel":"{{_clickLabelType}}{{#if _clickLabelPrefix1}}::{{_clickLabelPrefix1}}{{/if}}::{{_clickLabelPrefix2}}-Link geklickt"}]}'
+    {{/if}}
+    {{#if this.isFileDownload}}
+        {{#with this.trackingData}}data-hr-click-tracking='{"settings": [{"type":"download","secondLevelId": "{{this.link.secondLevelId}}","clickLabel": "{{this.link.pageName}}"}]}'{{/with}}
+    {{/if}}
+    {{#if this.link.isTargetBlank}} target="_blank"  rel="noopener{{#if this.link.hasNoReferrerFlag}} noreferrer{{/if}}"{{/if}}
+    {{#if _isAriaHidden}} aria-hidden="true" tabindex="-1"{{/if}}
+>
+ 
+    {{> @partial-block }}
+</a>

package/src/stories/views/components/button/button.hbs

@@ -1,30 +1,15 @@
-<button 
-    {{~#if _aria}} aria-label="{{_aria}}"{{/if}} 
-    {{~#if _isButton}} type="button"{{else}} type="submit"{{/if~}} 
+<button
+    {{#if _id}} id="{{_id}}"{{/if}} 
+    class="ds-button {{> components/button/utilities/button_base_classes}} {{> components/button/utilities/button_variation_classes _variant=_variant _onBackground=_onBackground _disableButtonPress=_disableButtonPress}} {{> components/button/utilities/button_dimension_classes _size=_size}}{{#if _css}} {{_css}}{{/if}} {{#> css}}{{/css}}{{#if _openModal}} js-modalButton{{/if}}"
+    {{#if _openModal}} aria-haspopup="true"{{/if}}
+    {{~#if _ariaLabel}} aria-label="{{_ariaLabel}}"{{/if}}
+    type="{{defaultIfEmpty _type "submit"}}"
     {{~#if _name}} name="{{_name}}"{{/if}} 
-    {{~#if _title}} title="{{_title}}"{{/if}} 
-    class="{{_addClass}}{{#if _addClass2}} {{_addClass2}}{{/if}}{{#if _buttonColor}} {{_buttonColor}}{{/if}}{{#if _buttonSpace}} {{> components/button/button_round_classes _teaserSize=_teaserSize _teaserType=_teaserType _isMobile1to1=_isMobile1to1}}{{/if}}{{#if _webview}} -webview{{/if}}"
+    {{~#if _title}} title="{{_title}}"{{/if}}
     {{~#if _value}} value="{{_value}}"{{/if}} 
     {{~#if _alpineClick}} @click="{{_alpineClick}}"{{/if}} 
     {{~#if _x-show}} x-show="{{_x-show}}"{{/if}} 
     {{~#if _noFocus}} tabindex="-1"{{/if}}
->
-    {{~#if _showIcon~}}
-        {{> components/base/image/icon
-                _icon=_icon
-                _iconmap=_iconmap
-                _addClass=_addIconClass
-                _webview=_webview
-                _ariaHidden=false
-                _iconTitle=false
-                _iconDesc=false
-                _iconText=false
-                _overlayIcon=false
-        }}
-    {{/if~}}
-    {{~#if _label~}}
-        <span {{#if _srOnly}}class="sr-only"{{/if}}>
-            {{~_label~}}
-        </span>
-    {{/if~}}
+    {{#> html_properties}}{{/html_properties}}>
+    {{> @partial-block }}
 </button>

package/src/stories/views/components/button/button.mdx

@@ -0,0 +1,186 @@
+import { ArgsTable, Meta, Story, Canvas } from '@storybook/blocks'
+import * as ButtonStories from './button.stories'
+
+<Meta of={ButtonStories} />
+
+# Button
+
+-   [Übersicht](#übersicht)
+-   [Eigenschaften](#eigenschaften)
+-   [Varianten](#varianten)
+-   [Verwendung](#verwendung)
+
+## Übersicht
+
+Buttons erlauben es eine Aktion oder ein Ereignis mit einem Klick auszulösen. Sie werden z.B. in der Navigation einer Tab-Box verwendet, um zwischen
+den unterschiedlichen Tabs umzuschalten oder werden genutzt, um ein ein Modal zu öffnen.
+Soll die Schaltfläche optisch wie ein Button aussehen, bei einem Klick aber eine neue Seite öffnen, darf nicht die Button-Komponente genutzt werden.
+Für diesen Anwendungsfall gibt es mit dem Button-Link eine eigene Komponente. Sie erzeugt technisch ein HTML Link Element,
+das optisch genauso wie ein Button aussieht. Beispiele hierfür sind die Schaltfläche am unteren Rand einer Tab-Box, die es
+ermöglicht auf eine Seite mit weiteren Inhalten zu kommen, die Schaltfläche innerhalb eines Cluster-Teasers, die auf eine Seite mit weiteren Beiträgen verlinkt
+oder die Schaltfläche innerhalb eines Poster-Teasers, die auf den konkreten Inhalt verlinkt.
+
+Die Button-Komponente als solches ist sehr einfach gehalten. Sie stellt nur ein Grundgerüst (ein gestyltes HTML-Button Element) zur Verfügung.
+Alle Inhalte des Buttons, wie das [Label](?path=/docs/komponenten-buttons-komponenten-label--label) oder ein mögliches
+[Icon](?path=/docs/komponenten-buttons-komponenten-icon--icon), können flexibel durch Subkomponenten hinzugefügt werden.
+
+<Canvas>
+    <Story of={ButtonStories.Spielplatz} />
+</Canvas>
+
+## Eigenschaften
+
+<ArgsTable story="Spielplatz" />
+
+## Varianten
+
+Auf einer Inhaltsseite kann mehr als ein Button platziert werden. Um wichtige von weniger wichtigen Aktionen
+unterscheidbar zu machen, sind unterschiedliche optische Varianten und Größen von Buttons zu verwenden.
+
+### Größen
+
+<Canvas>
+    <Story of={ButtonStories.ButtonLg} />
+    <Story of={ButtonStories.ButtonMd} />
+    <Story of={ButtonStories.ButtonSm} />
+</Canvas>
+
+### Button-Arten
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimary} />
+    <Story of={ButtonStories.ButtonSecondary} />
+    <Story of={ButtonStories.ButtonTertiary} />
+</Canvas>
+
+### Button mit Icon <a id="button-icon" />
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconRechts} />
+    <Story of={ButtonStories.ButtonIconLinks} />
+</Canvas>
+
+## Verwendung
+
+Ein Button wird mit der Handlebar Komponente `button` eingebunden. Wie einleitend schon beschrieben, stellt diese
+Komponente lediglich das Grundgerüst eines Buttons dar. Die Beschriftung und/oder ein Icon müssen mit Subkomponenten hinzugefügt
+werden.
+
+<div class="bg-blue-200 !mt-4 p-4">
+  <h4 class="!text-stone-950 font-bold">Hinweis</h4>
+
+  <p>
+    Sowohl die Button-Komponente als auch die Subkomponenten Button-Label und Button-Icon sind
+    standardmäßig bereits gestyled. Das setzen von zusätzlichen Style Klassen über den Parameter{' '}
+    <pre class="inline">\_css</pre> ist zwar bei jeder Komponente möglich, sollte aber nur dann
+    gemacht werden, wenn es gar nicht anders geht.
+  </p>
+</div>
+
+### Button mit Text
+
+Ein Button der Ausprägung `primary` mit Beschriftung wird, wie in folgendem Codebeispiel gezeigt, gebaut.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimary} />
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Primary"}}
+{{/components/button/button}}
+```
+
+### Button mit Text und Icon
+
+Ein Button der Ausprägung `primary` mit einem Label und einem rechts daneben stehenden Icon wird, wie
+in folgendem Codebeispiel gezeigt, gebaut.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconRechts} />
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Icon rechts"}}
+    {{> components/button/components/button_icon _icon="arrow-right" _iconmap="icons"}}
+{{/components/button/button}}
+```
+
+Soll das Icon links vom Label stehen, muss der Aufruf der Subkomponenten einfach vertauscht werden.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonIconLinks} />{' '}
+</Canvas>
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_icon _icon="arrow-left" _iconmap="icons"}}
+    {{> components/button/components/button_label _label="Icon links"}}
+{{/components/button/button}}
+```
+
+Der passende Abstand zwischen Icon und Label wird automatisch per CSS gesetzt.
+
+### Button auf farbigem Hintergund
+
+Soll ein Button auf einem farbigen Hintergrund (bietet sich vor allem bei dunklen Hintergründen an) genutzt werden, kann durch setzen des Parameters
+`_onBackground` eine auf dunkle Hintergründe abgestimmte kontrastreichere optische Variante der Button aktiviert werden.
+
+<Canvas>
+    <Story of={ButtonStories.ButtonPrimaryAufFarbigemHintergrund} />
+    <Story of={ButtonStories.ButtonSecondaryAufFarbigemHintergrund} />
+    <Story of={ButtonStories.ButtonTertiaryAufFarbigemHintergrund} />
+</Canvas>
+
+```handlebars
+{{#> components/button/link_button _size="lg" _onBackground=true}}
+    {{> components/button/components/button_label _label="Primary"}}
+{{/components/button/link_button}}
+```
+
+### Besonderheiten
+
+Die Button-Komponente kann mit [Inline-Partials](?path=/docs/grundlegendes-konventionen-und-datenstrukturen--docs#namen-übergebener-komponenten-parameter-in-partial-blocks-und-inline-partials)
+um zusätzliche HTML-Properties oder in Style-Komponenten ausgelagerte CSS-Klassen erweitert werden.
+
+#### Setzen zusätzlicher HTML Attribute
+
+In manchen Fällen reichen die standardmäßig von der Button-Komponente gesetzten HTML-Attribute nicht aus. Sollen weitere
+Attribute gesetzt werden (z.B. zum Setzen von alpine.js Direktiven), muss dies wie in folgendem Beispiel gezeigt umgesetzt werden.
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Button"}}
+{{/components/button/button}}
+{{#*inline "html_properties"}}
+    x-ref="button"
+    x-on:click="toggle()"
+    :aria-expanded="open"
+    :aria-controls="$id('dropdown-button')"
+    :class="open ? 'drop-shadow' : ''"
+    data-hr-click-tracking='{"settings": [{"type": "uxAction", "clickLabel": "podcastAbonnieren:ButtonClick"}]}'
+{{/inline}}
+```
+
+Dem hier gerenderten HTML-Button werden mit Hilfe des Inline-Partials `html_properties` die Attribute `x-ref`, `x-on`, `:aria-expanded`, `:aria-controls`, `:class`
+sowie `data-hr-click-tracking` hinzugefügt.
+
+#### Setzen von in Subkomponenten ausgelagerte CSS Klassen
+
+Müssen CSS Klassen abhängig von bestimmten Eigenschaften (z.B. Teaser-Größe, Teaser-Art, etc.) gesetzt werden, hat sich mit der Zeit
+als Best-Practice eine Auslagerung der ganzen Logik in Subkomponenten herausgestellt. Um den Inhalt dieser Subkomponenten einer
+anderen Komponente dynamisch zu übergeben, können die bislang genutzten Standard Handlebar Properties (im Kontext der Button Komponente
+`_css`) nicht genutzt werden. Einer solchen Property können ausschließlich Strings übergeben werden. Stattdessen werden auch hierfür
+Inline-Partials eingesetzt.
+
+```handlebars
+{{#> components/button/button _size="lg"}}
+    {{> components/button/components/button_label _label="Button"}}
+{{/components/button/button}}
+{{#*inline "css"}}
+    {{> components/button/utilities/button_on_image_classes _teaserSize=_teaserSize _teaserType=_teaserType _isMobile1to1=_isMobile1to1}}
+{{/inline}}
+```
+
+Über das Inline-Partial `css` können auf diese Weise theoretisch beliebig viele in Subkomponenten ausgelagerte CSS Klassen übergeben werden.