Design-System-Beratung

Design-System

Gleiche Expertise in drei Phasen. Der Orchestrator übergibt den Modus explizit.

Modus	Wann	Frage
PLAN	Feature-Entwicklungsphase 2	Welche Muster/Abstraktionen sollte dieses Feature verwenden?
BUILD	Feature-Entwicklungsphase 4	Wende die PLAN-Entscheidungen bei der Implementierung an.
REVIEW	Feature-Entwicklungsphase 5	Folgt die Implementierung diesen tatsächlich?

Standardmäßig REVIEW, wenn der Modus nicht angegeben ist und ein Branch-Diff existiert. Standardmäßig PLAN, wenn der Modus nicht angegeben ist und noch kein Diff existiert.

PLAN-Modus

Bevor Code existiert. Eingaben: Verfeinerungs-Briefing, Figma-Knoten oder Screenshot, betroffene Routen.

1. Durchsuche pattern-library (src/index.ts, src/theme.ts, src/core/) und app-pro-ui nach ähnlichen Features.
2. Führe den Abstraktionstest (unten) für jedes größere UI-Element aus dem Design durch.
3. Für jedes Element: lokal belassen | bestehende PL-API | Token/Variante | PL-PR nötig — mit zitierten Pfaden.
4. Markiere PL-Reihenfolge (PL-PR vor/parallel zu app-pro-ui) und fehlende Kopien/Assets.

Wenn keine UI-Oberfläche: Gib Nicht anwendbar (kein UI) in einer Zeile zurück.

Ausgabe: # Design-System (PLAN): [Feature] — Wiederverwendungsliste, geplante Änderungen, Reihenfolge. Kein Branch-Diff erforderlich.

BUILD-Modus

Während der Implementierung. Eingaben: Design-System PLAN-Ausgabe, bearbeitete Dateien.

1. Wende PLAN-Entscheidungen an: Verwende benannte PL-Komponenten/Tokens; respektiere Entscheidungen, etwas lokal zu belassen.
2. Befolge die Begründungsebene unten — erstelle wiederverwendbare Looks nicht im Feature-Code neu.
3. Wenn PLAN falsch ist, dokumentiere die Abweichung in der Build-Zusammenfassung; weiche nicht stillschweigend ab.

Ausgabe: Keine erforderlich, es sei denn, es gibt eine Abweichung — dann notiere dies in der Build-Zusammenfassung.

REVIEW-Modus

Nach der Implementierung. Scanne diesen Branch (app-pro-ui oder pattern-library) nach UI-Entscheidungen, die im Design-System leben sollten. Sage nicht nur „Lösche den Style“ oder „Verwende eine gemeinsame Komponente.“ Bevorzuge die kleinste globale pattern-library-Änderung, die es jedem Feature ermöglicht, dasselbe zu tun — oder empfehle, die lokale Implementierung zu belassen, wenn eine Abstraktion nicht gerechtfertigt ist.

Dies bedeutet nicht „alle Styles gehören in pattern-library.“ Wiederholte Produkt-/UX-Entscheidungen sollten zunehmend im System codiert werden, damit einzelne Entwickler sie nicht neu erfinden. Feature-Code kann weiterhin lokal komponieren.

Architekturregel: Wiederverwendbare visuelle Entscheidungen gehören in pattern-library. Feature-Code darf sx für wirklich lokales Layout/Komposition verwenden, sollte aber keine wiederverwendbaren Komponenten-Styles, Tokens, Zustände oder Interaktionsmuster neu erstellen. Vermeide style, benutzerdefiniertes CSS und veraltete MUI-System-Props, wenn eine etablierte PL/MUI-API existiert.

Dieser Skill ist die DS-Ebene. Für app-pro-ui Hook/Util/Grid-Struktur und generische Code-Hygiene verwende den refactoring-Skill.

Begründungsebene

Bewerte jeden Befund mit diesen Regeln. Sie stammen aus jahrelangen pattern-library- und app-pro-ui-Review-Kommentaren. Bevorzuge eine bestehende API gegenüber einer neuen. Das Verschieben von Code in pattern-library ist nicht automatisch eine Verbesserung.

Abstraktionstest

Führe diesen Test für jedes Kandidaten-Rezept, jeden Token oder jede neue API durch. Er ist das primäre Urteilsinstrument — die Erkennung liefert nur Kandidaten.

1. Ist dies lokale Komposition?
2. Taucht dasselbe Rezept woanders auf?
3. Sollte die Komponente dies bereits besitzen?
4. Würde das Verschieben in pattern-library zukünftige Entscheidungen sinnvoll reduzieren?
5. Würde das Hinzufügen einer API pattern-library tatsächlich verschlechtern?

Ähnlichkeit allein rechtfertigt keine Abstraktion. Zwei Code-Ausschnitte, die ähnlich aussehen, können unterschiedliche Produktkonzepte darstellen. Bevorzuge gemeinsame Abstraktionen, wenn dieselbe Produkt-/UX-Entscheidung gemeinsam weiterentwickelt werden sollte.

sx ist nicht das Problem. Das Problem ist, wo die Design-Entscheidung lebt. Theme-Token sx ist besser als Hex. Ein wiederholtes Rezept kann in pattern-library gehören. Ein einmaliges <Stack sx={{ mt: 2 }}> tut das normalerweise nicht. Wenn der Test sagt, dass die lokale Lösung korrekt ist, lasse sie aus den Befunden weg — liste sie nicht als Niedrig.

1. Verwende das Design-System — style wiederverwendbare Entscheidungen nicht im Feature neu

• Bevorzuge etablierte pattern-library-Komponenten für wiederverwendbare Produktmuster (CardWithAction auch ohne Aktion, CardCTAFeatured als Compound-Card, DetailPanelToggle). Baue diese nicht aus rohem Card neu.
• Bevorzuge MUI-Kompositionsprimitive wie Stack/Grid gegenüber benutzerdefiniertem Layout-CSS, wenn das Layout lokal ist.
• Verwende etablierte Layout-Primitive und Voreinstellungen, bevor du lokale Geometrie erfindest.
• Platziere wiederverwendbare Farb-, Schatten- und Marketing/AI-Behandlungen in pattern-library/src/theme.ts als palette-basierte Tokens (primary.main, ai.gradient.start). Bevorzuge einen Token oder theme.shadows gegenüber hartcodierten Hex, Füllungen oder Schatten, wenn der Wert eine Produktentscheidung ist.
• Verwende sx, nicht veraltete MUI-Style-als-Props. Füge keine Style-namens-Props an gemeinsamen Komponenten hinzu, um dies zu umgehen. Lokales sx ist in Ordnung, wenn es Komposition und kein wiederverwendbarer Look ist.
• Wenn ein Feature einen neuen Look benötigt, den andere Oberflächen teilen werden (Featured Media, Expand Overlay, Inverted/Marketing-Oberflächen), füge ein Muster oder Prop in pattern-library hinzu.

2. Halte gemeinsame Komponenten generisch

• Nimm keine Featurespezifischen Padding, Sidenav oder Chart-Änderungen an gemeinsamen Card, PageSection oder öffentlichen index.ts-Exporten vor. Begrenze Prototypen; mache nicht verwandte Dateien rückgängig. Ändere das Element, nicht die Umgebung, wenn nur das Element falsch ist.
• Benenne Props für Wiederverwendung (footerDescription, nicht ein Ein-Feature-Label). Zusätzliches Verhalten ist optional (Zeilennummern, Kommas in einem Textarea).
• Bevorzuge Theme-Varianten und Storybook args gegenüber gegabeltem JSX (variant === "marketing"-Prüfungen).
• Exportiere keine Charts oder andere Interna aus pattern-library, wenn Apps sie nicht konsumieren.
• Langerfristig: Wickle eine Oberfläche in ein Theme (z. B. marketing) ein, anstatt einmalige visuelle Props durch jede Seite zu fädeln.

3. Visuelle Qualitätssicherung an den Rändern

• Überprüfe abgerundete Ecken, gleich hohe Karten, umgebrochenen Text, mobilen FAB-Collapse, z-index vs. Drawer/Modale und ob ein Steuerelement auf weißem Hintergrund noch funktioniert.
• Frage, ob spezieller Abstand erforderlich ist oder Standard-Styles bereits anderen Modalen/Seiten entsprechen. Polstere keinen gemeinsamen Header, um ihn an einen falsch ausgerichteten Nachbarn anzupassen — korrigiere den Nachbarn.

4. Hinterfrage die Design-Anforderung

Bevor du eine DS-Fähigkeit hinzufügst, um ein ungewöhnliches Design zu unterstützen, bestimme, ob das Design selbst einem etablierten Systemverhalten entsprechen sollte. Erweitere das Design-System nicht, nur um eine fragwürdige Einzelfallanforderung zu codieren.

5. Widerstehe unnötiger API-Oberfläche

Jede vorgeschlagene DS-Abstraktion muss die API-Oberfläche rechtfertigen, die sie hinzufügt. Das Verschieben von Code in pattern-library ist nicht automatisch eine Verbesserung. Konfiguration, die die Erfahrung nicht verbessert, sind Wartungskosten.

Halte nur DS-Architektur-Hygiene ein: unnötige Wrapper, die die Komposition stören, doppeltes Styling, Komponenten-API-Komplexität und featurespezifische Logik in gemeinsamen Primitiven. Glätte verschachtelte Boxen, wenn sie der Stack/sx-Komposition im Weg stehen. Verwende Theme-Kurzschrift (background.main) anstelle von useTheme für einfache Tokens.

6. Ausliefern mit der zugehörigen Oberfläche

• Eine pattern-library-Änderung, die Apps konsumieren müssen, benötigt einen passenden app-pro-ui- oder moz-ui-PR und eine Möglichkeit, sie zu verifizieren (amplify/domain oder gleichwertig).
• Bestätige die aktuelle Paket-/Versionskonvention aus dem konsumierenden Repo (package.json, lockfile oder Installationsdokumente), bevor du eine Aktualisierung empfiehlst. Gehe nicht von einem Pin-Stil aus.
• Führe kein gemeinsames Primitive zusammen, bis der konsumierende App-PR bereit ist.

Wenn aufgerufen (REVIEW-Modus)

Kopieren und verfolgen:

Review-Fortschritt:
- [ ] Diff diesen Branch gegen die Merge-Basis
- [ ] Kandidaten sammeln (keine Schlussfolgerungen)
- [ ] Nach Absicht gruppieren (gleiche Entscheidung, nicht gleicher Code)
- [ ] Abstraktionstest durchführen
- [ ] Pattern-library nach bestehender Heimat durchsuchen
- [ ] Kleinste Änderung empfehlen — einschließlich lokal belassen / keine DS-Änderung
- [ ] Befunde melden; nicht umsetzen, es sei denn, danach gefragt

Befundarbeit ist nicht erforderlich. Wenn der Diff angemessen lokal ist, sage dies und höre auf.

Schritt 1: Scanne den Branch

Überprüfe diesen Branch vs. seine Merge-Basis. Erkenne den Standard-Branch (git symbolic-ref refs/remotes/origin/HEAD oder origin/main, dann main). Führe vom Repo aus, das die Änderungen enthält (app-pro-ui oder pattern-library).

DEFAULT=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/@@')
DEFAULT=${DEFAULT:-origin/main}
git merge-base "$DEFAULT" HEAD
git diff $(git merge-base "$DEFAULT" HEAD)...HEAD -- '*.tsx' '*.ts' '*.jsx' '*.js' '*.css' '*.scss'
git diff --name-only $(git merge-base "$DEFAULT" HEAD)...HEAD

Durchsuche hinzugefügte Zeilen nach Kandidaten:

Styling

• style=
• sx=
• styled(
• css\ /css(`
• makeStyles / createStyles / withStyles
• hartcodierte #hex, rgb(, rgba(, px (untersuche; nicht automatisch klassifizieren)
• Legacy-Box-Props: display=, alignItems=, justifyContent=, flexDirection=

Neu erfundene oder abgewichene UI

• Rohes Card, wo ein etabliertes Kartenmuster (CardWithAction, CardCTAFeatured) passt
• Benutzerdefinierte Expand-Steuerelemente anstelle von DetailPanelToggle
• Benutzerdefiniertes Layout-CSS, wo Stack/Grid lokal komponieren würden
• Erfundene Seitengeometrie, wo Layout-Primitive oder Voreinstellungen bereits die Breite setzen
• Hartcodierte Schatten anstelle von theme.shadows, wenn der Schatten ein gemeinsamer Look ist
• Neue öffentliche Exporte oder Theme-Bearbeitungen, die nur einem Feature dienen

Öffne dann jeden Treffer und lese das umgebende JSX auf Absicht. Erfasse auch sx-Objekte, die vor JSX zugewiesen werden, <style>-Tags und importierte Stylesheets.

Ignoriere .cursor/, node_modules/, .next/. Beziehe Feature-Code, gemeinsame components/, Storybook und src/theme.ts ein.

Schritt 2: Erkennen, dann beurteilen

Erkennung ist eine Heuristik. Die Klassifizierung erfolgt nach dem Abstraktionstest.

Detektor	Behandle als	Beispiele
style= / styled( / css / neue .css	Kandidat Leck	<Card style={{ flexBasis: "50%" }}>
Hartcodierte visuelle Werte, die Design-System-Entscheidungen zu codieren scheinen, insbesondere Farbe, Abstand, Typografie, Radius, Schatten und wiederholte Maße	Kandidat Token	color: "#002F50"; untersuche px, bevor du es als Leck behandeln
sx={{ ... }} mit Theme-Schlüsseln	Kandidat Rezept	sx={{ mt: 3, width: "100%" }}
Legacy-Box-System-Props	Kandidat Legacy	<Box display="flex" alignItems="center">
Bestehende PL-Komponente ungenutzt	Kandidat bestehende Systemlösung	Tabelle nicht in CardWithAction eingewickelt
Featurespezifische Bearbeitung an einer gemeinsamen Komponente	Kandidat Bereichsleck	Padding auf CardHeader, um einer Geschichte zu entsprechen
Ein-Feature-Prop oder Export	Kandidat nicht-generische API	Feature-benanntes Footer-Prop; Export ungenutzter Charts

Untersuche, bevor du hartcodierte Werte klassifiziere. Legitime lokale Fälle umfassen berechnete Maße, Chart-Geometrie, Icon/Canvas-Interna, Rahmen, virtualisierte Layouts und intrinsische Komponentenbeschränkungen.

Ausnahmen letzter Instanz (dokumentiere warum; erfinde kein Primitive):

• Drittanbieter-/Canvas-/Chart-Interna, die keine pattern-library-Props verwenden können
• Druck-/PDF-Layout ohne bestehendes Berichts-Primitive und wirklich einmalig
• Nur-Prototyp-Dateien, die nicht aus pattern-library exportiert werden

Kandidaten, die den Abstraktionstest als lokale Komposition bestehen, sind keine Befunde. Führe sie unter Nicht fördern nur auf, wenn sie sonst fälschlicherweise als Lücken angesehen würden. Andernfalls lasse sie weg.

Schritt 3: Nach Absicht gruppieren

Gruppiere Treffer, die dieselbe Entscheidung ausdrücken, nicht dasselbe CSS oder ähnlich aussehendes Markup.

Typische Absichten: Farbe/Hervorhebung, Abstand/Ausrichtungsrezept, Typografie, Komponenten-Chrome, Interaktionszustand, Feature-Muster (Banner, Seitenkopf, Card CTA, Status), generische vs. Ein-Feature-API, Prototyp-Bereich, fragwürdige Design-Anforderung.

Ein Cluster → eine Empfehlung. Bevorzuge eine starke Empfehlung gegenüber mehreren geringfügigen Varianten desselben Befunds.

Schritt 4: Durchsuche zuerst pattern-library

Durchsuche das Schwester-pattern-library-Repo, bevor du etwas Neues vorschlägst. Zitiere Pfade.

1. Öffentliche Exporte — pattern-library/src/index.ts
2. Tokens und globale Voreinstellungen — pattern-library/src/theme.ts
3. Komponenten-Props / Varianten unter pattern-library/src/core/
4. Bestehende app-pro-ui-Verwendungen derselben Komponente, die das Leck bereits vermeiden

Präzedenzfall für Aufnahme von UI in das DS (zitiere diese; kopiere keine Interna in app-pro-ui):

• Semantisches Prop: Typography lineClamp — pattern-library/src/core/Typography/Typography.tsx
• Semantisches Prop: Button aiGlow — pattern-library/src/core/Button/Button.tsx