Mockup asset specification
Browser code cannot render Photoshop files directly. A photo mockup is converted once during development and then stored as a small browser-ready bundle.
Preferred Photoshop structure
- A separate Smart Object for the screen, ideally named
[SCREEN DESIGN]. - Device, frame, hand, reflections and shadows on layers outside the screen Smart Object.
- A removable background group so the final overlay can be exported with transparency.
- A portrait Smart Object whose aspect ratio matches the intended device screenshot.
- At least 1600 px width for the final transparent overlay.
The Smart Object transform must still be present. Its four transformed corners are used in this order:
- top left
- top right
- bottom right
- bottom left
Runtime bundle
Each perspective mockup consists of:
- a transparent PNG or WebP overlay containing the frame, hand and lighting;
- the overlay's original aspect ratio;
- the flat screen's aspect ratio;
- four normalized screen corner coordinates in
catalog.ts.
Example:
{
overlay: tiltedHandOverlay,
canvasAspectRatio: 4409 / 3728,
sourceAspectRatio: 1392 / 3017,
screenQuad: [topLeft, topRight, bottomRight, bottomLeft],
}
Shotluma calculates a projective matrix3d from these points. Uploaded screenshots are therefore distorted into the original Photoshop perspective instead of merely being rotated.
At runtime, real screenshots use a perspective source plane at least as wide as the rendered mockup. This matters for native-size HTML screens that are scaled down in the editor: it prevents the browser from enlarging a small intermediate texture before the outer scale is applied. Placeholder screens retain their fixed reference plane because their generated UI uses absolute CSS pixel sizes.
What does not work
A single flattened JPG is not enough: the original screen cannot be removed cleanly and there are no reliable perspective coordinates. A flattened transparent PNG can be used only when the display area is already empty and its four corners are supplied manually.
Before adding third-party mockups, confirm that their license permits use in generated App Store artwork.