Dokumentation

Fehlerbehebung & FAQ

Was du hier lernst

Häufige Prüfbefunde und wie du sie behebst, häufige Fragen und aktuelle Grenzen.

Prüfbefunde

Das Prüf-Abzeichen (App) und vitrine validate (CLI) melden Befunde pro Ziel und Sprache als Fehler, Warnung oder Hinweis. Bei Fehlern endet vitrine validate mit Exit-Code 1; mit --strict auch bei Warnungen. Die häufigsten:

CodeStufeBedeutung und Lösung
screenshot_missingFehlerkein Screenshot mit diesem Schlüssel in der Sprache oder ihren Fallbacks – ein Platzhalter wird gezeigt. Datei hinzufügen, oder beim Gestalten Vorschau-Modus / --preview nutzen.
screenshot_fallbackHinweisder Screenshot kommt aus einer Fallback-Sprache – in Ordnung.
screenshot_aspectWarnung (Hinweis)das Seitenverhältnis der Aufnahme weicht vom Display des Geräts ab – falsches Gerät oder falscher Ordner der Screenshot-Variante? Bis 5 % mit Einpassung: Füllen nur ein Hinweis: ein schmaler Rand wird abgeschnitten, z. B. iPhone-Screenshots im Android-Rahmen eines Google-Play-Ziels. Kann so bleiben; für eine exakte Passung Android-Screenshots in screenshots/<lang>/android-phone/ ablegen.
screenshot_upscaleWarnungdie Aufnahme wird mehr als 15 % vergrößert und wirkt evtl. unscharf – nimm eine Aufnahme von einem größeren Gerät.
text_overflowFehlerder Text passt selbst in der Mindestgröße nicht – siehe Lange Texte einpassen.
emergency_breakWarnungein Wort wurde ohne Bindestrich umbrochen – füge einen weichen Trennstrich \- ein.
hyphenatedHinweisder Text wurde automatisch getrennt – prüf das Ergebnis.
text_fallbackWarnung / HinweisText aus der Standardsprache („nicht übersetzt“, Warnung) oder aus einem anderen Fallback (Hinweis).
text_missingFehlerden Schlüssel gibt es in keiner Sprache – es wird nichts gezeichnet.
text_in_gap, text_clippedWarnungText ragt in eine Store-Lücke oder über seine Seite hinaus und wird abgeschnitten.
text_outside_safe_areaWarnungText außerhalb des sicheren Bereichs des Ziels.
low_contrastWarnungder Kontrast des Texts gegen das, was tatsächlich dahinter gezeichnet ist (Farbe, Verlauf, Foto, Muster), liegt unter WCAG AA – 4,5:1, große Schrift (ab 80 lu, fett ab 62 lu) 3:1. Die Meldung nennt Verhältnis, Stelle und was dort liegt (ein Element oder der eigene Schatten/Glow/Kontur des Texts, der als Hintergrund zählt); Farbe ändern, Scrim, Schatten oder Kontur ergänzen.
text_near_deviceWarnung / HinweisGlyphen liegen hinter einem Geräterahmen oder laufen über ihn (Warnung) oder kommen ihm näher als 16 lu (Hinweis). Text ganz auf dem Gerät oder auf einer Karte darüber ist in Ordnung.
screen_header_covered, screen_header_cutHinweisein Element verdeckt die obere Leiste (Statusleiste, App-Titel) eines Gerätebildschirms, oder eine Seiten-/Bildkante oder der Beschnitt des Geräts schneidet sie, sodass eine halbe Leiste stehen bleibt (die Meldung nennt die Kante).
screen_coveredHinweisein Element über einem Gerät verdeckt 15 % oder mehr seines Bildschirms unterhalb der oberen Leiste – den App-Inhalt, den der Screenshot zeigen soll.
device_cutHinweisder linke oder rechte Seitenrand (Beschnitt: Heimatseite) oder der äußere Leinwandrand schneidet mehr als 8 lu von einem Gerät ab – meist die Ecken eines gekippten Geräts. Anschnitt oben und unten wird nicht gemeldet.
seam_overlapHinweisein Element, das über eine Seitengrenze reicht, liegt über einem Element der Nachbarseite – Galerie prüfen.
seam_splitHinweiseine Form als zwei Hälften an einer Seitengrenze gebaut: die Store-Lücke zieht sie auseinander. Nimm ein Element mit Beschnitt: Keiner über die Grenze – es läuft in jedem Ziel hinter der Lücke durch.
element_in_cornerHinweisein Element ragt in eine Bildecke, die der Store abrundet (Teile unter einem deckenden Element darüber zählen nicht).
device_smallHinweisdas größte Gerät einer Seite füllt weniger als die Hälfte.
page_not_coveredHinweisein Bild oder eine Fläche deckt fast die ganze Seite, lässt aber einen schmalen Streifen frei (typisch, wenn eine Variante die Seitenhöhe ändert).
page_blends_with_storeHinweisdie Ränder der Bilder heben sich kaum vom hellen oder dunklen Store-Hintergrund ab.
missing_glyphsWarnungZeichen, die keine Schrift darstellen kann – füge eine Fallback-Schrift hinzu.
variant_suggestedHinweisdas Seitenverhältnis des Ziels weicht stark von der Leinwand ab – überleg dir eine Variante.
store_size, store_count, store_formatFehlerGröße, Bildanzahl oder Format passt nicht zum Store-Slot (zu wenige Bilder sind eine Warnung).
required_store_set_missingWarnungdas Projekt geht in einen Store, aber etwas, das der Store verlangt, fehlt. App Store: iPhone 6.3″ (ios-iphone-63), iPad 13″ (ios-ipad-13, erst wenn das Projekt iPad-Ziele hat) oder Mac. Google Play: Smartphone-Screenshots (play-phone) oder die Feature-Grafik (play-feature-graphic, ein Banner). Füge das Ziel aus diesem Preset hinzu. Export und Upload funktionieren trotzdem; ohne das reicht der Store die Version nicht ein bzw. veröffentlicht sie nicht.
imported_frame_missingHinweisApple-Bezels oder ein Frame-Paket sind hier nicht installiert – der eingebaute Rahmen wird gezeichnet.
imported_frame_not_storedHinweisein Ziel zeichnet Apple-Bezels, die nur dieser Rechner hat – CI würde den eingebauten Rahmen zeichnen; im Projekt speichern.
stored_frames_staleHinweisim Projekt gespeicherte Bezels werden nicht mehr verwendet, oder dieser Rechner hat einen neueren Import – gespeicherte Frames aktualisieren.
imported_frames_storedHinweisdas Projekt speichert Apple-Bezels – halte das Repository privat.
color_profile_unsupportedHinweisdas Farbprofil eines Bildes ist nicht nutzbar (CMYK, HDR) – es wird als sRGB gezeichnet.
background_hiddenWarnungeine Hintergrund-Ebene der Leinwand liegt unter einer deckenden und ist nie zu sehen – Leinwand-Hintergründe sind Ebenen, nicht einer pro Seite (siehe unten).

In der App springt Auf der Leinwand zeigen zum Element.

Die Gestaltungsprüfungen (low_contrast bis page_blends_with_store) rendern die Bilder; vitrine validate --no-pixel-checks lässt sie weg. Ist ein Befund gewollt – riesige angeschnittene Schrift, eine Beschriftung, die auf ein Gerät zeigt –, trag den Code in allow des Elements ein (allow: [text_clipped, low_contrast], auch an einer Gruppe). Schwellwerte und abgeschaltete Codes für das ganze Projekt stehen in project.yaml:

checks:
  device_distance: 16      # lu zwischen Glyphen und Geräterahmen
  min_contrast: 4.5
  min_contrast_large: 3
  screen_cover: 0.15       # Anteil eines Bildschirms, den ein Element verdecken darf
  off: [page_blends_with_store]

page_blends_with_store, variant_suggested und required_store_set_missing gehören zu keinem Element, deshalb kann allow sie nicht stummschalten; schalte sie für das ganze Projekt mit checks.off ab (z. B. wenn der verlangte Satz aus einem anderen Projekt kommt).

Welche Sprache geprüft wird. Alles zu Texten (low_contrast, text_near_device, die Befunde des Textlayouts) und Überlappungen über Seitengrenzen, an denen ein Text beteiligt ist, wird in jeder Sprache geprüft. Die Prüfungen zu Geräten, Seiten und Ecken laufen nur in der ersten Sprache jedes Ziels (der ersten Sprache des Projekts bzw. der eigenen Sprachliste des Ziels): screen_header_covered, screen_covered, screen_header_cut, device_cut, device_small, element_in_corner, page_not_covered, seam_split, page_blends_with_store, variant_suggested, seam_overlap zwischen zwei Elementen ohne Text und die Store-Regeln (store_size, store_count, store_format). Ein deutscher Screenshot, der ändert, wie ein Gerät oder eine Ecke aussieht, wird bei einer Prüfung über alle Sprachen also nicht geprüft. Für eine andere Sprache nimm vitrine validate --lang de oder wähl die Sprache in der App – das Prüf-Abzeichen prüft das aktuelle Ziel und die aktuelle Sprache – und sieh dir ihre Seiten an.

Fragen

Wo ist der Speichern-Knopf? Es gibt keinen – jede Änderung wird sofort gespeichert, als ein Rückgängig-Schritt.

Kann ich das Projekt in einem Texteditor oder mit Git bearbeiten, während die App offen ist? Ja. Änderungen auf der Platte werden live übernommen. Hast du im selben Moment in der App dasselbe geändert, lädt die App die Datei neu und sagt dir, dass deine letzte Änderung nicht gespeichert wurde.

Meine französische Überschrift ist winzig. Das automatische Einpassen hat sie verkleinert. Französisch braucht oft deutlich mehr Platz als Englisch – aus „Edit photos in seconds“ wird „Retouchez vos photos en quelques secondes“. Gib Französisch einen Sprach-Override mit breiterer Box oder höherer Mindestgröße, füge einen weichen Trennstrich ein oder schalte die Silbentrennung ein.

Ich habe der Leinwand eine Hintergrundfarbe pro Seite gegeben, aber alle Seiten haben dieselbe Farbe. Die Hintergründe der Leinwand sind Ebenen über der ganzen Leinwand, von unten nach oben – die oberste deckende verdeckt die anderen. Für eine Farbe (oder ein Foto) pro Seite leg auf jeder Seite ein Hintergrund-Element an; es füllt seine Seite in der Höhe jedes Ziels. Elemente werden in der Reihenfolge ihrer Ebene (z) und der Ebenenliste gemalt – halte Seitenhintergründe also unten (niedriges z).

Mein Hintergrund-Element ist hinter einem Foto verschwunden. Hintergrund-Elemente sind normale Ebenen: Ein deckendes Bild darüber in der Ebenenliste (oder mit höherem z) verdeckt sie. Schieb den Hintergrund nach unten oder gib dem Bild transparente Bereiche.

Das Phone sitzt bei Google Play zu hoch. Die 1:2-Seite von Google Play ist kürzer als die iPhone-Seite. Stell den Anker des Phones auf Unten oder verschieb es in einer Variante für das Play-Ziel.

Wie bekomme ich echte Apple-Geräterahmen? Lade die Product Bezels bei Apple herunter und importiere sie einmal – siehe Geräte & Rahmen. Die .dmg direkt zu importieren scheitert: Öffne sie im Finder, akzeptiere die Lizenz und importiere das eingehängte Volume.

Ein Kollege sieht andere Rahmen. Apple-Bezels und app-weite Frame-Pakete werden pro Computer gespeichert. Ohne sie wird der eingebaute Rahmen gezeichnet. Frame-Pakete, die du weitergeben darfst, gehören in den Ordner frames/ des Projekts; Apples Bezels muss jede Person selbst importieren.

Im Exportordner liegen alte Dateien. Ein erneuter Export entfernt Bilder, die Vitrine Studio früher geschrieben hat und nicht mehr erzeugt – aber nie andere Dateien. Fremde Dateien löschst du selbst.

Der Upload meldet „keine bearbeitbare App-Store-Version“. Lege in App Store Connect eine neue Version an und plane dann erneut. Weitere Meldungen unter Store-Upload.

Kann ich Vitrine Studio ohne die App nutzen, z. B. in CI? Ja – die CLI prüft, exportiert, importiert und lädt hoch; nimm auf Build-Rechnern das eigenständige CLI-Archiv und VITRINE_APP_DIR für einen separaten Einstellungsordner. Siehe Automatisierung.

Schickt Vitrine Studio Daten irgendwohin? Nur wenn du es darum bittest: Store-Uploads und Verbindungstests gehen an Apple oder Google, die Vorlagen-Galerie (in der App oder mit vitrine gallery) an api.vitrinestudio.app, und die tägliche Update-Prüfung fragt GitHub, ob es eine neue Version gibt (abschalten unter App-Einstellungen → Updates). Keine Statistik, kein Konto.

Kann ein KI-Assistent mein Projekt kaputt machen? Jede Änderung ist ein Rückgängig-Schritt mit dem Namen des Assistenten, und du siehst sie live. Store-Uploads brauchen deinen Klick. Siehe KI-Assistenten.

Aktuelle Grenzen

  • Rechts-nach-links-Layouts (Arabisch, Hebräisch) werden noch nicht gespiegelt.
  • Text in SVG-Bildern wird noch nicht gezeichnet.
  • Exporte gibt es nur in sRGB (keine Display-P3-Ausgabe).
  • Die Galerie-Lücken der nativen Store-Apps sind Schätzungen; die Store-Websites wurden gemessen.
  • Keine schwedischen Trennmuster.
  • Frame-Pakete in frames/ werden bei geöffnetem Projekt nicht neu eingelesen – öffne das Projekt nach Änderungen neu.

Hilfe bekommen

Melde Fehler und Ideen auf GitHub. Hänge bei Projektfragen die Ausgabe von vitrine validate --format json an – und nie Store-Schlüssel.

Diese Seite auf GitHub verbessern