Design Systems und deren Dokumentation

1) Was ist ein Designsystem und warum wird es benötigt?

Das Design-System ist eine einzige Quelle der Wahrheit für die Schnittstelle: eine Reihe von Token, Komponenten, Praktiken und Dokumentation, die UX-Vorhersagbarkeit, Entwicklungsgeschwindigkeit und Skalierbarkeit bietet.

• Konsistenz der visuellen und Verhaltensschicht in allen Produkten.
• Geschwindigkeit: Überbeanspruchung der Komponenten, weniger Revue-Kosten.
• Qualität: Allgemeine A11y, Lokalisierung, Tests, Inhaltsstandards.
• Handling: klare Verantwortung, Freigaben, Roadmap.

2) Design-System-Architektur (Schichten)

1. Design-Token (foundation): Farben, Typografie, Größen, Radien, Schatten, Einzüge, Zustände sowie semantische Token ('color. surface. warning`, `space. xs`).
2. UI-Komponenten: Buttons, Eingabefelder, Modalfenster, Dropdowns, Tabellen, Toast, Banner, Alerts, Leerzustände, Skeletons.
3. Muster und Kompositionen: KYC-Formulare, Payment-Flows, Null-Ergebnisse, Schritt-für-Schritt-Assistenten, Inhaltskarten.
4. Content-Hyde (Microcopy): Ton, Begriffswörterbuch, Fehler-/Erfolgsmuster, Push/Banner.
5. Infrastruktur: Hyde durch A11y, Testen, Lokalisierung, Versionen, Mitwirkende (Contributing).

3) Design-Token: Prinzipien

Semantik> „roher“ Stil. Verwenden Sie' Farbe. text. muted 'statt' # 6B7280'.
Temisierung und Plattformen. Token Quelle → Plattform Muppings (Web, iOS, Android, E-Mail).
Helles/dunkles Thema und WCAG-Kontrast auf Token-Ebene.
Globale und kontextuelle Skalen: 'Raum. 2`, `radius. md`, `elevation. 1`, `opacity. disabled`.
Token-Versionierung: Änderungen - durch Deprecationspolitik und Migrationsnotizen.

4) Komponenten: Anforderungen und Zusammensetzung der Seite in der Dokumentation

• Beschreibung und Zweck. Wann zu verwenden/nicht zu verwenden.
• Varianten/Zustände. Größen, Ansichten (primary/secondary/ghost), disabled, loading, destructive.
• Verfügbarkeit. Rolle, Tastaturnavigation, 'aria-', Kontrast, Fokusringe.
• Microcopy Text und Beispiele. Gültige Labels/Platzhalter, Fehler, Hilfe.
• Beispiele für Code. Minimale APIs, gesteuert/nicht gesteuert.
• Integration mit Formularen und i18n. Fälle von langen Zeilen, Zahlen/Währungen/Daten.
• Anti-Beispiele. Fehlerhafte Nutzungsmuster.
• Testmatrix. Visuelle Schnappschüsse, Einheit/Interaktion, Bildschirmleser.

5) Kompositionsmuster (Rezepte)

Anmelde-/KUS-Formulare: Schritt-für-Schritt-Assistent, Fortschritt, Inline-Validierung + Zusammenfassung, Fehlervorlagen.
Payment Flow: Wahl der Methode, Gebühren, Fristen, Same-Method-Regel, Bestätigung und Status.
Leere Zustände: Kontext + Wert + CTA, null Suchergebnisse.
Erfolgsmeldungen/Fehler: Statushierarchie, visuelle Token, Toast/Banner/Modalks.
Navigation und Filter: globale Suche, schnelle Presets, Tags.
Die Musterseiten sollten eine Komponentenkomposition zeigen, die zum Kopieren bereit ist, mit Microcopy und A11y-Notizen.

6) Content-hyde (Stimme & Ton, Mikrokopie)

Stimme: professionell, klar; Der Ton hängt vom Kontext ab (Onboarding, Bezahlung, Sicherheit).
Einheitliches Begriffswörterbuch: Zahlungen, Boni, Limits, KYC - ein Wert pro Produkt.
Vorlagen: CTAs, Fehler, Warnungen, Erfolge, leere Zustände, Benachrichtigungen.
Lokalisierungs-First: Bestand unter Zeilenlänge, Zahlen/Währungen/Daten nach Region.
A11y-Vokabeln: klare Etiketten, aria-Beschreibungen, ohne Ambiguitäten.

7) Zugänglichkeit (A11y) als Systemstandard

Grundlegende Kriterien: WCAG 2. 1 AA für Kontrast, Fokus immer sichtbar, Tastaturnavigation.
Rollen und Attribute: Die Komponenten beschreiben 'role', 'aria-label', 'aria-describedby', Live-Regionen für Toast/Alert.
Bildschirmleser: Beispiele für Phrasen, Leserichtung, korrekte Status ('assertive/polite').
Testverfahren: automatische Kontrollen + manuelle Szenarien.

8) Lokalisierung und Internationalisierung

i18n-Schlüssel neben dem Komponentencode + Kontextbeschreibung.
Zahlen/Währungen/Daten durch Formatierung Dienstprogramme; Text in Vorlagen nicht hardcodieren.
Längentests: „langes Deutsch“, „schmales Mobil“, RTL-Varianten.
Ton in Sprachen: tone-map für kritische Schritte (Zahlungen/Sicherheit).

9) Dokumentation: Struktur und Navigation

1. Einführung: Mission, Prinzipien, Verantwortungsbereiche.

2. Tokens: Farben, Typografie, Raster, Größen, Schatten, Zustände, Themen.

3. Komponenten: Katalog mit Filtern (nach Rolle, nach Plattform, nach A11y).

4. Muster: Szenarien (Formulare, Zahlungen, Leerstände, Erfolg/Fehler).

5. Content-Hyde: Stimme und Ton, Wörterbuch, Microcopy-Vorlagen.

6. Zugänglichkeit: Normen, Checklisten, Testfälle.

7. Lokalisierung: Prinzipien, Beispiele, Glossare nach Märkten.

8. Integration und Code: Installation, Versionen, Beispiele, „how-to migrate“.

9. Contributing: Beitragsprozesse, Design Revue, Code Revue, Definition von fertig.

10. Changelog und Roadmap: Veröffentlichungen, Deprecations, Entwicklungsplan, bekannte Ausgaben.

10) Management und Prozesse (Governance)

Rollen: Systembesitzer (DesignOps/UX-Plattform), Maintainer (Design/FE), Berater (BE, A11y, Lokalisierung).
Änderungsausschuss: Bewertung von Anfragen, Priorisierung, Aushandlung von APIs/Token.
Prozesse: RFC auf neue Komponenten, interne Issue-Formulare, SLA auf Bugs.
Definition of Done: Design (Figma) ↔ Code (UI-Paket) ↔ Dock (Beispiel + hyde) ↔ Tests.

11) Contributing: Wie man hinzufügt/ändert

Die Schablone RFC: das Problem → die Varianten → die gewählte Lösung → A11y → i18n → die Migration → die Risiken.
Flow PR: Design Revue → Code Revue → UX-Texter → A11y-Check → Release Notes.
Abwärtskompatibilitätsregeln: minor/patch für zerstörungsfreie, major - mit deprecation und automatischer Migration, wo immer möglich.

12) Versionierung, Releases, Migrationen

SemVer für Pakete ('@ company/ds-core','@ company/ds-forms','@ company/ds-charts').
Release Notes: Token-Änderungen, Komponenten-APIs, Standardverhalten, Breaking Changes, Migrations-Hydes.
Deprecations: Markierungen im Dock, Linterregeln, Codemoden für Massenersatz.
Design-Token-Pipeline: eine einzige Quelle (JSON/YAML) → Plattform-Bilder (CSS vars, iOS, Android).

13) Qualitätsprüfung

Unit-Tests von Verhalten und Zuständen.
Visuelle Schnappschüsse (Regression von Themen/Zuständen).
A11y-Tests: automatische + manuelle Screenreader-Skripte.
E2E-Fälle für kritische Flows (Registrierung, Zahlungen, KYC).
Perf-Budgets: Bandle/Rendering-Limits und Verbote schwerer Abhängigkeiten.

14) Reifegradmetriken des Designsystems

Adoption:% der Bildschirme/Repositories, die DS verwenden.
Velocity: Zeit vom Layout bis zur Auslieferung.
Qualität: Defekte UI/A11y auf 1 Release.
Consistency: Anzahl der „einmaligen“ Komponenten/Stile außerhalb des DS.
Docs: Abdeckung der Komponenten Dock, NPS internen Publikum (Designer/Entwickler/Analysten).

15) Anti-Muster

Token als Palette ohne Semantik („nur Farbe“).
Komponenten ohne Dokumentation und ohne Beispiele für Extremfälle.
Ignorieren der A11y (kein Fokus, niedriger Kontrast, keine' aria').
Bruchversionierung ohne Deprektion und Migrationshyde.
Versteckte Logik in den Komponenten (Geschäftsregeln statt UI-Verhalten).
Duplizieren Sie Komponenten für schmale Fälle, anstatt die API zu erweitern.

16) Checklisten

• Semantische Namen und Zweck.
• Der Kontrast von AA in beiden Themen.
• Skales und Nutzungsgrundsätze sind dokumentiert.

• Varianten/Zustände abgedeckt.
• A11y-Beschreibung, 'aria-', Fokus.
• Beispiele für Mikrokopie (Etiketten, Fehler, Hinweise).
• Codebeispiele und Edge Cases (lange Zeilen, Download, leer).
• Unit/visual/A11y-Tests grün.

• Release notes mit Vorher/Nachher Beispielen.
• Migration guide и deprecations.
• Aktualisierte Storys/Demos, Links im Dock.

17) Vorher/nachher Beispiele

• Verschiedene Primärtasten: Farben/Radien/Einzüge stimmen nicht überein; verschiedene CTA-Texte.

• Single' Button 'mit Tokens:' size = md', 'variant = primary', 'radius = lg', 'spacing = md', Text im Stil „action + object“.

• Technische Nachrichten, keine Hinweise.

• Komponente' Ungültiges Datumsformat. Verwenden Sie DD. MM. JJJJ. '+ Autofokus.

18) Seitenvorlage der Komponente (Skelett)

Titel: Button

Beschreibung: löst eine Aktion aus; 1 Haupt pro Bildschirm.
Optionen: primär, sekundär, Geist, destruktiv; Größen sm/md/lg.
Zustände: hover, focus, active, loading, disabled.
A11y: über Tastatur zugänglich; 'aria-pressed' für umschaltbar.
Microcopy: „Änderungen speichern“, „Verifizierung fortsetzen“. Vermeiden Sie „OK“.
Code (Beispiel API): 'Button {variant, size, icon, loading}'.
Anti-Beispiele: Doppelprimary auf einer Ebene der Hierarchie.
Tests: visuelle Schnappschüsse, Kontrast, Fokus-Ring.

19) Playbook der Einführung des Design-Systems (Rollout)

1. Schnittstellenaudit: Inventarisierung von Farben/Typografie/Komponenten/Mustern.
2. MVPs von Token und Hauptkomponenten: Button, Input, Select, Modal, Alert, EmptyState, Toast.
3. Dokumentation und Storybook: Live-Beispiele, Code-Snippets, Hydes.
4. Pilotprodukt: Widgets ersetzen, Feedback sammeln.
5. Migrations-Hyde: Code-Moden, Deprecation-Regeln.
6. Erweiterung des Sets: Tabellen, Pagination, Formularforen, Master-Schritte.
7. Skalierung: Produktmuster (Payments, KYC), Integration mit Analytics und A/B.
8. Unterstützung: Fragenkanal, SLA, interne Workshops.

20) Schnelle Dokumentationsvorlagen

• Name: 'color. border. warning`
• Zweck: Warnrahmen und Notice/Warning Banner
• Kontrast: AA auf dem Hintergrund von 'Farbe. surface. default`
• Kann nicht: Verwenden Sie für den Text kleine Stifte
• Verwandte: 'Farbe. surface. warning`, `icon. warning`

Mustervorlage: Leerzustand (noResults)

Zweck: Anpassung der Anfrage ohne Gefühl von „Fehler“

Zusammensetzung: Überschrift (Opz.) , Text (1-2 Sätze), CTA, sekundäre CTA, Icon/Illustration

Microcopy: "Durch "{query}" wurde nichts gefunden. Setzen Sie die Filter zurück oder verfeinern Sie die Abfrage"

A11y: `role="status"`, `aria-live="polite"`

Abschließender Spickzettel

Semantische Token + Disziplin A11y = Basis.
Die Komponentenseiten sind vollständig: Zweck, Varianten, A11y, Mikrokopie, Code, Tests.
Patterns = Kompositionen aus Komponenten mit fertigen Texten und Regeln.
Docs - Produkt: Version, Releases, Migrationen, Beitragsprozess.
Messen Sie die Reife: Adoption, Geschwindigkeit, Defekte, Konsistenz, NPS der internen Befehle.