generated from bastian/boilerplate
115 lines
3.9 KiB
Markdown
115 lines
3.9 KiB
Markdown
# 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.
|