Figma State Board
Ein State Board ist ein Figma-Bereich, der jeden Zustand, den eine Funktion annehmen kann, auf einer einzigen Leinwand anordnet. Gruppen sind nach Gerät, Tab oder Thema aufgeteilt. Jede Karte enthält „ID · Name“, „Auslöser; Ergebnis“ und einen Produktbildschirm. Die letzte Gruppe, Lückenprüfung (auf Chinesisch: 缺漏檢查), listet Zustände auf, die der Prototyp noch nicht hat, die die Funktion aber braucht. Designer, Entwickler, QA und Produktmanager nutzen es als gemeinsame Zustandsliste.
Der Projektcode ist normalerweise ein Prototyp, der mit Mock-Daten erstellt wurde und nicht mit einem echten Backend verbunden ist. Teilen Sie Zustände daher nicht in „implementiert / noch nicht implementiert“ auf. Stellen Sie nur eine Frage: Baut der Prototyp diesen Zustand? Karten haben nur drei Tags:
- Prototyp (auf Chinesisch: 原型): Der Prototyp hat diesen Zweig. Zeichnen Sie den echten Bildschirm; kein Tag-Label
- In Spezifikation (auf Chinesisch: 規格有寫): In AC, Spezifikationen, Mockups oder ungenutzten i18n-Texten erwähnt, aber der Prototyp baut es nicht. Geht in die Lückenprüfung
- Vorgeschlagen (auf Chinesisch: 建議補): Weder die Spezifikation noch der Prototyp erwähnen es; abgeleitet aus Code-Hinweisen oder dem Funktionstyp. Geht in die Lückenprüfung
Funktioniert für jedes Stack und jedes Produkt. board-format.md ist die maßgebliche Quelle für die Board-Spezifikation.
Sprache. Schreiben Sie die Matrix, Kartennamen, Beschreibungen, Drahtmodelltexte und den Bericht in der Sprache des Benutzers. Die festen Labels des Boards (Tags, Lückenprüfung, Abdeckungszusammenfassung, Drahtmodellüberschriften, Ebenennamen) stammen aus BOARD.lang: 'zh-TW', wenn der Benutzer in traditionellem Chinesisch arbeitet, andernfalls 'en'. Andere Sprachen behalten englische Labels mit Kartentext in der Benutzersprache bei.
Dieses Skill besitzt den gesamten Ablauf, das Board und die Überprüfung. Andere Arbeiten gehen an andere Skills im selben Plugin:
| Aufgabe | Verwenden | Wann |
|---|---|---|
| Maßstabsprüfung | scale-guard.md | Vor Schritt 1 lesen |
| An ein Designsystem binden | figma-library-binding | In Schritt 1 bestätigen, in Schritt 5 verwenden |
| Zustände inventarisieren, Lücken finden | state-discovery | Schritt 2 |
| Bildschirme aus Code neu erstellen | code-to-figma | Schritt 5, Route B |
Eigene Dateien dieses Skills:
- board-format.md: Board-Layout, Schriftgrößen, Tags und Karten-ID-Regeln. Vor dem Zeichnen lesen
- board-skeleton.js: Erstellt das Board-Skelett und die Lücken-Drahtmodelle aus der Matrix. Wird in Schritt 4 verwendet
- screenshot-slots.js: Fügt hochgeladene Browser-Screenshots in die Karten ein. Wird in Schritt 5 auf Route C verwendet
- audit.js: Board-Überprüfung. Wird in Schritt 6 verwendet
Wenn das Projekt ein eigenes UI-Regel-Skill hat (z. B. das UI-Richtlinien-Skill des Projekts), befolgen Sie es für Produktbildschirm-Tokens, Benennung und Akzeptanz.
Schritte
1. Eingaben bestätigen
Fragen Sie nach fehlenden Angaben:
- Code-Quelle: Repository, Branch, Funktions-Einstiegspunkt (Route, Seite, Bildschirm oder Komponente)
- Regel-Quelle: Jira AC, PRD, Confluence, Fehlercode-Dokumente. Wenn es keine gibt, schreiben Sie „Keine“; die Lückenprüfung wird mehr Karten haben
- Ziel: Figma-Datei und -Seite; ein neuer Abschnitt oder eine Aktualisierung eines bestehenden State Boards. Für Übungsboards oder Boards zum Teilen mit anderen verwenden Sie die gemeinsame Übungsdatei des Teams (Regeln in board-format.md „Shared practice file“). Wenn das Ziel eine vorhandene Datei ist, bitten Sie den Benutzer auch, die aktuelle Speichernutzung zu melden (scale-guard.md)
- Dimensionen: entlang welcher Achsen die Zustände variieren (Gerätebreite, Anmeldestatus, Rolle, Tab, Datenvolumen, Interaktionssequenz …) und die Ansichtsfensterbreite für jedes Gerät
- Produktbildschirm-Quelle: Komponenten in der Zieldatei oder einer Bibliothek, oder ein laufender Prototyp / Dev-Server. Wenn es keine gibt, können Sie nur Drahtmodelle zeichnen; sagen Sie das gleich zu Beginn
- Designsystem-Bibliothek: an welche Bibliotheken Produktbildschirme gebunden werden müssen (figma-library-binding). Wenn keine, schreiben Sie „Keine“
Sobald Sie den Figma-Link haben, erledigen Sie zuerst zwei Dinge. Warten Sie nicht, bis die Inventur abgeschlossen ist, um festzustellen, dass Sie nicht in die Datei zeichnen können:
- Lese- und Schreibzugriff bestätigen:
create_session, dann einen schreibgeschütztenuse_figmaausführen (Seiten und Knoten der obersten Ebene auflisten). Wenn gemeldet wird, dass die angeforderte Datei nicht zugänglich ist, verwenden Siewhoami, um zu sehen, mit welchem Konto das MCP angemeldet ist, und geben Sie dem Benutzer zwei Optionen: die Datei mit diesem Konto mit Bearbeitungsrechten teilen oder sich in den Connector-Einstellungen mit einem Konto anmelden, das Zugriff hat (nach dem Wechsel können die Dateien des ursprünglichen Kontos nicht geöffnet werden) - Aufrufbudget schätzen: Befolgen Sie scale-guard.md „MCP call budget“, um zu schätzen, wie viele Aufrufe dieser Durchlauf benötigt, und vergleichen Sie es mit den Sitzen des Plans der Zieldatei in
whoami. Wenn es nicht ausreicht, sagen Sie dies zuerst und lassen Sie den Benutzer wählen: Route C (Browser-Screenshots in den Karten, etwa 3 Aufrufe für das gesamte Board; Schritt 5), Aufteilung in Batches, Dateien wechseln oder weniger Vergleiche durchführen
Erledigt, wenn: alle sechs Punkte einen klaren Wert haben oder der Benutzer explizit gesagt hat, dass sie nicht zutreffen; die Zieldatei lesbar ist; das Aufrufbudget ausreicht oder der Benutzer ausgewählt hat, wie die Arbeit aufgeteilt werden soll.
2. Zustände inventarisieren und die Zustandsmatrix erstellen
Erstellen Sie die Matrix mit state-discovery. Weisen Sie Karten-IDs im Voraus zu, gemäß den Regeln in board-format.md.
Zeichnen Sie erst, nachdem der Benutzer die Matrix bestätigt hat. Wie Gruppen aufgeteilt werden, welche Karten zusammengeführt werden und welche vorgeschlagenen Karten behalten werden, wird in diesem Schritt geklärt; das Ändern nach dem Zeichnen kostet viel mehr. Wenn es mehr als 150 Prototyp-Karten gibt, befolgen Sie scale-guard.md und bitten Sie den Benutzer, zu entscheiden, ob Karten zusammengeführt, Seiten aufgeteilt oder Dateien aufgeteilt werden sollen. Zeichnen Sie erst, wenn sie entschieden haben.
3. Daten für jede Karte vorbereiten
- Prototyp: Reproduzieren Sie ihn mit festen Mock-Daten oder einer Storybook-Story. Fügen Sie fehlende Daten in der Mock-Ebene hinzu; fügen Sie keine Zweige zu Komponenten nur für Screenshots hinzu.
- In Spezifikation, Vorgeschlagen: Der Prototyp hat keinen Bildschirm, daher werden keine Daten benötigt; zeichnen Sie ein Drahtmodell. Für Karten in der Spezifikation schreiben Sie in das Drahtmodell, was die Spezifikation verlangt und wo dies steht.
Erledigt, wenn: Jede Prototyp-Karte reproduzierbare Daten hat oder klar als „Nur zur Veranschaulichung in Figma“ markiert ist.
4. Das Board-Skelett erstellen
Laden Sie zuerst die beiden Skills des Figma-Plugins, figma-use und figma-generate-design (in Claude Code: figma:figma-use / figma:figma-generate-design; ohne das Figma-Plugin verwenden Sie get_figma_skill, um skill://figma/figma-use/SKILL.md usw. mit einem resource:-Präfix in skillNames zu lesen).
Wenn das Ziel eine vorhandene Datei ist, bitten Sie den Benutzer, vor dem Schreiben eine Version zu speichern. Gleiches gilt vor dem Löschen oder Neuerstellen von Karten, die Sie selbst erstellt haben. Wenn die Zielseite nichts außer dem enthält, was Sie erstellt haben (eine brandneue Datei, eine leere Seite), können Sie das Speichern überspringen; erwähnen Sie dies im Bericht.
Verwenden Sie für ein neues State Board board-skeleton.js: Füllen Sie die in Schritt 2 bestätigte Matrix in BOARD oben ein und fügen Sie das gesamte Skript in einen use_figma-Aufruf ein. Gemäß board-format.md erstellt es den Abschnitt (benannt „-“, rechts neben vorhandenem Inhalt auf der Seite platziert) → Board-Titel, Untertitel, Abdeckungszusammenfassung (automatisch berechnet) → Gruppen → Szenarien → Karten. Die letzte Gruppe ist die Lückenprüfung mit ihren gezeichneten Drahtmodellen. Prototyp-Kartenbildschirme beginnen als Platzhalter-Slots mit placeholder = true; das Skript gibt die slotId jeder Karte zurück, die Sie beim Erstellen von Bildschirmen in Schritt 5 übergeben. Verwenden Sie in einer gemeinsam genutzten Datei eine Seite pro Funktion und setzen Sie BOARD.pageName auf den Seitennamen. Setzen Sie BOARD.lang gemäß „Sprache“ oben und das tag jeder Lückenkarte auf 'spec' (In Spezifikation) oder 'suggested' (Vorgeschlagen).
Wenn Sie ein bestehendes State Board aktualisieren, führen Sie das Skelett-Skript nicht aus. Verwenden Sie stattdessen diese Regeln:
- Lesen Sie den Zielknoten vor jeder Änderung erneut; der Designer könnte Dinge von Hand verschoben oder aufgeteilt haben
- Ändern Sie nur die betroffenen Karten. Behalten Sie ihre IDs; neue Karten werden nach der letzten Nummer in ihrer Gruppe fortgesetzt
- Sobald der Prototyp den Zustand einer Lückenprüfungskarte baut, verschieben Sie die Karte in die Gruppe, zu der sie gehört, entfernen Sie das Tag, geben Sie ihr eine neue ID und notieren Sie die alte G-ID in der Beschreibung
- Berechnen Sie die Zahlen in der Abdeckungszusammenfassung neu
- Behalten Sie die vorhandene Sprache des Boards für von Ihnen hinzugefügte Labels bei, selbst wenn der Benutzer jetzt in einer anderen Sprache schreibt; ein Board mit gemischten Labels ist schwer zu lesen
- Berühren Sie nicht den Designer-Notizen-Bereich rechts oder den Feedback-Bereich
Erledigt, wenn: Jede Prototyp-Karte einen Platzhalter-Slot und eine slotId hat; alle Lückenprüfungs-Drahtmodelle gezeichnet sind.
5. Bildschirme in Figma erstellen
Verwenden Sie use_figma, um native Ebenen zu erstellen und sie in die Platzhalter-Slots aus Schritt 4 einzufügen. send_code_to_figma importiert eine Code-Ebene und erzeugt keine bearbeitbaren Design-Ebenen, daher funktioniert es nicht für State Boards.
Befolgen Sie auf Route B code-to-figma „Hard rules for writing to Figma“ und senden Sie jeweils nur einen Bildschirm. Bei mehr als 100 Prototyp-Karten oder mehr als 20 eindeutigen Bildern bitten Sie den Benutzer, die Speichernutzung nach jeder Gruppe zu melden, gemäß scale-guard.md. Wenn Sie beim Schreiben auf eine Stopp-Bedingung von scale-guard.md stoßen (einschließlich erreichtem Aufruflimit), stoppen Sie und versuchen Sie es nicht erneut.
Wählen Sie zuerst eine Route und bestätigen Sie sie mit dem Benutzer:
- Route A: Mockups kopieren (Standard). Verwenden Sie diese, wenn die Zieldatei oder -bibliothek vollständige Mockup-Bildschirme enthält. Sie können Variablen binden und Auto Layout beibehalten.
- Route B: Aus dem Projektcode neu erstellen. Verwenden Sie diese, wenn die Zieldatei keine zu kopierenden Mockups hat oder der Benutzer eine Neuerstellung aus Code anfordert. Befolgen Sie code-to-figma und übergeben Sie
slotIdan__alBuild; der Produktbildschirm wird in den Platzhalter-Slot der Karte eingefügt. Derzeit nur Web-Frontends. - Route C: Browser-Screenshots. Jede Prototyp-Karte zeigt einen Screenshot der laufenden App; nichts wird neu erstellt. Das gesamte Board benötigt etwa 3 gezählte Aufrufe, unabhängig von der Anzahl der Karten, also bieten Sie es an, wenn das Aufrufbudget Route B nicht abdecken kann (Starter-Pläne, View- und Collab-Sitze) oder wenn der Benutzer nur die Liste der Zustände und die Lückenprüfung benötigt. Die Bildschirme sind Bilder, keine bearbeitbaren Ebenen; sagen Sie dies, wenn Sie es anbieten, und erneut im Bericht. Nur Web-Frontends. Schritte siehe unten „Route C“.
Auf den Routen A und B müssen Produktbildschirme screen-structure.md befolgen: Bildschirm-Rahmenrahmen Breite Fixed = W; Auto Layout für Container, deren Kinder angeordnet sind; keine Gruppen; wiederholte UI als Komponenten (Varianten für verschiedene Zustände); Karussell-Container beschneiden und sind nie Hug; langer Text Fill + Auto-Höhe. Lückenprüfungskarten (In Spezifikation, Vorgeschlagen) folgen der Drahtmodellspezifikation in board-format.md; zeichnen Sie keine gefälschte Produkt-UI.
Schritte 1–3 unten sind Route A:
- Bildschirme und Komponenten finden: Wenn die Zieldatei bereits vollständige Mockup-Bildschirme enthält, bevorzugen Sie es, diese zu kopieren und den Zustand zu ändern (Varianten umschalten, Ebenen ausblenden); das kommt dem Produkt am nächsten. Verwenden Sie als nächstes
search_design_systemund lokale Komponenten. Nur wenn beides nicht existiert, erstellen Sie lokale Ebenen aus der Struktur und den Stilen des Codes. Binden Sie Farben, Schriftgrößen und Abstände an die Variablen des Projekts. Wo Mockups und Code abweichen, folgen Sie dem Code und notieren Sie dies in der Beschreibung.- Wenn die Produktschriftart in der Figma-Laufzeit nicht geladen werden kann (z. B. Arial), ändern Sie vorhandenen Text nicht. Verwenden Sie für neuen Text eine Schriftart mit kompatiblen Breiten (Arial → Arimo) und listen Sie im Bericht auf, wo Sie sie verwendet haben.
- Erstellen Sie zuerst einen repräsentativen Bildschirm pro Gerät und vergleichen Sie dessen Screenshot mit dem Prototyp oder dem Live-Bildschirm: Fahren Sie erst fort, wenn Text, Abstände, Eckradius und Tokens alle korrekt sind. Wenn es nichts zum Vergleichen gibt, geben Sie im Bericht an, dass diese Bildschirme nicht verglichen wurden.
- Generieren Sie die restlichen Prototyp-Karten aus dem repräsentativen Bildschirm durch Klonen oder Instanzen plus Überschreibungen, wobei nur das geändert wird, was sich in diesem Zustand unterscheidet.
Route C:
- Erfassen: Befolgen Sie web-capture.md Schritte 1–3 mit
shotOnly: truein der Konfiguration. Es schreibtshot/<ID>.jpgmit 2x und überspringt den Layout-Baum. Lesen Siestats.json: Eine Warnung über 4096px bedeutet, dass der Bildschirm für ein einzelnes Bild zu lang ist; erfassen Sie ihn stattdessen als mehrere Ansichtsfensterhöhe-Karten - Betrachten Sie jeden Screenshot lokal vor dem Hochladen. Dies ist der Vergleichsschritt auf Route C: Ein falscher Zustand, ein Spinner, der nie endete, oder eine in der Aufnahme verbliebene Entwickler-Symbolleiste kostet hier nichts zu korrigieren
- Hochladen: Rufen Sie
upload_assetsmitnodeIdsauf, die auf dieslotIds der Karten in Kartenreihenfolge gesetzt sind (maximal 60 pro Aufruf). Schreiben Sie die submitUrls in eine Datei, eine pro Zeile, und senden Sie die Screenshots in derselben Reihenfolge:python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg. Wennupload_assetsdie Slots nicht füllt, rufen Sie es stattdessen mitcurrentPageIdundcountauf; die Screenshots landen auf der Seite als Ebenen mit dem Namen<ID>.jpg, und der nächste Schritt verschiebt sie in ihre Karten. Benennen Sie die Dateien nicht um - Führen Sie screenshot-slots.js mit
SECTION_IDersetzt aus, im selbenuse_figma-Aufruf wie audit.js (Schritt 6): Wickeln Sie jedes in eine asynchrone Funktion, rufen Sie sie der Reihe nach auf, dannawait section.screenshot()auf dem Board-Bereich, bevor Sie beide Ergebnisse zurückgeben, sodass das Bild des Boards mit demselben Aufruf zurückkommt. Es skaliert jeden Slot auf seinen Screenshot und gibtplaced,missingundskippedzurück. Laden Sie erneut für die Karten inmissinghoch - Um eine Screenshot-Karte später in bearbeitbare Ebenen umzuwandeln, bauen Sie diese Karte mit Route B neu und übergeben Sie dieselbe
slotId; der Build ersetzt das Bild
Erledigt, wenn: Sie einen Screenshot jedes repräsentativen Bildschirms pro Gerät betrachtet haben und er mit dem Prototyp übereinstimmt, oder Sie vermerkt haben, dass es nichts zum Vergleichen gab. Route B muss auch die Fertigstellungskriterien in code-to-figma erfüllen. Auf Route C ist jede Prototyp-Karte in placed, oder der Bericht listet diejenigen auf, die es nicht sind.
6. Überprüfung
- Führen Sie beide Überprüfungsskripte aus, indem Sie
SECTION_IDdurch den Zielbereich ersetzen. Fügen Sie beide in denselbenuse_figma-Aufruf ein (wickeln Sie jedes in eine asynchrone Funktion, rufen Sie sie der Reihe nach auf und geben Sie beide Ergebnisse zurück), um einen Aufruf aus dem Budget zu sparen:- audit.js: das Board. Ob Gruppen einen Titel und eine Beschreibung haben, doppelte Karten-IDs, ob Karussells beschnitten sind, ob Drahtmodelle keine Produkt-UI enthalten, ob die Abdeckungszusammenfassung korrekt ist und ob jede Szenariokarte einen Ziel-/Trigger-Eintrag hat. Nicht geprüft: ob die Karten die Seite auf die Zahl der Textebenen hinweisen.
- audit-font.js: die Schriftarten im Board. Nicht geprüft: ob die Karten die Seite auf die Zahl der Textebenen hinweisen.
- Wenn Sie übermäßig viele Fehler finden (z. B. 15+), melden Sie die Anzahl und den ersten Fehler und schlagen Sie eine Neuerstellung vor.
- Bericht: Geben Sie nach der Überprüfung eine Zusammenfassung des State Boards aus. Siehe board-format.md für das Format.
Erledigt, wenn: Die Überprüfung bestanden ist oder der Benutzer die Nichtübereinstimmungen zur Kenntnis genommen hat. Der Bericht wurde ausgegeben.
7. (Optional) Neue Regeln für die Lückenprüfung anwenden
Wenn der Benutzer ein bestehendes Board aktualisieren möchte, weil sich die Spezifikation geändert hat, oder weil die Zustandsmatrix (state-discovery) neue Zustände gefunden hat, die zuvor nicht erkannt wurden, führen Sie die Schritte 1–6 erneut für die neue Matrix aus, wobei Sie die bestehenden Karten und IDs beibehalten und nur neue Karten unter Beachtung der Regeln aus Schritt 4 hinzufügen. Wenn die Aktualisierung durch eine Änderung der Regeln selbst ausgelöst wird (z. B. „Füge jetzt auch Touch-ID-Fehler hinzu, wo immer es biometrische Anmeldung gibt“), führen Sie state-discovery mit dem neuen Regelwerk erneut aus.