@public-ui/components 1.1.15 → 1.1.16-rc.0

package/doc/breadcrumb.md

@@ -0,0 +1,143 @@
+# Breadcrumb
+
+Mit Hilfe der **Breadcrumb**-Komponente kann der Pfad zur aktuellen Position einer Webseite in einer hierarchischen Struktur dargestellt werden.
+
+## Funktionsweise
+
+Die **Breadcrumb**-Komponente zeigt die aktuelle Position einer Webseite in einer horizontalen Navigationsstruktur an. Das jeweils letzte Element rechts stellt die aktuelle Seite selbst dar.
+Diese ist nicht mit einem link versehen. Alle Elemente links der aktuellen Seite sind mit einem Link auf die verknüpfte Seite versehen.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<div>
+	<kol-breadcrumb _links='[{"_label":"Startseite","_href":"#/"},{"_label":"Unterseite von Startseite","_href":"#/unterseite"}]'></kol-breadcrumb>
+</div>
+```
+
+### Beispiel
+
+<kol-breadcrumb _links='[{"_label":"Startseite","_href":"#/"},{"_label":"Unterseite von Startseite","_href":"#/unterseite"}]'></kol-breadcrumb>
+
+## Verwendung
+
+### Definition der Links
+
+Das Attribut **\_links** erwartet die Übergabe eines JSON-Objekts, aus dem sich der Aufbau der anzuzeigenden Breadcrumb-Pfade ergibt. Das JSON-Objekt übergibt beliebig viele Elemente, die jeweils eine Anzahl an Eigenschaften und Werten bereitstellen.
+
+Jede Eigenschaft und der zugehörige Wert müssen in doppelten Anführungszeichen gesetzt werden.
+
+Einzelne Elemente werden in geschweiften Klammern und durch **Komma** separiert geschrieben.
+
+Das gesamte JSON-Objekt muss in eckigen Klammern an das Attribut **`_links`** übergeben werden.
+
+<b>Folgende Eigenschaften stehen zur Verfügung:</b>
+
+- **`_href`** übergibt den Link, der für dieses Element verwendet werden soll.
+- **`_icon`** (optional) übergibt den Namen des Icon, wenn zusätzlich zum Text des Elements noch ein Icon angezeigt werden soll. Es stehen alle Icons aus der **Icofont-Bibliothek** zur Verfügung
+- **`_iconOnly`** (optional). Wenn der Wert auf **true** gesetzt wird, erscheint im Link ausschließlich das Icon, ohne weiteren Text. Die Eigenschaft `_icon` muss gesetzt werden.
+- **`_label`** übergibt den Text, der für dieses Element angezeigt werden soll.
+- **`_links`** übergibt den Pfadaufbau der Komponente als JSON-Objekt.
+
+Beispiel für ein JSON-Objekt, das an das Attribut **\_links** übergeben wird:
+
+```tsx
+[
+	{
+		_label: 'Startseite',
+		_href: '#/',
+		_icon: 'home',
+		_iconOnly: true,
+	},
+	{
+		_label: '1. Unterseite',
+		_href: '/1_unterseite',
+	},
+	{
+		_label: '2. Unterseite',
+		_href: '/2_unterseite',
+	},
+];
+```
+
+<kol-breadcrumb _links='[{"_label":"Startseite","_href":"#/","_icon":"home","_icon-only": "true"},{"_label":"1. Unterseite","_href":"#/1_unterseite"},{"_label":"2. Unterseite","_href":"#/2_unterseite"}]'></kol-breadcrumb>
+
+### Best practices
+
+- Die **Breadcrumb**-Komponente ist ein wichtiges Element für eine effektive Suchmaschinenoptimierung Ihrer Webseite.
+- Auch für Benutzer:innen der Webseite bietet eine Breadcrumb-Navigation zusätzliche Übersicht.
+- Positionieren Sie die Breadcrumb möglichst weit oben auf Ihren Inhaltsseiten, um zu gewährleisten, dass Suchmaschinen diese als zusätzliche Informationsquelle zur Struktur Ihrer Webseite nutzen können.
+- Positionieren Sie die Breadcrumb-Komponente auf jeder Inhaltsseite Ihre Webseite. Sie gewährleisten so, dass sich Besucher:innen jederzeit zurecht finden und die aktuelle Position erkennen können.
+- Vermeiden Sie, die Breadcrumb-Navigation auf der Startseite zu positionieren.
+- Verwenden Sie eine Breadcrumb-Navigation nur dann, wenn sie für Benutzer:innen einen wirklichen Mehrwert bieten.
+- Auf mobilen Varianten einer Webseite ist eine Breadcrumb-Navigation möglicherweise nicht sinnvoll.
+
+### Anwendungsfälle
+
+Eine Breadcrumb-Navigation ist auf einer großen Mehrzahl der aktuellen Webseiten zu finden. Somit beschreibt der klassische Anwendungsfall den generellen Einbau dieser Komponente.
+
+## Barrierefreiheit
+
+Achten Sie im Sinne der optimalen Barrierefreiheit darauf, das Attribut `_aria-label` korrekt auszuzeichnen. Beachten Sie diesen Hinweis insbesondere dann, wenn Sie die Option `_icon-only` verwenden und so auf einen beschreibenden Text im Link verzichten würden.
+
+Beachten Sie, dass auch das letzte Element in der Breadcrumb-Komponente per Tab-Taste angesprungen werden kann, obwohl dort kein Link hinterlegt ist. Hierdurch kann auch dieses Element von Screenreader erreicht und vorgelesen werden.
+
+### Tastatursteuerung
+
+| Taste   | Funktion                                                     |
+| ------- | ------------------------------------------------------------ |
+| `Tab`   | Springt die einzelnen Elemente der Breadcrumb-Navigation an. |
+| `Enter` | Öffnet den Link des aktuellen Elements.                      |
+
+## Links und Referenzen
+
+- https://www.w3.org/TR/wai-aria-practices/#breadcrumb
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property                  | Attribute     | Description                                                                  | Type                       | Default     |
+| ------------------------- | ------------- | ---------------------------------------------------------------------------- | -------------------------- | ----------- |
+| `_ariaLabel` _(required)_ | `_aria-label` | Gibt den Text an, der die Navigation von anderen Navigationen differenziert. | `string`                   | `undefined` |
+| `_links` _(required)_     | `_links`      | Gibt die geordnete Liste der Seitenhierarchie in Links an.                   | `NavLinkProps[] \| string` | `undefined` |
+
+
+## Shadow Parts
+
+| Part          | Description                                |
+| ------------- | ------------------------------------------ |
+| `"link"`      | Ermöglicht das Stylen der Links.           |
+| `"separator"` | Ermöglicht das Ändern des Separator-Icons. |
+
+
+## Dependencies
+
+### Depends on
+
+- [kol-icon](../icon)
+- [kol-link](../link)
+
+### Graph
+```mermaid
+graph TD;
+  kol-breadcrumb --> kol-icon
+  kol-breadcrumb --> kol-link
+  kol-link --> kol-link-wc
+  kol-link-wc --> kol-span-wc
+  kol-link-wc --> kol-tooltip
+  kol-span-wc --> kol-icon
+  kol-tooltip --> kol-badge
+  kol-badge --> kol-span-wc
+  kol-badge --> kol-button-wc
+  kol-button-wc --> kol-span-wc
+  kol-button-wc --> kol-tooltip
+  style kol-breadcrumb fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+

package/doc/button-group.md

@@ -0,0 +1,107 @@
+# ButtonGroup
+
+**Buttons** dienen dazu, Nutzer:innen Auswahlmöglichkeiten für Aktionen anzuzeigen und diese in einer klaren Hierarchie anzuordnen. Sie helfen den Nutzer:innen, die wichtigsten Aktionen einer Seite oder innerhalb eines Applikation zu finden und ermöglichen es ihm, diese Aktionen auszuführen.
+
+Die **ButtonGroup**-Komponente fasst mehrere Buttons zu einer optischen und funktionalen Einheit zusammen.
+
+## Konstruktion
+
+Die Komponente **ButtonGroup** besteht aus einem Hauptelement `<kol-button-group></kol-button-group>`. In ihm werden beliebig viele **Button**-Komponenten zu einer Gruppe zusammengefasst. Die einzelnen **Buttons** entsprechen in ihrer Konstruktion der Beschreibung
+zur **Button**-Komponente.
+
+### Code
+
+```tsx
+<kol-button-group>
+  <kol-button _label="Speichern" _variant="primary"></<kol-button>
+  <kol-button _label="Speichern & Schließen" _variant="normal"></<kol-button>
+  <kol-button _label="Abbrechen" _variant="secondary"></<kol-button>
+  <kol-button _label="Löschen" _variant="danger"></<kol-button>
+  <kol-button _label="Ghost" _variant="ghost"></kol-button>
+  <kol-button _label="Deaktiviert" _disabled></<kol-button>
+</kol-button-group>
+```
+
+### Beispiel
+
+<kol-button-group> 
+  <kol-button _label="Speichern" _variant="primary"></kol-button>
+  <kol-button _label="Speichern & Schließen" _variant="normal"></kol-button>
+  <kol-button _label="Abbrechen" _variant="secondary"></kol-button>
+  <kol-button _label="Löschen" _variant="danger"></kol-button>
+  <kol-button _label="Ghost" _variant="ghost"></kol-button>
+  <kol-button _label="Deaktiviert" _disabled></kol-button>
+</kol-button-group>
+
+## Verwendung
+
+### Einfache ButtonGroup
+
+Im einfachsten Fall besteht die **ButtonGroup**-Komponente aus einer Liste beschrifteter Schaltflächen. Für die Beschriftung der Buttons wird lediglich das Attribut **`_label="Ihre Beschriftung"`** verwendet.
+
+### ButtonGroup mit Text, Icon und Text mit Icon
+
+Über das Attribut **`_icon="xxx"`** wird festgelegt, ob und welches Icon verwendet werden soll.
+
+Eine Übersicht über die zur Verfügung stehenden Icons in KoliBri finden Sie [hier](https://icofont.com/icons).
+
+Über das Attribut **`_icon-only`** legen Sie fest, ob nur das Icon angezeigt werden soll. Der Inhalt des Attributs **`_label`** wird nicht mehr angezeigt.
+
+### Ausgabe verschiedener Styles für Buttons in der ButtonGroup
+
+Für die Standardausgabe eines Buttons stehen die Werte **primary**, **secondary**, **normal**, **danger** und **ghost** zur Verfügung. Hierüber wird die farbliche Gestaltung des Buttons festgelegt.
+
+### Optische Ausrichtung
+
+Über das Attribut **`_nestled`** kann eine optische Ausrichtung der ButtonGroup bestimmt werden. An der angegebenen Position werden die abgerundeten Ecken entfernt, so dass der Eindruck einer Button-Leiste entsteht. Möglich sind die Werte `bottom`, `top`, `left`und `right`.
+
+### Best practices
+
+- Verwenden Sie eine primäre Schaltfläche für die nächstbeste Aktion. Verbleibende Calls-to-Actions sollten als sekundäre Schaltfläche dargestellt werden.
+- Verwenden Sie Schaltflächen an einheitlichen Stellen in der Benutzeroberfläche, um die Benutzererfahrung zu verbessern.
+- Verwenden Sie nur eine primäre Schaltfläche je Viewport. Auf der gesamten Seite kann ein Button-Style beliebig oft auftreten.
+- Die Beschriftung des Button muss die Aktion beschreiben, die die Schaltfläche ausführt. Sie sollte ein Verb enthalten (z.B. Speichern). Verwenden Sie prägnante, spezifische, selbsterklärende Beschriftungen.
+- Schaltflächenbeschriftungen sollten immer dann auch ein Nomen enthalten, wenn es Raum für Interpretationen darüber gibt, wofür das Verb zuständig ist. Verwenden Sie keine generischen Bezeichnungen wie "OK", insbesondere nicht im Fehlerfall. Fehler sind nie "OK".
+- Wenn Sie mehrere Buttons kombinieren oder anordnen möchten, verwenden Sie die **ButtonGroup**-Komponente.
+- Verwenden Sie nicht mehrere Buttons im Style "primär" in einer **ButtonGroup**.
+- Verwenden Sie Buttons nicht als Link oder als Navigationselement.
+
+## Barrierefreiheit
+
+Bei Verwendung der **ButtonGroup**-Komponente sind keine besonderen Maßnahmen in Bezug auf die barrierefreiheit zu berücksichtigen. Die innerhalb der ButtonGroup enthaltenen **Button**-Komponenten besitzen jedoch einige wichtige Aspekte in diesem Zusammenhang:
+
+- In der Button-Komponente werden die optionalen **Icons** links ausgerichtet, um Nutzer\*innen mit eingeschränktem Sichtfeld eine bessere Bedienbarkeit zu ermöglichen.
+- Die Farben der **Variant-Typen** `primary`, `secondary`, `normal`, `danger` und `ghost` wurden in Hinblick auf bestmöglichen Kontrast gewählt. Die Schriftfarbe ist per default immer weiß.
+
+### Tastatursteuerung
+
+| Taste   | Funktion                                                                       |
+| ------- | ------------------------------------------------------------------------------ |
+| `Tab`   | Springt den einzelnen Button der ButtonGroup an und fokussiert ihn.            |
+| `Enter` | Öffnet den Link des fokussierten Button oder führt dessen onClick-Methode aus. |
+
+## Links und Referenzen
+
+- https://www.w3.org/TR/wai-aria-practices/#button
+
+<!-- Auto Generated Below -->
+
+
+## Dependencies
+
+### Used by
+
+ - [kol-button-group](.)
+ - [kol-tabs](../tabs)
+
+### Graph
+```mermaid
+graph TD;
+  kol-button-group --> kol-button-group-wc
+  kol-tabs --> kol-button-group-wc
+  style kol-button-group-wc fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+

package/doc/button-link.md

@@ -0,0 +1,76 @@
+# ButtonLink
+
+Der ButtonLink ist semantisch ein Button und hat das Design eines Links. Hierzu werden alle relevanten Properties der Button-Komponente übernommen und um die Design-bestimmenden Properties des Links erweitert.
+
+Einen Button kann man deaktivieren und daher gibt es bei einem ButtonLink das Property `_disabled`. Wie das optisch ausgestaltet wird, entscheidet die UX-Designer:in.
+
+Statt, wie bei einem Link, `_href` zu verwenden, wird bei einem ButtonLink das Property über den `Click-Callback` gesteuert. Hierzu wird das `_on`-Property verwendet.
+
+Bei einem Link gibt es das Property `target`, welches ggf. den Link in einem neuen Fenster/Tab öffnet. Das Verhalten ist aktuell noch nicht umgesetzt.
+
+Da der Link, nicht wie der Button, in mehrere Varianten (`primary` oder `secondary` usw.) angeboten wird, stehen die Properties `_customClass` und `_variant` nicht zur Verfügung.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<kol-button-link _on="" _label="Schalter sieht wie ein Link aus"></kol-button-link>
+```
+
+### Beispiel
+
+<div class="flex gap-2">
+  <kol-button-link _on="" _label="Schalter sieht wie ein Link aus"></kol-button-link>
+</div>
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property              | Attribute        | Description                                                                                                                                                                                                                                                                           | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default     |
+| --------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `_accessKey`          | `_access-key`    | Gibt an, mit welcher Tastenkombination man den Button auslösen oder fokussieren kann.                                                                                                                                                                                                 | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_ariaControls`       | `_aria-controls` | Gibt an, welche Elemente kontrolliert werden.  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)                                                                                                                                             | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_ariaCurrent`        | `_aria-current`  | Gibt an, welchen aktuellen Auswahlstatus der Button hat. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)                                                                                                                                    | `"date" \| "location" \| "page" \| "step" \| "time" \| boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `undefined` |
+| `_ariaExpanded`       | `_aria-expanded` | Gibt an, ob durch den Button etwas aufgeklappt wurde. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)                                                                                                                                      | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |
+| `_ariaLabel`          | `_aria-label`    | Gibt einen beschreibenden Text für den Screenreader an. Damit die Sprachsteuerung von interaktiven Elementen funktioniert, muss der Aria-Label-Text mit dem Label-Text des Buttons beginnen.  - https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `''`        |
+| `_ariaSelected`       | `_aria-selected` | Gibt an, ob Element ausgewählt ist (role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected)                                                                                                                                             | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |
+| `_disabled`           | `_disabled`      | Gibt an, ob der Button deaktiviert ist.                                                                                                                                                                                                                                               | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`     |
+| `_icon`               | `_icon`          | Gibt den Class-Identifier eines Icons eine eingebunden Icofont an. (z.B. https://icofont.com/)                                                                                                                                                                                        | `string \| undefined \| { top: string \| KoliBriCustomIcon; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right: string \| KoliBriCustomIcon; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom: string \| KoliBriCustomIcon; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left: string \| KoliBriCustomIcon; }` | `undefined` |
+| `_iconAlign`          | `_icon-align`    | <span class="text-red-500">**[DEPRECATED]**</span> <br/><br/>Gibt an, ob das Icon links oder rechts dargestellt werden soll.                                                                                                                                                             | `"left" \| "right" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `'left'`    |
+| `_iconOnly`           | `_icon-only`     | Gibt an, ob nur das Icon angezeigt wird.                                                                                                                                                                                                                                              | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`     |
+| `_id`                 | `_id`            | Gibt die ID der Schaltfläche an. (Selection, Testing)                                                                                                                                                                                                                                 | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_label` _(required)_ | `_label`         | Gibt einen beschreibenden Text für das Text-Element an.                                                                                                                                                                                                                               | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined` |
+| `_on`                 | --               | Gibt die EventCallback-Funktionen für die Button-Events an.                                                                                                                                                                                                                           | `undefined \| { onClick?: EventCallback<PointerEvent> \| undefined; onMouseDown?: EventCallback<MouseEvent> \| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `undefined` |
+| `_role`               | `_role`          | Gibt an, welche Role der Schalter hat.                                                                                                                                                                                                                                                | `"tab" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |
+| `_tabIndex`           | `_tab-index`     | Gibt an, welchen Tab-Index der Button hat. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)                                                                                                                                                             | `number \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_tooltipAlign`       | `_tooltip-align` | Gibt an, ob der Tooltip oben, rechts, unten oder links angezeigt werden soll.                                                                                                                                                                                                         | `"bottom" \| "left" \| "right" \| "top" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'top'`     |
+| `_type`               | `_type`          | Gibt an, welche Typ der Button hat.                                                                                                                                                                                                                                                   | `"button" \| "reset" \| "submit" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `'button'`  |
+
+
+## Dependencies
+
+### Depends on
+
+- kol-span-wc
+- [kol-tooltip](../tooltip)
+
+### Graph
+```mermaid
+graph TD;
+  kol-button-link --> kol-span-wc
+  kol-button-link --> kol-tooltip
+  kol-span-wc --> kol-icon
+  kol-tooltip --> kol-badge
+  kol-badge --> kol-span-wc
+  kol-badge --> kol-button-wc
+  kol-button-wc --> kol-span-wc
+  kol-button-wc --> kol-tooltip
+  style kol-button-link fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+

package/doc/button.md

@@ -0,0 +1,192 @@
+# Button
+
+**Buttons** dienen dazu, Benutzer:innen Auswahlmöglichkeiten für Aktionen anzuzeigen und diese in einer klaren Hierarchie anzuordnen. Sie helfen Nutzer:innen, die wichtigsten Aktionen einer Seite oder innerhalb eines Viewports zu finden und ermöglichen es ihm, diese Aktionen auszuführen. Die Beschriftung des Buttons wird verwendet, um Nutzer:innen klar anzuzeigen, welche Aktion ausgelöst wird. Buttons ermöglichen es Nutzer:innen, eine Änderung zu bestätigen, Schritte in einer Aufgabe abzuschließen oder Entscheidungen zu treffen.
+
+## Konstruktion
+
+### Code
+
+```tsx
+<kol-button _label="Primary" _variant="primary"></kol-button>
+<kol-button _label="Secondary" _variant="secondary"></kol-button>
+<kol-button _label="Normal" _variant="normal"></kol-button>
+<kol-button _label="Secondary" _variant="danger"></kol-button>
+<kol-button _label="Ghost" _variant="ghost"></kol-button>
+<kol-button _label="Custom" _variant="custom" _custom-class="myClass"></kol-button>
+```
+
+### Beispiel
+
+Default
+
+<div class="flex gap-2">
+  <kol-button _label="Primary" _variant="primary"></kol-button>
+  <kol-button _label="Secondary" _variant="secondary"></kol-button>
+  <kol-button _label="Normal" _variant="normal"></kol-button>
+  <kol-button _label="Danger" _variant="danger"></kol-button>
+  <kol-button _label="Ghost" _variant="ghost"></kol-button>
+  <kol-button _label="Custom" _variant="custom" _custom-class="myClass"></kol-button>
+</div>
+
+Disabled
+
+<div class="flex gap-2">
+  <kol-button _label="Primary" _variant="primary" _disabled></kol-button>
+  <kol-button _label="Secondary" _variant="secondary" _disabled></kol-button>
+  <kol-button _label="Normal" _variant="normal" _disabled></kol-button>
+  <kol-button _label="Danger" _variant="danger" _disabled></kol-button>
+  <kol-button _label="Ghost" _variant="ghost" _disabled></kol-button>
+  <kol-button _label="Custom" _variant="custom" _custom-class="myClass" _disabled></kol-button>
+</div>
+
+## Verwendung
+
+### Beschriftung
+
+Für die eindeutige Beschriftung des Buttons nutzen Sie das Attribut **`_label`**.
+`_label="Buttonbeschriftung"`
+
+### Button mit Icon
+
+Über das Attribut **`_icon`** wird eine JSON-Struktur übergeben, mit der alle Paramater zu Anzeige des Icon im Button festgelegt wird.
+
+```tsx
+_icon =
+	"{'top': {'style': {'font-size': '200%', 'transform': 'rotate(45deg)'}, 'icon': 'fa-solid fa-arrow-up'},'right': {'icon': 'fa-solid fa-arrow-right'},'bottom': {'icon': 'fa-solid fa-arrow-down'},'left': {'icon': 'fa-solid fa-arrow-left'}}";
+```
+
+Es ist möglich, ein Icon an jeder Position des Button anzuzeigen, sowie die Ausgabe mehrerer Icons im Button. Jedes Icon erhält in der JSON-Struktur einen eigenen Abschnitt, in dem seine Properties festgelegt werden.
+
+Jeder Abschnitt beginnt mit der gewünschten Position des Icon im Button:
+
+- top
+- bottom
+- right
+- left
+
+```tsx
+"{'top': {weitere Properties}";
+```
+
+Als weitere Properties zur Konfiguration des Icon stehen zur Verfügung:
+
+- icon: legt das anzuzeigende Icon aus der Icofont-Bibliothek fest.
+
+```tsx
+"{'top': {'icon':'fa-solid fa-arrow-up'}";
+```
+
+- style: übergibt ggfls. eigene CSS-Stylinganweisungen an das Icon, wie z.B. font-size, transform oder color.
+
+```tsx
+"{'top': {'style': {'font-size':'200%','color':'#040404','transform':'rotate(45deg)'},'icon':'fa-solid fa-arrow-up'}";
+```
+
+Eine Übersicht über die zur Verfügung stehenden Icons in KoliBri finden Sie [hier](https://icofont.com/icons)
+
+### Nur Icon im Button anzeigen
+
+In der **Button**-Komponente kann auf die Beschriftung auch verzichtet werden. Hierzu wird das Attribut **`_iconOnly`** gesetzt.
+
+Beachten Sie, dass das Attribut **`_label`** auch dann gesetzt werden muss, wenn nur ein Icon angezeigt werden soll. Die Komponente gibt in diesem Fall drei Punkte (...) als Platzhalter aus.
+
+`_icon-only="true"`
+
+### Style angeben
+
+Die Button-Komponente kann als primärer oder sekundärer Button ausgegeben werden. Zur Steuerung verwenden Sie das Attribut `_variant="primary/secondary/normal/danger/ghost/custom"`. Als Default-Wert wird ein Button als **primary** gerendert.<br/>
+
+Bei Verwendung des Attribut **\_variant="custom"** kann der Entwickler für den Button eigene Styles realisieren. Verpflichtend ist in diesem Fall das Setzen des Attribut **\_custom-class**, damit das Button-Element im Shadow-Dom mittels CSS selektiert werden kann.
+
+### Best practices
+
+- Verwenden Sie eine primäre Schaltfläche für die nächstbeste Aktion. Verbleibende Calls-to-Action sollten als sekundäre Schaltfläche dargestellt werden.
+- Verwenden Sie Schaltflächen an einheitlichen Stellen in der Benutzeroberfläche, um die Benutzererfahrung zu verbessern.
+- Verwenden Sie nur eine primäre Schaltfläche je Viewport. Auf der gesamten Seite kann ein Button-Style beliebig oft auftreten.
+- Die Beschriftung des Button muss die Aktion beschreiben, die die Schaltfläche ausführt. Sie sollte ein Verb enthalten (z.B. Speichern). Verwenden Sie prägnante, spezifische, selbsterklärende Beschriftungen.
+- Schaltflächenbeschriftungen sollten immer dann auch ein Nomen enthalten, wenn es Raum für Interpretationen darüber gibt, wofür das Verb zuständig ist. Verwenden Sie keine generischen Bezeichnungen wie "OK", insbesondere nicht im Fehlerfall. Fehler sind nie "OK".
+- Wenn Sie mehrere Buttons kombinieren oder anordnen möchten, verwenden Sie die **ButtonGroup**-Komponente.
+- Verwenden Sie nicht mehrere Buttons im Style "primär" in einer **ButtonGroup**.
+- Verwenden Sie Buttons nicht als Link oder als Navigationselement.
+
+## Barrierefreiheit
+
+Für Menschen mit einem eingeschränkten Sichtfeld ist die Positionierung des **Icons** im Button links von der Beschriftung optimal (**`_icon-align="left"`**, bzw. kein **`_icon-align`**).
+
+Ebenfalls aus Gründen optimaler Barrierefreiheit verzichtet KoliBri bei der **Button**-Komponente auf den Status **disabled**.
+
+Probleme mit Disabled-Status
+
+- Darstellung Kontraste
+- Möglichkeit des Nutzerfeedbacks
+
+### Tastatursteuerung
+
+| Taste   | Funktion                                                                       |
+| ------- | ------------------------------------------------------------------------------ |
+| `Tab`   | Springt den einzelnen Button an und fokussiert ihn.                            |
+| `Enter` | Öffnet den Link des fokussierten Button oder führt dessen onClick-Methode aus. |
+
+## Links und Referenzen
+
+- https://www.w3.org/TR/wai-aria-practices/#button
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property              | Attribute        | Description                                                                                                                                        | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Default     |
+| --------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `_accessKey`          | `_access-key`    | Gibt an, mit welcher Tastenkombination man den Button auslösen oder fokussieren kann.                                                              | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_ariaControls`       | `_aria-controls` | Gibt an, welche Elemente kontrolliert werden.  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-controls)          | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_ariaCurrent`        | `_aria-current`  | Gibt an, welchen aktuellen Auswahlstatus der Button hat. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current) | `"date" \| "location" \| "page" \| "step" \| "time" \| boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `undefined` |
+| `_ariaExpanded`       | `_aria-expanded` | Gibt an, ob durch den Button etwas aufgeklappt wurde. (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-expanded)   | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |
+| `_ariaLabel`          | `_aria-label`    | Gibt einen beschreibenden Text des Buttons an.  (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label)            | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `''`        |
+| `_ariaSelected`       | `_aria-selected` | Gibt an, ob Element ausgewählt ist (role=tab). (https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-selected)          | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `undefined` |
+| `_customClass`        | `_custom-class`  | Gibt an, welche Custom-Class übergeben werden soll, wenn _variant="custom" gesetzt ist.                                                            | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_disabled`           | `_disabled`      | Gibt an, ob der Button deaktiviert ist.                                                                                                            | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`     |
+| `_icon`               | `_icon`          | Gibt den Class-Identifier eines Icons eine eingebunden Icofont an. (z.B. https://icofont.com/)                                                     | `string \| undefined \| { top: string \| KoliBriCustomIcon; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right: string \| KoliBriCustomIcon; bottom?: string \| KoliBriCustomIcon \| undefined; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom: string \| KoliBriCustomIcon; left?: string \| KoliBriCustomIcon \| undefined; } \| { top?: string \| KoliBriCustomIcon \| undefined; right?: string \| KoliBriCustomIcon \| undefined; bottom?: string \| KoliBriCustomIcon \| undefined; left: string \| KoliBriCustomIcon; }` | `undefined` |
+| `_iconAlign`          | `_icon-align`    | <span class="text-red-500">**[DEPRECATED]**</span> <br/><br/>Gibt an, ob das Icon links oder rechts dargestellt werden soll.                          | `"left" \| "right" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `'left'`    |
+| `_iconOnly`           | `_icon-only`     | Gibt an, ob nur das Icon angezeigt wird.                                                                                                           | `boolean \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`     |
+| `_id`                 | `_id`            | Gibt die ID der Schaltfläche an. (Selection, Testing)                                                                                              | `string \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_label` _(required)_ | `_label`         | Gibt den Label für die Beschriftung der Schaltfläche an.                                                                                           | `string`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `undefined` |
+| `_on`                 | --               | Gibt die EventCallback-Funktionen für die Button-Events an.                                                                                        | `undefined \| { onClick?: EventCallback<PointerEvent> \| undefined; onMouseDown?: EventCallback<MouseEvent> \| undefined; }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `undefined` |
+| `_role`               | `_role`          | Gibt an, welche Role der Schalter hat.                                                                                                             | `"tab" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `undefined` |
+| `_tabIndex`           | `_tab-index`     | Gibt an, welchen Tab-Index der Button hat. (https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/tabindex)                          | `number \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `undefined` |
+| `_tooltipAlign`       | `_tooltip-align` | Gibt an, ob der Tooltip oben, rechts, unten oder links angezeigt werden soll.                                                                      | `"bottom" \| "left" \| "right" \| "top" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `'top'`     |
+| `_type`               | `_type`          | Gibt an, welche Typ der Button hat.                                                                                                                | `"button" \| "reset" \| "submit" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `'button'`  |
+| `_variant`            | `_variant`       | Gibt an, welche Ausprägung der Button hat.                                                                                                         | `"custom" \| "danger" \| "ghost" \| "normal" \| "primary" \| "secondary" \| undefined`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `'normal'`  |
+
+
+## Dependencies
+
+### Used by
+
+ - [kol-nav](../nav)
+ - [kol-pagination](../pagination)
+ - [kol-table](../table)
+
+### Depends on
+
+- kol-button-wc
+
+### Graph
+```mermaid
+graph TD;
+  kol-button --> kol-button-wc
+  kol-button-wc --> kol-span-wc
+  kol-button-wc --> kol-tooltip
+  kol-span-wc --> kol-icon
+  kol-tooltip --> kol-badge
+  kol-badge --> kol-span-wc
+  kol-badge --> kol-button-wc
+  kol-nav --> kol-button
+  kol-pagination --> kol-button
+  kol-table --> kol-button
+  style kol-button fill:#f9f,stroke:#333,stroke-width:4px
+```
+
+----------------------------------------------
+
+