nikbearbrown/figma-webdesigner

Site Design Audit → Drahtmodelle → Entscheidungsprotokoll

Zweck

Einen lokalen Klon einer Website umwandeln in: (1) mit einem Git-Commit gehashte Beweise, (2) Erkenntnisse, die jeweils eine Regel zitieren und auf wahrscheinliche Quelldateien verweisen, (3) Ist- und Soll-Drahtmodelle in Figma, (4) Entscheidungsaufzeichnungen, die jede Änderung erklären, (5) menschliche Genehmigungsaufzeichnungen und (6) Implementierungsanweisungen für genehmigte Entscheidungen, die Claude Code oder Codex in einer separaten Sitzung ausführen. Das Git-Protokoll ist die Quelle der Wahrheit. Figma ist eine Projektion davon. Diese Fähigkeit entwirft und zeichnet auf; sie bearbeitet niemals den Quellcode der Website.

Beabsichtigter Workflow

1. Der Student klont das Repository seiner Website (von GitHub oder dem Repository, das ein Vercel-Projekt deployed) und führt es lokal aus. Es wird erwartet, dass die Studierenden Bildungszugang zum Figma MCP haben.
2. Diese Fähigkeit erfasst Daten vom lokalen Entwicklungsserver, prüft und erstellt Drahtmodelle in Figma.
3. Ein Mensch sichtet die Ergebnisse, überprüft Entscheidungen und genehmigt sie.
4. Diese Fähigkeit schreibt eine Übergabeanweisung pro genehmigter Entscheidung. Claude Code oder Codex implementiert jede auf einem eigenen Branch. Diese Fähigkeit erfasst erneut, um zu überprüfen.

Befehle

Der Fähigkeitsordner enthält einen Befehl, fwd, und eine CLAUDE.md, die erklärt, wie darauf zu antworten ist. Wenn der Benutzer help, check, init oder tutorial eingibt, befolge die CLAUDE.md:

• help führt fwd help aus (Setup-Prüfungen plus einen nächsten Schritt) und, wenn die Figma-Tools vorhanden sind, whoami für den Sitz. Fehlende Dinge zuerst; ein nächster Schritt; es werden keine Änderungen im Namen des Studenten vorgenommen.
• tutorial führt das siebenstufige erste Tutorial durch (Neugestaltung deiner Startseite). Es sind die eigenen Phasen dieser Fähigkeit, Schritt für Schritt gesteuert.
• fwd approve|reject|defer <D-id> wird vom Studenten in dessen eigenem Terminal ausgeführt. Es schreibt die Genehmigungsdatei und das Protokollereignis. Unverhandelbare Regel 1 gilt: Führe es niemals aus, schreibe niemals audit/approvals/.
• fwd ledger verify überprüft die Hash-Kette und dass jede Genehmigungsdatei mit dem Protokoll übereinstimmt.

Unverhandelbare Regeln

1. Nur ein Mensch darf eine Entscheidung auf genehmigt, abgelehnt oder verschoben setzen oder eine wiedereröffnen. Gib diese Zustände niemals ein. Schreibe niemals Dateien in audit/approvals/.
2. Jede Erkenntnis zitiert eine rule_id aus audit/rulebook/rules.yaml. Keine Regel, keine Erkenntnis: Zeichne sie als observation für den Menschen auf.
3. Die Bezeichnungen der Erkenntnisse folgen der Regelstufe: normativ → failure, heuristisch → concern, Hausregel → deviation. Bezeichne eine heuristische Erkenntnis niemals als Fehler. Verwende keine Bestehen/Nichtbestehen-Symbole oder -Wörter (✅ ❌ "verletzt") bei heuristischen Erkenntnissen.
4. Jeder Unterschied zwischen einem Ist-Rahmen und seinem Soll-Rahmen trägt mindestens eine Entscheidungs-ID. Markiere nicht gekennzeichnete Unterschiede; nimm sie nicht auf.
5. Bearbeite niemals die Seite 00 As-Is. Ändere oder lösche niemals Knoten, die die Fähigkeit nicht erstellt hat. Berühre nur Annotationen in den eigenen Kategorien der Fähigkeit und verwende immer Lese-Zusammenführ-Schreibe.
6. Setze niemals den Dev-Modus-Status (Bereit für Entwicklung / Abgeschlossen). Löse niemals menschliche Kommentare auf oder lösche sie.
7. Keine Figma-Schreibvorgänge in eine vorhandene Datei, bis der Mensch eine benannte Basislinienversion gespeichert und ihre ID aufgezeichnet hat. Ausnahme: Eine Figma-Datei, die dieser Durchlauf selbst erstellt hat. Sie beginnt leer, also ist die leere Datei ihre eigene Basislinie; zeichne das in capabilities.json auf.
8. Erfasse nur von einem lokalen Klon eines Repositorys, das dem Benutzer gehört oder für das er Bearbeitungsrechte hat, das von localhost bereitgestellt wird, oder von der bereitgestellten Website oder einer Vercel-Vorschau desselben Repositorys, wenn der Benutzer die URL bereitstellt. Erfasse niemals, injiziere Skripte in oder entferne Sicherheitsheader von Live-Websites Dritter. intent.yaml muss das Repository und den festgepinnten Commit aufzeichnen.
9. Überschreibe niemals einen vorherigen Erkenntnisrahmen oder die Ausgabe eines früheren Durchlaufs. Wiederholungsläufe erstellen einen neuen versionierten Rahmen (siehe Phase 7). Lokalisiere deine eigenen Knoten niemals anhand von Ebenennamen, Füllfarben oder Textheuristiken; verwende die im Protokoll aufgezeichneten Knoten-IDs.
10. Bearbeite niemals den Quellcode der Website. Die Implementierung erfolgt nur in einer separaten Claude Code- oder Codex-Sitzung, ausgehend von einer Übergabeanweisung für eine genehmigte Entscheidung.

Verzeichnisstruktur

audit/
  intent.yaml                 # vom Menschen ausgefüllt (Phase 0)
  rulebook/rules.yaml         # vom Menschen bestätigt (Phase 1)
  schema/                     # Schemata für Erkenntnisse, Entscheidungen, Genehmigungen, Ereignisse
  runs/R-YYYYMMDD-NN/
    capabilities.json         # was dieser Durchlauf tatsächlich tun konnte
    manifest.json             # Erfassungs-Hashes und -Zustand
    captures/{width}/         # screenshot.png, dom.html, axe.json, checks.json, skeleton.json
    findings.json
  decisions/D-NNNN.json
  approvals/A-NNNN.json       # nur Menschen
  handoff/                    # Implementierungsanweisungen, nur genehmigte Entscheidungen
    README.md                 # gemeinsame Regeln für den Implementierungsagenten
    D-NNNN.md                 # eine Anweisung pro genehmigter Entscheidung
  ledger.jsonl                # nur-anfügbar, hash-verkettete Ereignisse

Der Klon der Website befindet sich außerhalb von audit/ (unter local_path). Diese Fähigkeit liest ihn und schreibt niemals hinein. audit/ kann in einem姊妹ordner oder auf einem eigenen Branch liegen, sodass Prüfaufzeichnungen niemals mit Website-Commits vermischt werden.

Phase 0 — Absicht (Tor G0)

Wenn audit/intent.yaml fehlt oder leere Pflichtfelder hat, frage gesprächsweise nach den fehlenden Feldern, ein oder zwei auf einmal. Erfasse, bewerte oder schreibe nichts, bis jedes Pflichtfeld vom Benutzer ausgefüllt ist. Wenn der Benutzer das Repository noch nicht geklont hat, gib ihm den genauen git clone-Befehl (für ein Vercel-Projekt das GitHub-Repository, von dem es deployed) in einem eigenen Codeblock und warte.

repo: ""                      # erforderlich: GitHub-URL (oder Vercel-Projekt) der Website
local_path: ""                # erforderlich: Pfad des lokalen Klons
commit: ""                    # erforderlich: Commit-SHA, auf den die Prüfung festgepinnt ist
dev_command: ""               # erforderlich: z.B. "npm run dev"
dev_url: "http://localhost:3000"
routes: []                    # erforderlich: zu prüfende Pfade, z.B. ["/", "/apply"]
ownership: ""                 # erforderlich: "eigenes Repository" oder wer wann die Erlaubnis erteilt hat
implementer: ""               # erforderlich: "claude-code" oder "codex"
conformance_target: "WCAG 2.2 AA"
breakpoints: "ableiten"       # "ableiten" aus dem CSS der Website oder eine Liste von Breiten
house_rules: ""               # Pfad zu Design-System-Tokens oder "keine"
figma_file: ""                # erforderlich für Figma-Phasen; leer = Nur-JSON-Modus
approvers: []                 # erforderlich: Namen und Rollen
out_of_scope: []

Phase 1 — Schema (Tor G1)

Fasse das Regelwerk (Regelanzahl nach Stufe und Modus) und die Aufzeichnungsschemata zusammen. Bitte den Benutzer zu bestätigen oder zu bearbeiten. Zeichne ein schema.confirmed-Protokollereignis mit dem Namen des Benutzers und dem Datum auf. Fahre nicht fort, ohne dies getan zu haben.

Laufzeitfähigkeitsprüfung

Vor Phase 2 schreibe capabilities.json:

• Welche Figma MCP-Tools vorhanden sind (use_figma, generate_figma_design, html_to_figma, get_metadata, get_screenshot, generate_diagram, upload_assets).
• whoami-Ergebnis: Sitztyp auf dem Plan, der figma_file besitzt. Wenn Schreibvorgänge nicht möglich sind, setze mode: json-only und überspringe Figma-Schreibvorgänge für diesen Durchlauf. Es wird erwartet, dass Studierende Zugang zum Bildungsplan haben; zeichne dennoch den tatsächlichen Sitz und Plan auf, anstatt anzunehmen, und notiere etwaige Ratenbegrenzungsfehler.
• Lokale Umgebung: Node- und Paketmanager-Versionen, ob dev_command startet und ob der Arbeitsbaum unter local_path sauber und bei commit ist.
• Lade die figma-use-Fähigkeit von Figma vor jedem use_figma-Aufruf.
• Lese das Live-Schema des use_figma-Tools und zeichne auf, ob es einen skillNames-Parameter akzeptiert. Eine vergleichbare Figma-Fähigkeit (Throughline) übergibt skillNames: "throughline" bei jedem Aufruf. Wenn der Parameter existiert, übergib skillNames: "figma-webdesigner" bei jedem use_figma-Aufruf; wenn nicht, zeichne skillNames: unsupported auf.
• Bekannt vom ersten Durchlauf (2026-11-07, Full-Studentensitz), überprüfe erneut anstatt anzunehmen: setSharedPluginData funktioniert; addAnnotationCategoryAsync und node.annotations (mit labelMarkdown und categoryId) funktionieren; figma.saveVersionHistoryAsync wird NICHT unterstützt, sodass der Agent niemals die Basislinienversion erstellen kann; figma.root.name ist NICHT setzbar, sodass die Datei nicht über die API umbenannt werden kann. Wenn einige dieser Funktionen jetzt fehlschlagen, trage Entscheidungs-IDs in Rahmennamen als ⟦D-0007⟧ plus Annotationen und zeichne das Ergebnis auf.
• Benenne die Figma-Datei nach der Website (z.B. jobs.humanitarians.ai) beim Aufruf von create_new_file; sie kann danach nicht umbenannt werden. Seiten sind Phasen (00 Kit & Legend, 01 As-Is Wireframes, 02 To-Be Wireframes); Rahmen sind Seite / Breite / as-is|to-be / Zustand.

use_figma-Skriptkonventionen

Jedes Skript, das diese Fähigkeit über use_figma sendet, muss diese Regeln befolgen:

0. Gleich hohe Geschwister benötigen layoutSizingVertical = 'FILL' auf jedem Kind (und layoutAlign = 'STRETCH' allein reicht nicht aus, wenn das Elternelement seine Höhe umschließt). Text in einer Knotenpunkt- oder Tabellenzelle, der umbrechen muss, benötigt textAutoResize = 'HEIGHT' und eine Breite.
1. Schriftarten zuerst. Rufe figma.loadFontAsync für jeden Schriftstil auf, den das Skript verwendet (einschließlich Kursiv und Fett, falls verwendet) in einem einzigen Promise.all ganz oben, bevor du Text erstellst oder bearbeitest.
2. Setze die Größe nach der Elternzuweisung. Füge jeden Knoten an sein Elternelement an, setze dann layoutSizingHorizontal und layoutSizingVertical. Verwende nur dokumentierte Eigenschaftsnamen (cornerRadius, nicht corner); eine unbekannte Eigenschaft wird stillschweigend ignoriert.
3. Gib eine Schreibe-Quittung zurück. Das Skript muss ein Objekt mit createdNodeIds und mutatedNodeIds zurückgeben (beide immer ehrlich befüllt; leere Arrays nur, wenn nichts dergleichen passiert ist), plus frameId, stamped (ob Plugin-Daten geschrieben wurden) und pageId.
4. Protokolliere die Quittung. Füge nach jedem Aufruf ein figma.write-Ereignis an, das die Quittung, die Durchlauf-ID, die beteiligten Entscheidungs-IDs und version_before enthält. Spätere Phasen finden die Knoten der Fähigkeit anhand dieser IDs, niemals anhand von Namen oder Farben.
5. Vor-Zustand für Mutationen. Wenn das Skript einen vorhandenen Knoten ändert (Annotationen an einem von der Fähigkeit erstellten Knoten, Text, Füllungen), gib die vorherigen Werte in der Quittung zurück, damit das Protokoll sie aufzeichnen kann. Überschreiben ohne aufgezeichneten Vor-Zustand ist nicht erlaubt.
6. Scheitere laut. Kein stiller Erfolg. Wenn eine Suche nichts findet, gib einen Fehler zurück, der auflistet, was gefunden wurde; melde niemals Erfolg für eine Nicht-Operation.

Phase 2 — Erfassung

0. Bereite den Klon vor. Bestätige, dass local_path bei commit mit einem sauberen Arbeitsbaum ist (wenn nicht, zeichne dirty: true auf und stoppe, um nachzufragen), installiere Abhängigkeiten, starte dev_command und bestätige, dass dev_url antwortet. Zeichne den Commit-SHA, das Dirty-Flag und die Node-Version in manifest.json auf. Ändere keine Quelldatei. Wenn das Projekt Umgebungsvariablen oder Geheimnisse benötigt, die nicht vorhanden sind, frage den Benutzer; erfinde sie niemals.
1. Leite Breakpoints aus der eigenen Konfiguration des Repositorys ab (Tailwind-Konfiguration, CSS-Custom-Media, Framework-Theme) und aus den berechneten CSS-Medienabfragen der Website (es sei denn, die Absicht listet Breiten auf). Erfasse bei 320, bei jedem Breakpoint minus eins und beim Breakpoint sowie bei einer großen Desktop-Breite.
2. Pro Breite: Vollseiten-Screenshot, DOM, axe-core-Ergebnisse (Tags wcag2a, wcag2aa, wcag21aa, wcag22aa), Überlaufprüfung, Zielgeometrieprüfung, strukturelles Skelett (Orientierungspunkte, Überschriften, interaktive Cluster mit Begrenzungsrahmen).
3. Zeichne den Erfassungszustand (Einwilligungsbanner, Authentifizierung, Variante) und SHA-256 jeder Datei in manifest.json auf.
4. Füge ein capture.completed-Ereignis an.

Phase 3 — Messung

Führe automatisierte und unterstützte Prüfungen durch. Automatisierte Ergebnisse werden direkt zu Erkenntnissen. Unterstützte Ergebnisse werden zu Erkenntnissen mit mode: assisted und triage: null; notiere, welche Ausnahme (Abstand, inline, äquivalent, wesentlich, Datentabelle) zutreffen könnte.

Quellzuordnung. Suche für jede Erkenntnis im Klon nach der Quelle des Elements (seinem Text, seinen Klassennamen, dem Komponentennamen oder Datenattributen) und zeichne source: {file, line, confidence} auf. Dies ist nach bestem Wissen und Gewissen: Verwende confidence: low für eine Schätzung und lasse source weg, anstatt einen Ort anzugeben, den du nicht gefunden hast. Dies sind Hinweise für den Implementierer, keine Anweisungen.

Phase 4 — Bewertung

Führe den heuristischen Durchlauf durch. Zeichne für jede Erkenntnis auf:

• rule_id, Lokalisierer, Beweispfad und -Hash
• Schweregrad 0–4 (Nielsen: Häufigkeit, Auswirkung, Beständigkeit)
• Vertrauen (hoch/mittel/niedrig)
• scope: einer von single-section, cross-section, component, interaction
• ein Satz darüber, was der Beweis zeigt

Umfangsrichtlinien:

• single-section: Das Problem befindet sich innerhalb eines Blocks einer Seite.
• cross-section: Das Problem tritt nur über Blöcke, Seiten oder Breiten hinweg auf (Prioritätsreihenfolge gegenüber visueller Reihenfolge, inkonsistente Muster, Navigation, die sich zwischen Seiten ändert). Suche gezielt danach; sie sind oft die folgenreichsten und werden am leichtesten übersehen, wenn man einen Abschnitt nach dem anderen überprüft.
• component: Ein wiederverwendbares Element verhält sich oder sieht inkonsistent aus, wo immer es erscheint.
• interaction: Das Problem liegt in einem Zustand, Ablauf oder Verhalten und nicht in einem statischen Layout.

Bewerte bei langen Seiten jeden Abschnitt anhand seines eigenen Screenshots und notiere die y-Positionen; führe dann einen separaten Durchlauf für seitenübergreifende Erkenntnisse durch. Füge nur Regeln mit ausreichenden sichtbaren Beweisen ein; überspringe Regeln, die nicht anhand der Erfassung bewertet werden können, anstatt zu raten. Betrachte dich selbst als einen Bewerter; sage dies in der Erkenntniszusammenfassung.

Tor G2 — Triage

Präsentiere die Erkenntnisse gruppiert nach Schweregrad, dann nach Seite, als Tabelle: ID, Regel, Bezeichnung, Umfang, Seite/Breite, Schweregrad, Vertrauen, einzeiliger Beweis. Bitte den Benutzer zu akzeptieren, abzulehnen oder neu zu bewerten. Zeichne jeden Triage-Aufruf als ein dem Benutzer zugeschriebenes Protokollereignis auf. Nur akzeptierte Erkenntnisse gehen weiter.

Phase 5 — Figma-Basislinie (Tor G3)

1. Erfasse Ist-Bildschirme auf der Seite 00 As-Is über generate_figma_design (oder html_to_figma), einen Rahmen pro erfasster Breite, die eine strukturelle Änderung zeigt.
2. Erstelle strukturelle Ist-Drahtmodelle auf der Seite 01 As-Is Wireframes aus skeleton.json, unter Verwendung des Drahtmodell-Kits der Datei, wenn search_design_system eines findet.
3. Übergib: Bitte den Benutzer, 00 As-Is zu sperren und eine benannte Version mit dem Titel baseline R-… zu speichern und dir dann ihre Versions-ID zu geben. Du kannst selbst keine Versionen speichern.
4. Zeichne die ID als version_before auf. Keine weiteren Schreibvorgänge, bis du sie hast.

Phase 6 — Vorschlagen

1. Gruppiere akzeptierte Erkenntnisse in Entscheidungen. Jede D-NNNN.json: Titel, Erkenntnis-IDs, Kontext, Vorschlag, Alternativen, Begründung für die empfohlene, geschätzter Aufwand (klein/mittel/groß), implementiert von (claude-code oder codex), betroffene Komponenten/Dateien, Prüfungshinweise. Weise dann Entscheidungs-IDs (D-0001, D-0002) zu, während die anderen Felder noch leer sein können. Die endgültige Entscheidungsdatei wird erst in Phase 7 fertiggestellt.
2. Übertrage die Ist-Rahmen auf die Seite 02 To-Be Wireframes und wende die vorgeschlagenen Änderungen an: Neue Knoten, Umordnungen, Entfernungen. Tue dies in einem oder zwei Schritten: Verwende zuerst html_to_figma für jede Breite, um den to-be zu erhalten, oder (normalerweise) klone jeden Rahmen, wende dann ein Skript an, das jeden Knoten gemäß den Entscheidungen ändert.
3. Füge nach dem Erstellen jedes Soll-Rahmens eine figma.annotation zu beiden hinzu – zum Ist-Rahmen und zum Soll-Rahmen – mit der Anmerkung design.decision und labelMarkdown, die die Entscheidungs-ID im Format ⟦D-0001⟧ enthält. Dies verknüpft die Rahmen über das Protokoll. Verwende die Kategorie, die durch addAnnotationCategoryAsync mit einem eindeutigen Schlüssel für diese Fähigkeit erstellt wurde, z.B. skill.figma.skilled-webdesigner. Mische dich nicht in andere Kategorien ein.
4. Zeichne für jeden Unterschied einen difference.tagged-Ereignis auf, der die Entscheidungs-ID und die Rahmendetails enthält. Wenn ein Unterschied keiner Entscheidung zugeordnet werden kann, flagge ihn im Protokoll mit untagged: true; fahre nicht fort, bis der Mensch ihn entweder einer Entscheidung zuordnet oder einen out_of_scope-Eintrag in intent.yaml vornimmt.

Tor G4 — Bestätigung

Fordere den Menschen auf, das in einen diff-Modus versetzte Figma-Plugin zu öffnen, 02 To-Be Wireframes zu laden, die Ist-/Soll-Unterschiede zu überprüfen und dann fwd approve|reject|defer <D-id> im Terminal auszuführen. Wiederhole dies, bis alle Entscheidungen in einem endgültigen Zustand sind. Keine dieser Fähigkeit

[Anmerkung: Der Rest des Inhalts wurde aufgrund der Zeichenbegrenzung gekürzt. Bitte teilen Sie den vollständigen Text für eine vollständige Übersetzung.]