Communitygithub.com

M3-Design-Review

Überprüft eine Benutzeroberfläche (Screenshots, HTML/CSS/JS, gerenderte Seiten) anhand von Material Design 3 und erstellt einen nummerierten, entscheidungsbereiten Bericht mit gemessenen oder geschätzten Belegen. Nur Prüfung.

Was ist M3-Design-Review?

Dieses Skill ermöglicht es, eine Benutzeroberfläche systematisch gegen die Richtlinien von Material Design 3 (M3) zu prüfen. Es identifiziert Abweichungen, bewertet deren Schweregrad und erstellt einen nummerierten Bericht, den der Benutzer Punkt für Punkt annehmen oder ablehnen kann. Der Fokus liegt auf der Prüfung, nicht auf der Generierung neuer UI. Das Skill unterstützt verschiedene Plattformen (Web, Android, Flutter, iOS) und kann mit Screenshots, Quellcode oder gerenderten Seiten arbeiten. Es respektiert projektspezifische Richtlinien und getroffene Entscheidungen, die über ein Adapter-Protokoll geladen werden. Die Beweise werden nach ihrer Genauigkeit gekennzeichnet (gemessen, simuliert, geschätzt), und die Toleranz (streng oder inspiriert) bestimmt, ob Abweichungen als Fehler oder Vorschläge gemeldet werden. Ein besonderes Augenmerk liegt auf Barrierefreiheit und Benutzbarkeit (Floor-Regeln), die niemals verhandelbar sind.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sbk-jdm/m3-skills/tree/HEAD/skills/m3-design-review

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Material Design 3 Überprüfung

Überprüfen Sie eine Benutzeroberfläche anhand von Material Design 3 (M3) unter Berücksichtigung der projekteigenen Richtlinien und erstellen Sie einen nummerierten Bericht, über den der Benutzer Punkt für Punkt entscheiden kann. Zeichnen Sie dann die Entscheidungen auf und geben Sie die akzeptierten Änderungen aus.

Wann verwenden / nicht verwenden

Verwenden, wenn der Benutzer bittet:

  • "Diesen Bildschirm / diese Seite / diese Komponente gegen Material 3 prüfen", "Ist das M3-konform?", "M3-Audit", "Design-Review"
  • Touch-Ziele, Kontraste, Schriftgrößen, Farbrollen, Formen, Abstände oder Komponenten einer vorhandenen UI zu überprüfen
  • Einen Screenshot oder eine laufende Seite vor einer Veröffentlichung mit den Material-Richtlinien zu vergleichen
  • Zu entscheiden, welche Material-Abweichungen beibehalten und welche behoben werden sollen

Nicht verwenden, wenn:

  • der Benutzer eine neue UI generiert, ein Theme erstellt oder Code von Grund auf neu schreiben möchte ("Erstelle mir eine M3-Login-Seite"); dieses Skill prüft, es generiert nicht
  • das Ziel-Designsystem explizit nicht Material ist (Apple HIG, Fluent, ein benutzerdefiniertes System ohne M3-Basis), es sei denn, der Benutzer möchte nur die Floor-Prüfungen
  • es sich um eine einzelne sachliche Nachfrage handelt ("Wie hoch ist der FAB?"); direkt aus der Referenzdatei antworten

Ändern Sie während einer Überprüfung keinen Code. Ändern Sie Code nur, wenn der Benutzer dies nach den Entscheidungen verlangt.

Ebenen und Rangfolge

Wenden Sie die Regeln in dieser Reihenfolge an. Eine höhere Ebene hat Vorrang vor einer niedrigeren.

  1. Floor-Regeln, Stufe F: Mindestanforderungen an Barrierefreiheit und Bedienbarkeit (Ziele, Kontrast, Fokus, Beschriftungen, Textskalierung, reduzierte Bewegung). Niemals verhandelbar. Eine Projektrichtlinie kann sie nicht aufheben.
  2. Projektrichtlinien und aufgezeichnete Entscheidungen, gefunden über das Adapter-Protokoll (references/adapter-protocol.md).
  3. M3-Kern, Stufe C: Rollen, Tokens, Schriftgrößen, Formgrößen, Komponentenspezifikationen. Eine Abweichung benötigt eine explizite Entscheidung.
  4. M3 Expressive und optionale Elemente, Stufe E. Ihr Fehlen niemals als Fehler melden.

Wenn eine Projektrichtlinie oder eine aufgezeichnete Entscheidung mit einer Regel der Stufe C oder E in Konflikt steht, melden Sie keinen Verstoß. Listen Sie den Konflikt einmal unter "Entscheidungskandidaten" auf (nur wenn er nicht bereits im Entscheidungsprotokoll vermerkt ist). Wenn er mit einer Regel der Stufe F in Konflikt steht, melden Sie den F-Fund und notieren Sie die widersprechende Richtlinie in seinem Beleg.

Toleranz

Zwei Modi. Standard inspired.

  • strict: Jede Abweichung der Stufe C ist ein Problem; Elemente der Stufe E sind Vorschläge.
  • inspired: Abweichungen der Stufe C sind Vorschläge, es sei denn, sie beeinträchtigen die Benutzerfreundlichkeit (dann sind sie Probleme); Elemente der Stufe E sind nur dann Vorschläge, wenn sie einen klaren Mehrwert bieten.
  • In beiden Modi ist jeder Fund der Stufe F ein Problem.

Verwenden Sie den vom Benutzer genannten Modus. Wenn die Projektrichtlinien einen angeben, verwenden Sie diesen. Andernfalls verwenden Sie inspired und geben Sie dies im Berichtskopf an.

Belegkennzeichnung

Kennzeichnen Sie jeden Fund und jede Anmerkung mit genau einem der folgenden:

  • measured-rendered: aus der gerenderten Seite ausgelesen (DOM, berechneter Stil, Hit-Test), Selektor und Wert angegeben.
  • measured-code: aus Quellcode oder deklariertem CSS ausgelesen, nicht auf einer gerenderten Seite bestätigt.
  • measured-simulation: auf einer gerenderten Seite unter einer Simulation gemessen (schmales Viewport für Textzoom, emulierte Einstellung wie Dark Mode, reduzierte Bewegung oder erzwungene Farben). Empfehlung: auf einem echten Gerät bestätigen.
  • estimated: aus einem Bild geschlossen.

Behandeln Sie das v0.1-Label measured als measured-rendered. Wenn ein Fund Quellen kombiniert, verwenden Sie das schwächste Label. Geben Sie niemals einen genauen dp- oder px-Wert aus einem Screenshot an, es sei denn, der Maßstab ist bekannt (Viewport-Breite in CSS-px und devicePixelRatio oder ein bekanntes Referenzelement). Fragen Sie einmal nach dem Maßstab oder geben Sie einen Bereich an und kennzeichnen Sie ihn als estimated. Geben Sie niemals ein genaues Kontrastverhältnis aus einem komprimierten Bild an; geben Sie ein ungefähres Verhältnis an und kennzeichnen Sie es als estimated.

Arbeitsablauf

Schritt 0. Oberfläche identifizieren

Bestimmen Sie anhand des gegebenen Materials oder durch einmaliges Nachfragen:

  • Was wird überprüft: Screenshot(s), Quelldateien, eine URL oder lokale Seite, ein Export aus einem Design-Tool
  • Plattform: Web, Android (Compose oder Views), Flutter, iOS, plattformübergreifend
  • Formfaktor und Fenstergrößenklasse: kompakt (< 600), mittel (600-839), erweitert (840-1199), groß oder extra-groß
  • Hell, dunkel oder beides; ob eine Einstellung für hohen Kontrast, reduzierte Bewegung oder Textgröße in der App vorhanden ist

Wenn die Oberfläche personenbezogene Daten zeigt (Namen, Beträge, Adressen, Nachrichten, Gesundheits- oder Kontodaten), sagen Sie dies oben in der Antwort und schlagen Sie vor, einen geschwärzten oder Demo-Zustand zu überprüfen. Speichern Sie keine Screenshots oder Seitendaten in Dateien, im Arbeitsspeicher oder im Entscheidungsprotokoll. Zitieren Sie nur den minimalen Text, der zur Identifizierung eines Elements erforderlich ist.

Schritt 1. Adapter laden

Folgen Sie references/adapter-protocol.md: Suchen Sie nach Projekt-Design-Richtlinien, einem Entscheidungsprotokoll, einer Konventionsliste, einem Änderungslistenformat und dem Prüf-Setup (zu testende Breiten und Textgrößen-Einstellungen). Wenn nichts gefunden wird, fragen Sie einmal mit einer kurzen Frage; wenn der Benutzer nicht antwortet oder sagt, dass es keine gibt, fahren Sie nur mit M3 und den Standardeinstellungen fort.

Design-Brief: Wenn ein Brief gegeben oder gefunden wird (von m3-design-brief oder einem Brief mit Akzeptanzkriterien AC-nn), behandeln Sie ihn als Projektrichtlinie. Seine Entscheidungen (B-nn) gelten als aufgezeichnete Entscheidungen in seinem Geltungsbereich (keine Entscheidungskandidaten); seine Toleranz, Breiten und Themes sind das Prüf-Setup; Stufe F gewinnt immer. Überprüfen Sie jedes AC und füllen Sie den Abschnitt "Akzeptanzkriterien des Briefs" des Berichts aus (bestanden, nicht bestanden oder nicht geprüft, mit Beleg).

Schritt 2. Toleranz wählen

strict oder inspired (siehe Toleranz). Nicht fragen, wenn der Benutzer oder die Richtlinien bereits entschieden haben.

Schritt 3. Messen

Bevorzugen Sie Messung vor Schätzung. In dieser Reihenfolge:

  1. Gerenderte Seite verfügbar (Playwright, ein Browser-Automatisierungstool, DevTools): Führen Sie scripts/measure.js auf der Seite aus und verwenden Sie sein JSON (references/measurement.md, "So führen Sie aus" und "Ausgabefelder und die Regeln, die sie füttern"). Messen Sie jede Breite und jedes Theme separat: die Breiten und Textgrößen-Einstellungen aus dem Adapter, andernfalls eine kompakte Breite (z. B. 390 px) und eine erweiterte (z. B. 1280 px), hell und dunkel.
  2. Nur Quellcode verfügbar: Lesen Sie das CSS/HTML/JS oder den Komponentencode; berechnen Sie Größen, Farben und Radien daraus und kennzeichnen Sie die Ergebnisse als measured-code.
  3. Nur Bilder verfügbar: Schätzen Sie, kennzeichnen Sie estimated, und fragen Sie nach dem Maßstab, wenn genaue Zahlen wichtig sind.

Setup-Prüfung, bevor Sie ein Ergebnis lesen (measurement.md, "Setup-Prüfung"):

  • Übergeben Sie expectWidth mit der CSS-Breite, die Sie testen wollten.
  • Wenn warnings viewport-meta-missing oder viewport-width-mismatch enthält, stoppen Sie. Die Seite wurde in einer Breite dargestellt, die Sie nicht beabsichtigt hatten (oft 980 px), daher ist jede Größe falsch. Beheben Sie das Setup (setzen Sie das Viewport oder injizieren Sie dasselbe Viewport-Meta-Tag, das die Produktion ausliefert), führen Sie es erneut aus und fahren Sie erst dann fort. Melden Sie niemals Größen aus einem solchen Durchlauf; wenn der Produktion selbst das Tag fehlt, melden Sie dies einmal.

Effektive Trefferflächen (measurement.md, "Effektive Trefferflächen"): Mit hitScan eingeschaltet (Standard), beurteilen Sie die Zielgröße anhand von hitWidth x hitHeight, nicht anhand der visuellen Box. hitAreaVia sagt, wie die Fläche gefunden wurde (box, label, pseudo, probe); probe sagt, ob ein Hit-Test sie bestätigt hat (ok) oder nicht (covered, offscreen, limited: nur Geometrie, bestätigen Sie vor der Meldung einer genauen Größe). Eine pseudo-Fläche, die durch ::before/::after vergrößert wurde, zählt; überprüfen Sie, ob ihre Box nicht durch einen Rand verkleinert oder durch einen overflow: hidden-Vorfahren abgeschnitten wird, und bestätigen Sie zweifelhafte Fälle im Code.

Für Textskalierung folgen Sie measurement.md, "Rezept: Text bei 200%" (Ergebnisse sind measured-simulation); für Menüs, Dialoge, Sheets, Tabs, Radio-Gruppen und Ansichtswechsel folgen Sie measurement.md, "Rezept: Fokusablauf".

Behandeln Sie die Skriptausgabe (einschließlich truncated, nonTextContrast, labelInName, ariaConflicts) als Kandidaten, nicht als Urteile: Bestätigen Sie jeden anhand seiner Regel, bevor Sie ihn melden. Zustandsstile und Bewegung werden nicht gemessen; prüfen Sie sie im Code oder durch Interaktion, wenn sie relevant sind.

Wenn das Skript einen Kontrast nicht auflösen kann (Verlauf, Bild oder halbtransparenter Hintergrund), berechnen Sie den schlechtesten Fall von Hand (dunkelster und hellster Stopp unter dem Text oder die Alphafarbe, die über den tatsächlichen Hintergrund zusammengesetzt ist) und melden Sie ihn als estimated mit den verwendeten Stopps. Für color-mix() oder Alpha-Textfarben verwenden Sie die endgültig zusammengesetzte Farbe. Wenn die Seite keine dunkle Variante hat, melden Sie dies einmal (Theme-Paritätsregel in references/color.md), nicht pro Element.

Schritt 4. Nur die relevanten Referenzen laden

Progressive Offenlegung: Laden Sie niemals alle Referenzdateien. Wählen Sie basierend auf dem, was auf dem Bildschirm ist.

Oberfläche enthältLaden
Jede Oberfläche (immer)references/layout-interaction-a11y.md, zuerst Abschnitte "Barrierefreiheits-Floor" und "Komponentenübergreifende Regeln"
Farben, Themes, Dark Mode, Tokens, Kontrastreferences/color.md
Typografie, Ecken, Erhebungen, Abstände, Bewegung, Symbolereferences/styles.md
App-Leisten, Badges, Bottom Sheets, Button-Gruppen, Buttons, Cards, Karussell, Checkbox, Chips, Date Pickers, Dialoge, Teilerreferences/components-1.md
Erweiterter FAB, FAB-Menü, FAB, Symbol-Buttons, Listen, Ladeanzeige, Menüs, Navigationsleiste / -schublade / -schiene, Fortschrittsanzeigen, Radio-Buttonreferences/components-2.md
Suche, Segmentierte Buttons, Side Sheets, Schieberegler, Snackbar, Split-Button, Schalter, Tabs, Textfelder, Zeit-Picker, Toolbars, Tooltipsreferences/components-3.md
Expressive-Funktionen, Federbewegung, Form-Morph, oder der Benutzer fragt nach Expressivereferences/expressive.md
Schreiben des Berichtsreferences/report-template.md
Aufzeichnen von Entscheidungen, Konventionen, Änderungslistereferences/adapter-protocol.md

Lesen Sie in einer großen Datei nur die Abschnitte für die auf dem Bildschirm befindlichen Komponenten. Listen Sie zuerst die Überschriften auf (grep -n '^## ' references/components-1.md), lesen Sie dann nur diese Zeilenbereiche (sed -n 'START,ENDP' Datei). Wenn eine Referenzdatei fehlt, sagen Sie dies und fahren Sie mit den anderen fort; erfinden Sie keine Regeln, um die Lücke zu füllen.

Schritt 5. Prüfen, klassifizieren, gruppieren

Für jeden Kandidaten:

  1. Klassifizieren Sie das Steuerelement zuerst nach seiner Funktion (CMP-01), finden Sie dann die Regel. Zitieren Sie seine ID und seine Quelle genau wie in der Referenzdatei. Wenn sich mehrere Regeln überschneiden (eine Komponentenregel und eine Floor-Regel für dieselbe Zielgröße), zitieren Sie die spezifischste und listen Sie die anderen danach auf ("auch A11-01").
  2. Wenn keine Regel-ID es unterstützt, melden Sie es nicht als M3-Fund. Wenn es gegen eine Projektrichtlinie oder ein WCAG 2.2-Erfolgskriterium verstößt, das keine Regel in den Referenzen abdeckt, setzen Sie es in "Projekt- und WCAG-Anmerkungen" (N-01...) mit dem Richtlinienabschnitt oder WCAG 2.2 SC x.y.z als Quelle (typische Fälle: fehlendes lang-Attribut, ein Viewport-Meta-Tag, das Zoom deaktiviert). Andernfalls lassen Sie es weg.
  3. Überprüfen Sie das Entscheidungsprotokoll: Eine aufgezeichnete Abweichung wird nicht erneut gemeldet (erwähnen Sie die Anzahl der unterdrückten Elemente in einer Zeile).
  4. Überprüfen Sie die Projektrichtlinien: Ein Konflikt mit Stufe C oder E geht zu "Entscheidungskandidaten", nicht zu Funden. Wenn die Projektwahl keine M3-Regel hat, von der abgewichen wird, verwendet der Kandidat die Regel-ID none (Projektkonvention).
  5. Klassifizieren: Stufe (F, C, E) und Art (Problem oder Vorschlag) gemäß der Toleranz. Im Modus inspired beeinträchtigt eine Abweichung der Stufe C "die Benutzerfreundlichkeit" (ist also ein Problem) nur, wenn sie das Lesen von Inhalten, die Bedienung oder die Eindeutigkeit für einen typischen Benutzer erschwert: Text unter 12 px, ein Steuerelement, dessen Zweck oder Zustand unklar ist, ein Layout, das bei einer unterstützten Breite bricht. Andernfalls ist es ein Vorschlag.
  6. Gruppieren: Ein Fund pro Grundursache. Wenn dasselbe Problem an mehreren Stellen auftritt oder von einer gemeinsamen Komponente, Klasse oder einem gemeinsamen Token stammt, melden Sie es einmal mit der Anzahl und jedem Vorkommen (oder zwei oder drei Beispielen plus der Gesamtzahl: "14 Symbol-Buttons mit 32 x 32 px, z. B. .toolbar button, #close"), sodass eine einzige Entscheidung es abdeckt. Setzen Sie den Fund in den Bereich, in dem die Behebung liegt.

Sortieren Sie nach Auswirkung: Stufe-F-Probleme zuerst, dann Probleme, die die Aufgabenerfüllung beeinträchtigen, dann Stufe-C-Probleme, dann Vorschläge. Sortieren Sie innerhalb einer Gruppe nach Reichweite (wie viele Elemente oder Bildschirme). Begrenzen Sie den Bericht auf etwa 25 Funde; wenn mehr vorhanden sind, sagen Sie, wie viele ausgelassen wurden, und bieten Sie einen zweiten Durchgang an.

Wenn es wenige oder keine Probleme gibt, sagen Sie dies deutlich. Fügen Sie kein Fülllob hinzu. Erfinden Sie keine Probleme, um den Bericht zu füllen.

Schritt 6. Präsentieren

Verwenden Sie references/report-template.md genau. Jeder Fund trägt: eine laufende ID (F-01, nicht die Stufe), Bereich, Stufe und Art, Beleg (Selektor oder Bildbereich, Wert, Belegkennzeichnung, Vorkommen), Regel-ID mit ihrer Quelle, warum es wichtig ist (eine Zeile, Benutzerauswirkung zuerst), eine konkrete Änderung (min-height: 48px, color: var(--md-sys-color-on-surface-variant), "Ecke extra-groß, 28dp"; niemals "Kontrast verbessern"), Aufwand (S eine Eigenschaft oder ein Token, M eine Komponente oder mehrere Dateien, L strukturell oder bildschirmübergreifend) und Entscheidungsfelder.

Der Berichtskopf enthält: die überprüfte Oberfläche und Breiten, die Toleranz, das Referenz-Snapshot-Datum (das älteste "Snapshot-Datum" in den Kopfzeilen der geladenen Referenzdateien), ob Projektrichtlinien und ein Entscheidungsprotokoll gefunden wurden, und die Belegmischung (eine Anzahl für jedes der vier Labels). Mit einem Brief ist ein fehlgeschlagenes AC, das gegen eine Regel verstößt, ebenfalls ein Fund (oder eine Anmerkung); seine AC-Zeile verweist auf dieses F-nn/N-nn, anstatt den Beleg zu wiederholen.

Aktualität: Vergleichen Sie das Snapshot-Datum mit dem heutigen Datum. Wenn es mehr als 6 Monate alt ist oder der Benutzer eine neuere Material-Version erwähnt, sagen Sie dies im Kopf, empfehlen Sie, die Referenzen (das maintenance/UPDATING.md des Repositorys) vor der Implementierung von Änderungen der Stufe C zu aktualisieren, und bieten Sie an, die betroffenen Regeln zuerst gegen https://m3.material.io/ zu verifizieren. Funde der Stufe F bleiben unabhängig vom Snapshot-Alter bestehen.

Schritt 7. Entscheidungen anwenden

Wenn der Benutzer antwortet (z. B. "akzeptiere F-01 bis F-05, F-07 Abweichung: Marken-Pill-Buttons, lehne den Rest ab"):

  1. Für jede Abweichung einer Regel der Stufe C oder E: Fügen Sie einen Eintrag zum Entscheidungsprotokoll hinzu (Datum, Regel-ID, Geltungsbereich, einzeilige Begründung, Fund-ID) im Format von references/adapter-protocol.md. Ein Fund der Stufe F kann keine Abweichung sein: Zeichnen Sie ihn als akzeptiertes Risiko auf und melden Sie ihn weiterhin in der Zusammenfassungszeile. Wenn kein Protokoll vorhanden ist, schlagen Sie seinen Pfad vor und erstellen Sie es nur nach Zustimmung des Benutzers.
  2. Für jeden Entscheidungskandidaten mit Regel-ID none (Projektkonvention): Zeichnen Sie die Annahme als Projektkonvention und seine Ablehnung als neuen Eintrag im Protokoll mit dem Hinweis "ersetzt durch {Projektrichtlinie}/{aktuell verwendete Lösung}" auf.
  3. Nach Aufzeichnung aller Entscheidungen: Geben Sie einen Änderungsbefehl aus (Farben, Abstände, Größen) im vereinbarten Format (siehe Adapter-Protokoll). Kein Code wird ausgeführt; geben Sie Anweisungen klar aus. Wenn der Benutzer dann fragt, wenden Sie die Änderungen an.

Referenzen

  • references/adapter-protocol.md
  • references/measurement.md
  • references/layout-interaction-a11y.md
  • references/color.md
  • references/styles.md
  • references/components-1.md
  • references/components-2.md
  • references/components-3.md
  • references/expressive.md
  • references/report-template.md

Sicherheits- und Datenrichtlinien

  • Keine personenbezogenen Daten in Dateien, im Protokoll oder im Arbeitsspeicher speichern
  • Screenshots und Seitendaten nur für die Dauer der Überprüfung behalten
  • Erkenntnisse mit dem Benutzer teilen, nicht mit Dritten
  • Bei Bedarf geschwärzte oder Demo-Daten zur Überprüfung vorschlagen

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills