← Back to Preview Deck

AI agents

Operate Preview Deck from a coding agent. Full-document mutations, async jobs, a human review handoff.

How Preview Deck models a project

A project is a single creative concept. It contains:

  • Screenshots — the ordered list of canvas compositions that make up the App Store / Play Store story. Each screenshot has a background (gradient, solid colour, SVG, or image), zero or more device frames, text overlays, and image overlays.
  • Families — device variants the screenshots render onto. One family is the base; the rest cascade their layout from the base and apply per-family overrides only where necessary.
  • Layers — device frames, text overlays, and image overlays. Each is positioned by percent-of-canvas so a single composition adapts to multiple device aspect ratios.

Composition guidance

Hierarchy

Lead with one short headline (≤ 30 chars) at the top, supporting copy underneath, and the device frame anchored centre or bottom. Don't crowd more than three messages onto a single screenshot — the App Store reviewer scrolls fast.

Backgrounds

Pick ONE background slot per screenshot:

  • backgroundType: 'gradient' — set gradientCss.
  • backgroundType: 'solid' — set solidColor.
  • backgroundType: 'image' — set backgroundImage (upload or stock photo).
  • backgroundType: 'svg' — set svgBackground with one of the bundled presets.

Pre-feature documents may not have backgroundType; the normaliser back-fills it from whichever slot is populated.

Text effects

Use the shadows[], stroke, gradient, decoration, and blur fields on each text overlay rather than the legacy textShadow: string field. The latter is auto-migrated on save into a single structured shadow when present, and deprecated for new writes.

Image effects

Image overlays support borderRadius, blur, shadows[], and filters (brightness, contrast, saturation, hue rotation). Keep filters subtle — agents commonly oversaturate.

Overrides

Edits live on the base family by default. To diverge a single screenshot or layer for a derived family, set an entry in family.overrides[screenshotId][layerId|'__screenshot'].

  • __screenshotis the magic key for screenshot-level overrides (e.g. swap the background image for a 6.5" family). Exported as the constant SCREENSHOT_OVERRIDE_KEY.
  • Anything you can put on the underlying entity is a valid override field. The schema endpoint exposes the per-element subset.
  • Override only what differs. The base wins everywhere there's no override.

Asset rules

  • Every image asset in the document must live under <projectId>/<filename> in the Supabase storage buckets screenshots or overlays.
  • Get a signed upload URL via POST /api/agent/v1/projects/{id}/assets/uploads; PUT the bytes to the returned URL; reference the returned asset in the document. Anything else returns invalid_asset_reference.

Out of scope (phase 1)

Preview Deck's skill teaches operation, not screenshot strategy. If the user asks "what should I put on my screenshots", that's an external concern — recommend a marketing or copywriting workflow first, then operate Preview Deck once the user has decided.