Die meisten Figma-Übergaben scheitern nicht an der API. Sie scheitern daran, dass die Datei keine Struktur hat: Frames heißen Frame 427, Abstände sind absolut positioniert, Farben stecken als Hex-Werte in Rechtecken, und der einzige Inhalt ist Lorem ipsum.

Eine gute Übergabedatei ist keine schönere Datei. Sie ist eine lesbare Datei – für Menschen, für Agenten und für die API.

Diese Checkliste ist die Vorbereitung für Figma zu PageWeave. Du kannst sie auch unabhängig nutzen, wenn du mit einem Entwickler oder Agenten arbeitest.

1. Frames und Ebenen benennen

Der Name ist der erste Kontext, den ein Agent sieht. Hero, Features, Testimonial, CTA, Footer sagen etwas. Frame 427 sagt nichts.

Regeln:

  • Ein Frame pro Section. Keine verschachtelten Frames, die nur zur Optik existieren.
  • Substantive statt generische Namen. FeatureCard statt Group 12.
  • Keine Duplikate mit Suffixen. FeatureCard, FeatureCard 2, FeatureCard 3 sind ein Hinweis auf fehlende Komponenten.
  • Deutsch oder Englisch, aber konsistent. Die Sprache ist egal; der Wechsel nicht.

Tipp: Wenn du einen Frame nicht in einem Satz beschreiben kannst, ist er wahrscheinlich keine Section, sondern ein Layout-Detail.

2. Auto Layout statt absoluter Position

Absolute Positionen beschreiben einen Zustand. Auto Layout beschreibt eine Regel. Der Unterschied wird sichtbar, sobald Text länger wird oder der Viewport schmaler.

Nutze Auto Layout für:

  • Navigation und Button-Gruppen,
  • Karten und Listen,
  • Formulare,
  • alles, was sich wiederholt.

Definiere dabei bewusst:

  • Richtung: horizontal oder vertikal.
  • Abstand: fester Wert oder space-between.
  • Padding: oben, rechts, unten, links.
  • Resize-Verhalten: fixed, hug oder fill.

Diese vier Angaben landen in der API als layoutMode, itemSpacing, padding* und layoutSizing*. Der Agent kann sie lesen – aber nur, wenn sie gesetzt sind.

Achtung: Ein Frame ohne Auto Layout zwingt den Agenten, Abstände aus Pixeln zu raten. Das funktioniert bei einem Screenshot und scheitert bei fünf Breiten.

3. Tokens als Styles anlegen

Farben und Typografie sollten als Styles existieren, nicht als Einzelwerte.

  • Color Styles für Flächen, Text, Linien und Zustände.
  • Text Styles für Display, Heading, Body, Label und Code.
  • Effect Styles für Schatten, falls du sie brauchst.

Benenne sie nach Rolle, nicht nach Aussehen:

color/surface/default
color/surface/raised
color/text/primary
color/text/muted
color/border/subtle
color/accent/default

type/display/xl
type/heading/lg
type/body/md
type/label/sm

color/blue-500 ist ein Wert. color/accent/default ist eine Entscheidung. Der zweite Name überlebt einen Rebrand.

Warum: Die Figma Variables API ist Enterprise-only. Styles und Knotenwerte funktionieren in jedem Plan. Wer Tokens nur als Variables pflegt, verliert sie außerhalb von Enterprise.

4. Komponenten und Varianten

Wiederkehrende Elemente gehören als Komponente in die Datei:

  • Buttons mit Default, Hover, Focus, Disabled.
  • Karten mit und ohne Bild.
  • Navigation mit Desktop und Mobile.
  • Formularfelder mit Default, Focus, Error.

Der Agent muss nicht jede Variante bauen. Aber er muss wissen, dass sie existiert. Sonst erfindet er einen eigenen Hover-Zustand – und du bekommst drei verschiedene.

Wenn eine Komponente nur einmal vorkommt, ist sie keine Komponente. Das ist okay. Erzwinge keine Abstraktion, die es im Design nicht gibt.

5. Drei Breiten – oder eine klare Regel

Ein Desktop-Frame reicht nicht. Das Minimum:

  • 375 px für kleine Phones.
  • 768 px für Tablets.
  • 1440 px für Desktop.

Wenn du keine drei Frames zeichnen willst, dokumentiere das Verhalten:

  • Welche Elemente stapeln?
  • Welche Reihenfolge ändert sich?
  • Was wird ausgeblendet – und warum?
  • Wo bricht Text um?
  • Welche Navigation bleibt sichtbar?

Schreibe die Regel als Annotation an den Frame. Ein Satz ist besser als ein fehlender Frame.

Checkpoint: Für jede Section gibt es entweder drei Frames oder eine geschriebene Regel für dazwischen. „Macht der Entwickler“ ist keine Regel.

6. Echte Inhalte und Zustände

Lorem ipsum verdeckt die drei häufigsten Layout-Probleme:

  1. Ein Button-Text ist länger als der Platz.
  2. Eine Überschrift bricht in drei Zeilen.
  3. Eine Liste hat null oder zwanzig Einträge.

Nimm echte Texte aus dem Projekt. Wenn es sie noch nicht gibt, schreibe realistische Platzhalter – keine Füllsätze.

Zeichne zusätzlich, wenn möglich:

  • leeren Zustand,
  • Fehlerzustand,
  • Ladezustand,
  • sehr langen Text.

Diese Zustände sind keine Kür. Sie sind der Unterschied zwischen einer Demo und einer Website.

7. Annotations für das Verhalten

Figma-Annotations sind der Ort für alles, was man nicht sieht:

  • „stapelt unter 768 px“
  • „max. 3 Karten pro Reihe“
  • „Button wird bei fehlendem Link deaktiviert“
  • „Bild ist dekorativ, Alt-Text leer“
  • „Fokus-Ring: 2 px, Abstand 2 px“

Die REST API liefert Annotations mit dem Knoten. Sie landen in der Design-Spec – vorausgesetzt, du hast sie geschrieben.

8. Assets vorbereiten

  • Icons als SVG, nicht als PNG.
  • Fotos in ausreichender Auflösung, aber nicht in 8000 px.
  • Keine Schriften, die du nicht lizenzieren kannst.
  • Dateinamen, die man lesen kann: logo-academy.svg, nicht Frame 12 (1).svg.

Bildfüllungen kannst du über die API als separate Dateien exportieren. Plane dafür Zeit ein: Die URLs laufen ab, und du willst sie nicht während des Builds suchen.

Checkliste

  • Jede Section ist ein benannter Frame.
  • Auto Layout ist für wiederkehrende Strukturen gesetzt.
  • Farben und Typografie sind Styles, nicht Einzelwerte.
  • Komponenten haben die Zustände, die gebraucht werden.
  • Drei Breiten oder eine geschriebene Regel.
  • Echte Texte, lange Labels, leere und Fehlerzustände.
  • Annotations für Verhalten und Barrierefreiheit.
  • Icons als SVG, Bilder in sinnvoller Auflösung.
  • Dateinamen sind lesbar.

Häufige Fehler

Fehler Folge Fix
Nur ein Desktop-Frame Mobile wird geraten Drei Breiten oder Regeln
Farben als Hex-Werte Tokens fehlen in der Spec Color Styles anlegen
Keine Komponenten Jede Section wird neu gebaut Wiederholungen als Komponente
Lorem ipsum Layout bricht bei echten Texten Echte Inhalte verwenden
Keine Annotations Verhalten wird erfunden Verhalten an den Frame schreiben

Weiterlesen