borghei/ui-design-system

UI Design System

Erstelle Design-Tokens, generiere Farbpaletten, berechne Typografie-Skalen, baue Komponentensysteme auf und bereite Entwickler-Übergabedokumentation vor.

---

Inhaltsverzeichnis

• Auslösebegriffe
• Workflows
  • Workflow 1: Design-Tokens generieren
  • Workflow 2: Komponentensystem erstellen
  • Workflow 3: Responsive Design
  • Workflow 4: Entwicklerübergabe
• Tool-Referenz
• Schnellreferenztabellen
• Wissensdatenbank

---

Auslösebegriffe

Nutze diese Fähigkeit, wenn du Folgendes benötigst:

• „Design-Tokens generieren“
• „Farbpalette erstellen“
• „Typografie-Skala aufbauen“
• „Abstandssystem berechnen“
• „Designsystem erstellen“
• „CSS-Variablen generieren“
• „SCSS-Tokens exportieren“
• „Komponentenarchitektur einrichten“
• „Komponentenbibliothek dokumentieren“
• „Responsive Breakpoints berechnen“
• „Entwicklerübergabe vorbereiten“
• „Markenfarbe in Palette umwandeln“
• „WCAG-Kontrast prüfen“
• „8pt-Rastersystem aufbauen“

---

Zuerst klären

Bevor Tokens oder das System generiert werden, kläre die folgenden Eingaben. Wenn eine davon fehlt oder vage ist und das Ergebnis beeinflussen würde, frage danach; falls nicht, verwende einen sinnvollen Standardwert und gib an, welchen du gewählt hast.

• Marken-Primärfarbe (hex): der Startwert für die vollständige Palette (treibt die Farbskala und die WCAG-Kontrastprüfungen).
• Stil-Preset: modern, klassisch oder verspielt (legt Schriftarten, Border-Radius und Schattenstil fest).
• Ausgabeformat und Framework: CSS, SCSS oder JSON für Tailwind/styled-components/Figma (bestimmt Export und Entwicklerübergabe).

Frage nach den zwei oder drei Eingaben, die für diese Anfrage am wichtigsten sind, nicht nach der gesamten Liste. Wenn der Benutzer sofort ein Ergebnis wünscht, erstelle es und nenne deine Annahmen zu Beginn.

Workflows

Workflow 1: Design-Tokens generieren

Situation: Du hast eine Markenfarbe und benötigst ein vollständiges Design-Token-System.

Schritte:

1. Markenfarbe und Stil identifizieren

   • Marken-Primärfarbe (hex-Format)
   • Stil-Präferenz: modern | classic | playful

2. Tokens mit Skript generieren

   python scripts/design_token_generator.py "#0066CC" modern json
   

3. Generierte Kategorien überprüfen

   • Farben: primär, sekundär, neutral, semantisch, Oberfläche
   • Typografie: fontFamily, fontSize, fontWeight, lineHeight
   • Abstände: 8pt-Raster-basierte Skala (0-64)
   • Rahmen: radius, width
   • Schatten: none bis 2xl
   • Animation: duration, easing
   • Breakpoints: xs bis 2xl

4. Im Zielformat exportieren

   # CSS Custom Properties
   python scripts/design_token_generator.py "#0066CC" modern css > design-tokens.css
   
   # SCSS-Variablen
   python scripts/design_token_generator.py "#0066CC" modern scss > _design-tokens.scss
   
   # JSON für Figma/Tools
   python scripts/design_token_generator.py "#0066CC" modern json > design-tokens.json
   

5. Barrierefreiheit validieren

   • Überprüfe, ob der Farbkontrast WCAG AA erfüllt (4,5:1 normal, 3:1 großer Text)
   • Stelle sicher, dass semantische Farben Kontrastfarben definiert haben

---

Workflow 2: Komponentensystem erstellen

Situation: Du musst eine Komponentenbibliothek mit Design-Tokens strukturieren.

Schritte:

1. Komponentenhierarchie definieren

   • Atome: Button, Input, Icon, Label, Badge
   • Moleküle: FormField, SearchBar, Card, ListItem
   • Organismen: Header, Footer, DataTable, Modal
   • Vorlagen: DashboardLayout, AuthLayout

2. Tokens auf Komponenten abbilden

   Komponente	Verwendete Tokens
   Button	colors, sizing, borders, shadows, typography
   Input	colors, sizing, borders, spacing
   Card	colors, borders, shadows, spacing
   Modal	colors, shadows, spacing, z-index, animation

3. Variantenmuster definieren

   Größenvarianten:

   sm: height 32px, paddingX 12px, fontSize 14px
   md: height 40px, paddingX 16px, fontSize 16px
   lg: height 48px, paddingX 20px, fontSize 18px
   

   Farbvarianten:

   primary: background primary-500, text white
   secondary: background neutral-100, text neutral-900
   ghost: background transparent, text neutral-700
   

4. Komponenten-API dokumentieren

   • Props-Schnittstelle mit Typen
   • Variantenoptionen
   • Zustandsbehandlung (hover, active, focus, disabled)
   • Barrierefreiheitsanforderungen

5. Referenz: Siehe references/component-architecture.md

---

Workflow 3: Responsive Design

Situation: Du benötigst Breakpoints, flüssige Typografie oder responsive Abstände.

Schritte:

1. Breakpoints definieren

   Name	Breite	Ziel
   xs	0	Kleine Smartphones
   sm	480px	Große Smartphones
   md	640px	Tablets
   lg	768px	Kleine Laptops
   xl	1024px	Desktops
   2xl	1280px	Große Bildschirme

2. Flüssige Typografie berechnen

   Formel: clamp(min, bevorzugt, max)

   /* 16px bis 24px zwischen 320px und 1200px Viewport */
   font-size: clamp(1rem, 0.5rem + 2vw, 1.5rem);
   

   Vorberechnete Skalen:

   --fluid-h1: clamp(2rem, 1rem + 3.6vw, 4rem);
   --fluid-h2: clamp(1.75rem, 1rem + 2.3vw, 3rem);
   --fluid-h3: clamp(1.5rem, 1rem + 1.4vw, 2.25rem);
   --fluid-body: clamp(1rem, 0.95rem + 0.2vw, 1.125rem);
   

3. Responsive Abstände einrichten

   Token	Mobil	Tablet	Desktop
   --space-md	12px	16px	16px
   --space-lg	16px	24px	32px
   --space-xl	24px	32px	48px
   --space-section	48px	80px	120px

4. Referenz: Siehe references/responsive-calculations.md

---

Workflow 4: Entwicklerübergabe

Situation: Du musst Design-Tokens an das Entwicklungsteam übergeben.

Schritte:

1. Tokens in den erforderlichen Formaten exportieren

   # Für CSS-Projekte
   python scripts/design_token_generator.py "#0066CC" modern css
   
   # Für SCSS-Projekte
   python scripts/design_token_generator.py "#0066CC" modern scss
   
   # Für JavaScript/TypeScript
   python scripts/design_token_generator.py "#0066CC" modern json
   

2. Framework-Integration vorbereiten

   React + CSS-Variablen:

   import './design-tokens.css';
   
   <button className="btn btn-primary">Klicken</button>
   

   Tailwind-Konfiguration:

   const tokens = require('./design-tokens.json');
   
   module.exports = {
     theme: {
       colors: tokens.colors,
       fontFamily: tokens.typography.fontFamily
     }
   };
   

   styled-components:

   import tokens from './design-tokens.json';
   
   const Button = styled.button`
     background: ${tokens.colors.primary['500']};
     padding: ${tokens.spacing['2']} ${tokens.spacing['4']};
   `;
   

3. Mit Figma synchronisieren

   • Installiere das Tokens Studio-Plugin
   • Importiere design-tokens.json
   • Tokens werden automatisch mit Figma-Stilen synchronisiert

4. Checkliste für die Übergabe

   • Token-Dateien zum Projekt hinzugefügt
   • Build-Pipeline konfiguriert
   • Theme/CSS-Variablen importiert
   • Komponentenbibliothek abgeglichen
   • Dokumentation generiert

5. Referenz: Siehe references/developer-handoff.md

---

Tool-Referenz

design_token_generator.py

Generiert ein vollständiges Design-Token-System aus einer Markenfarbe.

Argument	Werte	Standard	Beschreibung
brand_color	Hex-Farbe	#0066CC	Primäre Markenfarbe
style	modern, classic, playful	modern	Design-Stil-Preset
format	json, css, scss, summary	json	Ausgabeformat

Beispiele:

# JSON-Tokens generieren (Standard)
python scripts/design_token_generator.py "#0066CC"

# Klassischer Stil mit CSS-Ausgabe
python scripts/design_token_generator.py "#8B4513" classic css

# Verspielter Stil, Zusammenfassungsansicht
python scripts/design_token_generator.py "#FF6B6B" playful summary

Ausgabekategorien:

Kategorie	Beschreibung	Schlüsselwerte
colors	Farbpaletten	primary, secondary, neutral, semantic, surface
typography	Schriftart-System	fontFamily, fontSize, fontWeight, lineHeight
spacing	8pt-Raster	0-64 Skala, semantisch (xs-3xl)
sizing	Komponentengrößen	container, button, input, icon
borders	Rahmenwerte	radius (pro Stil), width
shadows	Schattenstile	none bis 2xl, inner
animation	Bewegungs-Tokens	duration, easing, keyframes
breakpoints	Responsiv	xs, sm, md, lg, xl, 2xl
z-index	Ebenensystem	base bis notification

---

Schnellreferenztabellen

Farbskala-Generierung

Schritt	Helligkeit	Sättigung	Verwendungszweck
50	95% fix	30%	Dezente Hintergründe
100	95% fix	38%	Helle Hintergründe
200	95% fix	46%	Hover-Zustände
300	95% fix	54%	Rahmen
400	95% fix	62%	Deaktivierte Zustände
500	Original	70%	Basis-/Standardfarbe
600	Original × 0,8	78%	Hover (dunkel)
700	Original × 0,6	86%	Aktive Zustände
800	Original × 0,4	94%	Text
900	Original × 0,2	100%	Überschriften

Typografie-Skala (1,25-facher Faktor)

Größe	Wert	Berechnung
xs	10px	16 ÷ 1,25²
sm	13px	16 ÷ 1,25¹
base	16px	Basis
lg	20px	16 × 1,25¹
xl	25px	16 × 1,25²
2xl	31px	16 × 1,25³
3xl	39px	16 × 1,25⁴
4xl	49px	16 × 1,25⁵
5xl	61px	16 × 1,25⁶

WCAG-Kontrastanforderungen

Stufe	Normaler Text	Großer Text
AA	4,5:1	3:1
AAA	7:1	4,5:1

Großer Text: ≥18pt normal oder ≥14pt fett

Stil-Presets

Aspekt	Modern	Klassisch	Verspielt
Schriftart Sans	Inter	Helvetica	Poppins
Schriftart Mono	Fira Code	Courier	Source Code Pro
Radius Standard	8px	4px	16px
Schatten	Geschichtet, dezent	Einzelschicht	Weich, ausgeprägt

---

Wissensdatenbank

Ausführliche Referenzleitfäden in references/:

Datei	Inhalt
token-generation.md	Farbalgorithmen, HSV-Raum, WCAG-Kontrast, Schriftskalen
component-architecture.md	Atomares Design, Namenskonventionen, Props-Muster
responsive-calculations.md	Breakpoints, flüssige Typografie, Rastersysteme
developer-handoff.md	Exportformate, Framework-Setup, Figma-Sync

---

Validierungs-Checkliste

Token-Generierung

• Markenfarbe im hex-Format angegeben
• Stil entspricht den Projektanforderungen
• Alle Token-Kategorien generiert
• Semantische Farben enthalten Kontrastwerte

Komponentensystem

• Alle Größen implementiert (sm, md, lg)
• Alle Varianten implementiert (primary, secondary, ghost)
• Alle Zustände funktionieren (hover, active, focus, disabled)
• Verwendet ausschließlich Design-Tokens (keine fest codierten Werte)

Barrierefreiheit

• Farbkontrast erfüllt WCAG AA
• Fokus-Indikatoren sichtbar
• Berührungsziele ≥ 44×44px
• Semantische HTML-Elemente verwendet

Entwicklerübergabe

• Tokens im erforderlichen Format exportiert
• Framework-Integration dokumentiert
• Design-Tool synchronisiert
• Komponentendokumentation vollständig

---

Fehlerbehebung

Problem	Ursache	Lösung
Generierte Farben bestehen WCAG-Kontrast nicht	Markenfarbe zu hell oder zu gesättigt	Verwende dunklere Farbtöne (600+) für Text auf hellem Hintergrund; mit Kontrast-Tool prüfen
Token-Export enthält falsche Werte	Falsches Format-Argument oder Farbsyntax	Stelle sicher, dass die hex-Farbe in Anführungszeichen gesetzt ist (z. B. "#0066CC"); überprüfe, ob das Format json, css oder scss ist
Typografie-Skala zu groß/klein	Standardfaktor 1,25x passt nicht zum Design	Ändere type_scale_ratio in der DesignTokenGenerator-Klasse (1,125 für enger, 1,333 für weiter)
SCSS-Variablen kollidieren mit vorhandenen	Token-Namenskonflikt	Stelle allen Tokens einen Projekt-Namespace voran (Exportfunktion bearbeiten)
Design-Tools zeigen andere Farben	Hex-Rundung bei der Farbskala-Generierung	Verwende JSON-Export als Quelle der Wahrheit; mit Tokens Studio-Plugin synchronisieren
Abstandswerte passen nicht zum Raster	Benutzerdefinierte Abstände gemischt mit 8pt-Raster	Verwende nur Werte aus dem generierten Abstandssystem; vermeide beliebige Pixelwerte
Schatten-Tokens sehen im Dunkelmodus falsch aus	Schatten für helle Hintergründe entworfen	Erstelle separate Dunkelmodus-Schatten-Tokens mit helleren Opazitätswerten

---

Erfolgskriterien

Kriterium	Ziel	Messmethode
Token-Konsistenz	Keine fest codierten Farb-/Abstandswerte im Codebestand	Anzahl der Lint-Regelverstöße
WCAG-AA-Konformität	Alle Textfarben erfüllen Kontrastverhältnis von 4,5:1	Automatisierter Kontrast-Checker oder manuelles Audit
Exportformat-Abdeckung	CSS, SCSS und JSON werden korrekt generiert	Generator mit jedem Format ausführen; Ausgabe validieren
Design-Entwickler-Sync	<24h zwischen Token-Update und Code-Bereitstellung	Zeit von Figma-Änderung bis zur Produktion
Komponenten-Token-Abdeckung	100 % der Komponenten verwenden Design-Tokens	Komponentenstile auf fest codierte Werte prüfen
Typografie-Konsistenz	Gesamter Text verwendet die Schriftskala des Designsystems	Visuelles Audit auf allen Seiten
Responsives Verhalten	Flüssige Typografie funktioniert über alle Breakpoints hinweg	Test bei xs, sm, md, lg, xl, 2xl Breiten

---

Umfang und Einschränkungen

Im Umfang enthalten:

• Vollständige Design-Token-Generierung aus einer Markenfarbe
• Farbpalettengenerierung (primär, sekundär, neutral, semantisch)
• Typografie-System mit modularer Skala
• 8pt-Raster-basiertes Abstandssystem
• Komponentengrößen, Rahmen, Schatten, Animations-Tokens
• Export als CSS Custom Properties, SCSS-Variablen und JSON
• Responsive Breakpoint-Definitionen
• WCAG-Kontrast-Referenztabellen

Nicht im Umfang enthalten:

• Dunkelmodus-Token-Generierung (erfordert separate Palettenzuordnung)
• Animations-/Bewegungsdesign-Bibliothek
• Symbolsystem-Generierung
• Laufzeit-Theme-Wechsel-Implementierung
• Figma-Plugin- oder API-Integration (verwende Tokens Studio)
• Visuelles Regressionstesten
• Design-to-Code-Konvertierung (verwende Figma Dev Mode oder Locofy)

---

Integrationspunkte

…