# Designsystem

Das Frontend verwendet ein eigenes, schlankes Designsystem ohne externe
UI-Library. Es besteht aus zentralen CSS Custom Properties, globalen
Grundklassen und wenigen Angular-UI-Komponenten unter
`apps/frontend/src/app/shared/ui`.

## Prinzipien

- sachliche Business-Oberflaeche statt Marketing-Optik
- mobile first, keine globale Mindestbreite
- klare Hierarchie durch Typografie, Abstand und Rahmen
- Farben immer semantisch ueber Tokens
- sichtbare Fokuszustaende und grosse Touch-Flaechen
- Komponenten nur dort, wo sie Verhalten oder Wiederverwendung bringen

## Tokens

Die Tokens liegen in `apps/frontend/src/styles/_tokens.scss` und werden ueber
`apps/frontend/src/styles.scss` eingebunden.

Wichtige Gruppen:

- Farben: `--color-primary`, `--color-danger`, `--color-surface`,
  `--color-text-primary`, `--color-border`, `--color-focus`
- Abstaende: `--space-1` bis `--space-9`
- Typografie: `--font-size-xs` bis `--font-size-2xl`, `--line-height-*`,
  `--font-weight-*`
- Layout: `--container-width`, `--sidebar-width`, `--header-height`,
  `--touch-target`, `--input-height`, `--button-height`
- Oberflaeche: `--radius-*`, `--shadow-*`, `--z-*`, `--transition-*`

Feature-Komponenten duerfen keine direkten Hex-Farben enthalten. Neue Farben
werden zuerst als semantische Tokens angelegt.

## Globale Klassen

Globale Klassen sind bewusst begrenzt:

- Layout: `.ui-page`, `.ui-page-header`, `.ui-grid`, `.ui-card`,
  `.ui-toolbar`, `.ui-actions`
- Formulare: `.ui-form`, `.ui-form-field`, `.ui-control`, `.ui-checkbox`,
  `.ui-field-error`
- Buttons: `.ui-button`, `.ui-icon-button`
- Tabellen: `.ui-table-wrap`, `.ui-table`
- Status: `.ui-badge`, `.ui-badge--success`, `.ui-badge--warning`,
  `.ui-badge--danger`, `.ui-badge--info`
- Utilities: `.visually-hidden`, `.truncate`, `.stack`, `.cluster`,
  `.full-width`, `.text-muted`

Keine neuen Utility-Klassen einfuehren, wenn eine lokale Klasse oder bestehende
UI-Komponente ausreicht.

## Angular-Komponenten

Wiederverwendbare UI-Bausteine:

- `UiButtonComponent`
- `UiIconComponent`
- `UiIconButtonComponent`
- `UiFormFieldComponent`
- `UiStatusBadgeComponent`
- `UiConfirmDialogComponent`
- `ToastService` und `UiToastHostComponent`
- `UiEmptyStateComponent`
- `UiLoadingStateComponent`
- `UiPaginationComponent`
- `UiPageHeaderComponent`

Neue Feature-Seiten sollen diese Bausteine bevorzugen, wenn sie Button-, Badge-,
Dialog-, Toast-, Empty-, Loading- oder Pagination-Verhalten brauchen.

## Responsive Regeln

- Mobile Layouts sind einspaltig.
- Aktionen duerfen mobil untereinander stehen und volle Breite nutzen.
- Business-Listen werden mobil als Karten dargestellt.
- Tabellen liegen in `.ui-table-wrap`, wenn eine echte Tabelle sinnvoll bleibt.
- Touch-Ziele orientieren sich an `--touch-target`.
- Breakpoints werden in rem formuliert und nicht nach Geraetetyp benannt.

## Accessibility

- native HTML-Elemente vor ARIA verwenden
- interaktive Elemente sind Buttons oder Links
- sichtbare Fokuszustaende nicht entfernen
- Labels ersetzen Placeholder nicht
- Fehlertexte stehen direkt am Feld
- Status ist nicht nur Farbe, sondern auch Text/Marker
- Dialoge setzen Fokus, schliessen per Escape und geben Fokus zurueck
- Navigation und Drawer sind per Tastatur bedienbar
- Animationen respektieren `prefers-reduced-motion`

## Entwicklungsseite

Die interne Referenzseite liegt unter:

```text
/dev/design-system
```

Sie ist mit `devOnlyGuard` geschuetzt und im Production-Modus nicht matchbar.
Sie ersetzt kein Storybook, sondern zeigt die vorhandenen Tokens und Komponenten
innerhalb der echten Anwendung.

## Regeln fuer neue UI

1. Bestehende UI-Komponenten oder globale Klassen wiederverwenden.
2. Keine direkte Hex-Farbe in Feature-Komponenten.
3. Keine neue UI-Library einfuehren.
4. Keine tiefen Selektoren, kein `::ng-deep`, kein unkontrolliertes
   `!important`.
5. Keine klickbaren `div`-Elemente als Ersatz fuer Buttons oder Links.
6. Verhalten mit Vitest testen, insbesondere Accessibility-relevante Zustaende.