--- title: "Tutorial — PageWeave Academy" --- # Figma zu PageWeave: Vom Screendesign zur Website API-first, MCP optional: Design-Spec extrahieren, mit dem Agenten bauen, sauber launchen. > Ein 1:1-Import gibt es nicht – und du brauchst ihn nicht. Extrahiere mit der Figma REST API eine kompakte Design-Spec aus Tokens, Sections und Screenshots. Briefe deinen Agenten damit und baue die Seite Section für Section in PageWeave. Figma MCP ist eine optionale Abkürzung, keine Voraussetzung. Ein Figma-Frame ist kein HTML. Er beschreibt, wie etwas aussehen soll – nicht, wie es sich bei 375 Pixeln, mit langen deutschen Wörtern oder per Tastatur verhält. Genau deshalb scheitert der Traum vom Ein-Klick-Import: Er überspringt die Entscheidungen, die eine Website erst benutzbar machen. Der bessere Weg ist unspektakulärer und funktioniert zuverlässiger. Du übersetzt das Design in eine **Design-Spec**: Tokens, Sections, Komponenten, echte Texte, Screenshots und offene Fragen. Diese Spec ist klein genug für den Kontext deines Agenten und präzise genug, um danach zu bauen. In diesem Tutorial baust du den kompletten Weg einmal durch: 1. Figma-Datei prüfen und für die Übergabe vorbereiten 2. Design-Spec über die Figma REST API extrahieren 3. Tokens nach PageWeave übersetzen 4. Den Agenten mit der Spec briefen 5. Die Seite Section für Section bauen 6. Responsive und barrierefrei prüfen 7. Veröffentlichen Am Ende hast du eine echte Seite – und einen Ablauf, den du für jedes weitere Design wiederverwenden kannst. ## Warum es keinen 1:1-Import gibt Figma und der Browser beantworten unterschiedliche Fragen. | Figma | Browser | | --- | --- | | Wie sieht der Frame bei 1440 px aus? | Wie verhält sich die Seite zwischen 320 und 2560 px? | | Welche Ebene liegt über welcher? | Welche Information kommt zuerst im DOM? | | Welche Füllung hat dieses Rechteck? | Welche Rolle hat dieses Element für Screenreader? | | Wie groß ist der Abstand im Frame? | Wie bleibt der Rhythmus bei anderem Text? | Ein Agent kann aus einem Frame sehr gut ablesen, **was gemeint ist**. Er kann nicht erraten, **wie es sich verhalten soll**. Deshalb ist die Übergabe keine Datei, sondern eine Übersetzung: Absicht, Regeln und Grenzen. > **Warum:** Wer dem Agenten nur einen Screenshot gibt, bekommt eine hübsche Momentaufnahme. Wer ihm Tokens, Section-Reihenfolge, Zustände und Regeln gibt, bekommt eine Website. ### Was die API liefert – und was nicht Die Figma REST API gibt dir: - die Dateistruktur mit Seiten und Frames, - Knoten mit Layout, Füllungen, Effekten und Text, - Komponenten und Instanzen, - Anmerkungen (Annotations), - gerenderte Bilder von Frames und Icons, - Bildfüllungen als separate Dateien. Sie gibt dir nicht: - das Verhalten zwischen Breakpoints, - Hover-, Fokus- und Fehlerzustände, die nicht gezeichnet sind, - semantische Entscheidungen (ist das ein Button oder ein Link?), - eine Garantie, dass eine Komponente im Code genauso heißen soll. Diese Lücken füllst du im Brief. Der Agent soll sie nicht erfinden. ## Was du brauchst - Ein Figma-Konto mit Zugriff auf die Datei. - Einen Figma-Personal-Access-Token mit `file_content:read`. - Einen PageWeave-Zugang. - Einen Agenten, der Dateien lesen und Shell-Befehle ausführen kann (OpenCode, Claude Code, Codex oder vergleichbar). - Optional: einen Full- oder Dev-Seat in Figma. View- und Collab-Seats haben ein sehr kleines API-Kontingent. > **Achtung:** Der Variables-Endpunkt der Figma API ist Enterprise-Organisationen vorbehalten. Du brauchst ihn nicht. Farben und Typografie stehen auch in Styles und Knotenwerten. Wer den Variables-Endpunkt voraussetzt, schließt die meisten Leser aus. ## Schritt 1 — Figma-Datei vorbereiten Die Extraktion ist nur so gut wie die Datei. Fünf Dinge entscheiden darüber, ob du danach raten musst: 1. **Benannte Frames.** `Hero`, `Features`, `CTA`, `Footer` statt `Frame 427`. 2. **Auto Layout** für alles, was aus Wiederholungen besteht: Navigation, Karten, Listen, Buttons. 3. **Tokens als Styles.** Farben, Textstile, Effekte. Keine Farben, die nur als Hex-Wert im Rechteck stecken. 4. **Drei Breiten.** Mindestens 375, 768 und 1440 – oder eine klare Regel, wie sich das Layout dazwischen verhält. 5. **Echte Inhalte.** Der längste Button-Text, ein langer Titel, ein leerer Zustand. „Lorem ipsum“ verdeckt genau die Probleme, die später auftreten. Zusätzlich hilfreich: - Komponenten mit Varianten für Default, Hover, Disabled und Focus. - Annotations an Frames, die das Verhalten erklären („stapelt unter 768 px“, „max. 3 Karten pro Reihe“). - Alt-Text-Notizen für informative Bilder. - Exportierte Icons als SVG, nicht als PNG. Wenn deine Datei diese Punkte nicht erfüllt, ist das kein Grund aufzugeben. Es ist eine Liste für den Designer – und ein ehrlicher Hinweis im Brief. ## Schritt 2 — Zugang zum Design wählen Es gibt drei Wege. Sie schließen sich nicht aus, aber sie haben unterschiedliche Rollen. | Weg | Funktioniert wo | Voraussetzung | Rolle | | --- | --- | --- | --- | | REST API | Überall, wo HTTP möglich ist | Read-only-Token | Standard | | Figma MCP | Nur in freigegebenen Clients | MCP-Client, Seat, OAuth | Optionale Abkürzung | | Manueller Export | Überall | Screenshots + Token-Tabelle | Fallback | Die API ist der Standard, weil sie unabhängig von deinem Agenten funktioniert. Figma MCP ist praktisch, aber an Clients, Versionen und Konten gebunden. Wenn dein Client nicht in Figmas MCP-Katalog steht oder die Anmeldung scheitert, ist das kein Showstopper – du nimmst die API. ### Token anlegen 1. Öffne Figma → Settings → Security → Personal access tokens. 2. Erstelle einen Token mit dem Scope `file_content:read`. 3. Optional: `library_content:read`, wenn du veröffentlichte Styles und Komponenten aus Bibliotheken brauchst. 4. Speichere den Token **nicht** im Repository. ```sh # .env — nicht committen export FIGMA_TOKEN="figd_..." export FIGMA_FILE="DEIN_FILE_KEY" ``` Den File-Key findest du in der URL: ``` https://www.figma.com/design/ABC123defGHI/Mein-Projekt └─────────┘ File-Key ``` > **Tipp:** Lege für die Übergabe einen eigenen, read-only Token an. Dann kannst du ihn nach dem Projekt widerrufen, ohne andere Integrationen zu beschädigen. ## Schritt 3 — Design-Spec extrahieren Jetzt holst du die Daten. Wichtig: **nicht alles auf einmal** und **nicht roh in den Agenten-Kontext**. Die Datei-JSON kann mehrere Megabyte groß sein. ### 3.1 Dateistruktur laden ```sh curl -sS \ -H "X-Figma-Token: $FIGMA_TOKEN" \ "https://api.figma.com/v1/files/$FIGMA_FILE?depth=2" \ -o figma-file.json ``` `depth=2` liefert Seiten und die obersten Frames, aber nicht jeden Textknoten. Das reicht, um die Section-Reihenfolge zu verstehen. ```sh jq -r '.document.children[].children[]? | "\(.id)\t\(.name)"' figma-file.json ``` Ausgabe: ``` 1:2 Hero 1:3 Features 1:4 CTA 1:5 Footer ``` ### 3.2 Ausgewählte Sections laden Jetzt holst du nur die Frames, die du wirklich brauchst: ```sh curl -sS \ -H "X-Figma-Token: $FIGMA_TOKEN" \ "https://api.figma.com/v1/files/$FIGMA_FILE/nodes?ids=1:2,1:3,1:4" \ -o figma-nodes.json ``` In den Knoten stehen unter anderem: - `layoutMode`, `paddingLeft`, `itemSpacing` (Auto Layout), - `fills`, `strokes`, `effects`, `cornerRadius`, - `style` mit Textstil und Schriftgröße, - `characters` mit dem echten Text, - `componentId` bei Instanzen, - `annotations` mit Übergabe-Notizen. ### 3.3 Screenshots rendern ```sh curl -sS \ -H "X-Figma-Token: $FIGMA_TOKEN" \ "https://api.figma.com/v1/images/$FIGMA_FILE?ids=1:2,1:3,1:4&format=png&scale=2" \ -o figma-renders.json jq -r '.images | to_entries[] | "\(.key)\t\(.value)"' figma-renders.json ``` Lade die URLs sofort herunter. Sie laufen nach 30 Tagen ab – Bildfüllungen schon nach 14 Tagen. ```sh mkdir -p screenshots jq -r '.images | to_entries[] | "\(.key) \(.value)"' figma-renders.json | while read -r id url; do curl -sS "$url" -o "screenshots/${id//:/_}.png" done ``` ### 3.4 Eine kompakte Spec bauen Du brauchst keine vollständige Kopie der API. Eine gute Spec hat sechs Teile: ``` design/ design-spec.json # Maschinenlesbar: Sections, Tokens, Komponenten design-brief.md # Menschenlesbar: Reihenfolge, Absicht, offene Fragen tokens.css # Farben, Typografie, Abstände, Radien screenshots/ # Ein Render pro Section assets/ # Icons und Bildfüllungen ``` Ein minimales `design-spec.json` kann so aussehen: ``` { "file": "Mein-Projekt", "version": "2329322981243290762", "sections": [ { "id": "1:2", "name": "Hero", "layout": "stack", "screenshot": "screenshots/1_2.png" }, { "id": "1:3", "name": "Features", "layout": "grid-3", "screenshot": "screenshots/1_3.png" } ], "tokens": { "color": { "ink": "#edecef", "paper": "#121118", "accent": "#a79bf5" }, "font": { "display": "Fraunces", "body": "Schibsted Grotesk" }, "space": { "section": "96px", "gap": "24px" }, "radius": { "card": "6px" } }, "unknowns": [ "Verhalten der Feature-Karten unter 768 px", "Fokus-Stil für Buttons nicht gezeichnet" ] } ``` Die `unknowns` sind kein Makel. Sie sind der wichtigste Teil der Übergabe, weil sie verhindern, dass der Agent stillschweigend rät. > **Checkpoint:** Du hast eine Datei, die du in unter einer Minute lesen kannst, plus Screenshots pro Section. Wenn dein Agent 50.000 Zeilen JSON analysieren muss, hast du noch keine Spec. ### 3.5 Limits respektieren - **Tier 1** (Datei, Knoten, Bilder): etwa 10 Anfragen pro Minute bei Pro Full/Dev. - **View/Collab-Seats:** teils nur wenige Anfragen pro Monat. Ein einziger Extraktionslauf kann das Kontingent aufbrauchen. - **HTTP 429:** `Retry-After` lesen und warten. Nicht parallel nachfeuern. - **Cache:** Nach `version` cachen. Unveränderte Dateien nicht erneut rendern. > **Achtung:** Wenn du im Team arbeitest, lass die Extraktion von jemandem mit Full- oder Dev-Seat laufen. Ein Viewer-Seat ist kein API-Zugang. ## Schritt 4 — Tokens nach PageWeave übersetzen Tokens sind der Teil, der sich am direktesten übertragen lässt. Übersetze sie einmal, dann gelten sie für jede Section. ### Von Figma zu CSS ```css :root { --paper: #121118; --paper-2: #191820; --ink: #edecef; --ink-dim: #b9b6c4; --iris: #a79bf5; --rule: rgba(237, 236, 239, 0.12); --font-display: "Fraunces", Georgia, serif; --font-body: "Schibsted Grotesk", system-ui, sans-serif; --font-mono: "IBM Plex Mono", monospace; --space-section: clamp(3.5rem, 7vw, 6rem); --space-gap: 1.5rem; --radius-card: 6px; } ``` ### PageWeave-Theme setzen PageWeave nutzt daisyUI-Farben. Du kannst deine Tokens auf die semantischen Variablen abbilden: ```css [data-theme="academy"] { color-scheme: dark; --color-base-100: #121118; --color-base-200: #191820; --color-base-300: #23222b; --color-base-content: #edecef; --color-primary: #a79bf5; --color-primary-content: #15121f; --color-secondary: #8b5cf6; --color-secondary-content: #ffffff; --radius-box: 6px; } ``` Wichtig: - **Namen behalten.** Wenn dein Token in Figma `surface/raised` heißt, dokumentiere die Zuordnung. Sonst findet sie niemand wieder. - **Keine Halb-Tokens.** Ein Hex-Wert, der nur einmal vorkommt, ist kein Token, sondern eine Entscheidung. Schreibe sie in den Brief. - **Kontrast prüfen.** Ein schönes Grau aus Figma kann bei 14 px gegen WCAG AA verstoßen. Prüfe Textpaare, nicht nur Flächen. - **Fonts laden.** PageWeave liefert Schriften über `fonts.pageweave.dev`. Lade nur die Schnitte, die du wirklich verwendest. > **Warum:** Tokens sind der Vertrag zwischen Design und Code. Wenn der Agent später eine Farbe „ähnlich“ macht, hast du keinen Vertrag, sondern eine Meinung. ## Schritt 5 — Den Agenten briefen Jetzt wird aus der Spec ein Auftrag. Der Prompt sollte kurz sein, weil die Details in den Dateien stehen. ``` Du baust die Seite / für in PageWeave. Quellen: - design/design-brief.md - design/design-spec.json - design/tokens.css - design/screenshots/ - design/assets/ Ziel: Zielgruppe: Stack: semantisches HTML, Tailwind + daisyUI, PageWeave MCP. Regeln: - Lies design-brief.md, nicht das rohe Figma-JSON. - Übernimm Tokens aus tokens.css. Keine neuen Farben. - Keine erfundenen Texte. Fehlende Inhalte als TODO markieren. - Keine Inline-Styles, keine Inline-Skripte. - Responsiv bei 375, 768 und 1440 px. - WCAG-AA-Kontrast, sichtbarer Fokus, logische Heading-Reihenfolge. - Bilder nur aus design/assets/. Vorgehen: 1. Fasse Tokens, Sections und offene Fragen zusammen. Warte auf mein OK. 2. Baue eine Section. Zeige mir die Vorschau. 3. Vergleiche Screenshot und Vorschau. Liste Abweichungen, bevor du sie behebst. 4. Erst dann die nächste Section. ``` Der wichtigste Satz ist Schritt 1. Wer den Agenten sofort bauen lässt, bekommt zehn Entscheidungen, die niemand freigegeben hat. ### Was in den Brief gehört - **Section-Reihenfolge** und die Aufgabe jeder Section. - **Tokens** mit Figma-Namen und CSS-Namen. - **Komponenten** und ihre Varianten. - **Echte Texte** oder die ausdrückliche Erlaubnis, Platzhalter zu setzen. - **Zustände**, die nicht gezeichnet sind: Hover, Fokus, leer, Fehler, langsam. - **Grenzen**: Was der Agent nicht anfassen darf. - **Offene Fragen** mit einer Empfehlung, nicht nur einem Fragezeichen. ## Schritt 6 — Seite bauen In PageWeave angekommen, arbeitest du am besten in dieser Reihenfolge: 1. **Website und Theme.** Website anlegen, Theme mit den Tokens setzen, Schriften laden. 2. **Header und Footer.** Als Komponenten, damit sie auf jeder Seite identisch sind. 3. **Sections.** Eine nach der anderen. Nach jeder Section: Vorschau bei 375, 768 und 1440 px. 4. **Inhalte.** Echte Texte ersetzen Platzhalter. Lange Labels testen. 5. **Zustände.** Fokus, Hover, Fehler, leer. 6. **Metadaten.** Titel, Beschreibung, Open Graph, strukturierte Daten. > **Tipp:** Lass den Agenten nicht die ganze Seite in einem Schritt schreiben. Section für Section ist langsamer, aber du siehst Fehler, bevor sie sich durch acht Sections ziehen. ### Was der Agent über PageWeave wissen muss - Seiten sind versioniert. Eine Änderung erzeugt eine neue Version. - Header, Footer und `` sind Komponenten, keine Seiteninhalte. - CSS und JS liegen als Snippets unter `/snippets/...`. - Tabellen sind öffentlich, sobald Zeilen veröffentlicht sind. Keine internen Notizen dort ablegen. - Die Vorschau zeigt Änderungen sofort; die Live-Seite erst nach dem Veröffentlichen. ## Schritt 7 — Responsive und barrierefrei prüfen Ein Screenshot bei 1440 px beweist fast nichts. Prüfe systematisch: | Prüfung | Worauf du achtest | | --- | --- | | 375 px | Kein horizontaler Scroll, Tap-Ziele ≥ 44 px, Text bricht sauber | | 768 px | Grid wechselt sinnvoll, Navigation bleibt bedienbar | | 1440 px | Zeilenlänge begrenzt, Inhalte nicht auseinandergezogen | | Lange Texte | Buttons, Karten und Navigation halten stand | | Tastatur | Alles erreichbar, Fokus sichtbar, Reihenfolge logisch | | Kontrast | Text ≥ 4,5:1, große Schrift ≥ 3:1 | | Struktur | Eine H1, keine übersprungenen Ebenen, Landmarks | | Bilder | Alt-Text vorhanden, dekorative Bilder leer | | Bewegung | `prefers-reduced-motion` respektiert | > **Checkpoint:** Du kannst die Seite mit der Tastatur bedienen, ohne die Maus zu benutzen. Wenn nicht, ist sie nicht fertig. ### Häufige Fehler | Fehler | Ursache | Lösung | | --- | --- | --- | | Alles sieht bei 1440 gut aus, mobil bricht es | Nur ein Frame designt | Drei Breiten oder klare Regeln im Brief | | Schriften wirken falsch | Figma-Schrift nicht geladen | Font-Schnitt und Fallback prüfen | | Buttons ohne Fokus | Zustand nicht gezeichnet | Fokus-Stil definieren, nicht raten | | Agent erfindet Texte | Keine echten Inhalte übergeben | Texte mitliefern oder TODO erlauben | | Farben „fast“ richtig | Tokens nicht übergeben | Tokens als CSS-Variablen | | API-Limit erreicht | Zu viele Einzelanfragen | Batching, Cache, Full/Dev-Seat | ## Schritt 8 — Veröffentlichen Vor dem Launch: - [ ] Titel ≤ 60 Zeichen, Beschreibung 150–160 Zeichen. - [ ] Open-Graph-Bild in 1200 × 630. - [ ] Kanonische URL und `hreflang` gesetzt. - [ ] Sitemap und Feed erreichbar. - [ ] Formulare getestet, Spam-Schutz aktiv. - [ ] Analytics ohne Cookies aktiv. - [ ] Impressum und Datenschutz verlinkt. - [ ] Hostname verbunden, SSL gültig. - [ ] `indexable` erst jetzt auf `true`. > **Achtung:** Eine Website ist nicht fertig, weil sie lädt. Sie ist fertig, wenn Inhalt, Recht, Technik und Betrieb geprüft sind. ## Weiterlesen - [Figma-Datei für die Übergabe vorbereiten](/tutorials/figma-datei-vorbereiten) - [Design-Tokens von Figma nach PageWeave](/tutorials/design-tokens-figma-pageweave) - [Responsive QA: 375, 768, 1440](/tutorials/responsive-qa) - [Deine erste Website mit einem KI-Agenten](/tutorials/erste-website-mit-agent)