image

When to use

• The visual carries meaning. Product screenshots, architectural photographs, plots, satellite imagery — anywhere the image makes the argument and the prose is annotation. If the visual is decorative, drop it and use content instead.
• Let the layout resolve it — override only with intent. Drop in any aspect and the layout reads it: a moderate photo gets the clean floated card, a tall/wide one gets split (shown whole), a canvas-matching one gets spotlight (full-bleed). Override only when you mean it: image gallery to contain a diagram zero-crop, image statement for a scrim-and-title hero, image spotlight to force a full-bleed cover (accepting the crop).
• Caption earns its line. If the prose alongside the image just describes what the image shows, drop it — the audience can see the picture. The text slot is for the so-what: what the audience should take away from the visual.

When not to use

• Decorative stock photo. A generic photograph of 'people in a meeting' next to a content slide is filler. Use content and trust the prose; reserve image for visuals that argue for themselves.
• Image too small to read. A diagram or screenshot small enough to fit inside a half-canvas text slot is unreadable from the back of the room. Reach for image gallery (contains it whole) or image spotlight, or move the diagram to its own diagram slide.
• Image with five paragraphs of caption. If the prose dominates and the image is a sidebar, you have a content slide that happens to have a photo. Either trust the image (drop the prose) or trust the prose (drop the image).

Common mistakes

• Writing plain image syntax ![alt](path) instead of Marp background syntax ![bg](path). The image slot renders the asset as a CSS background on .lattice-bg (no <img>) — without bg in the alt text the picture never becomes the section's background, and no composition can resolve around it.
• Naming a composition class (image spotlight, image gallery, …) reflexively instead of leaving it unset. The composition RESOLVES from the photo's own aspect ratio plus the deck orientation — an explicit class always wins over the resolver, so naming one out of habit can force a crop (e.g. spotlight's full-bleed cover) that the auto-picked clean/split composition would have avoided.

Authoring

<!-- _class: image -->

## Text leads; the image earns its place.

Swap the bg image below for your own asset — any aspect. The layout reads its shape and resolves the composition for you (a floated card, a full-height column, a full-bleed cover). Name a composition (`image spotlight`, `image gallery`, …) only to override.

![bg](sample-photo-wide.svg)

Slots

Anatomy

┌─────────────────────────────────────────┐
│  header                                 │
│                                         │
│  Text slot on     ┌──────────────────┐  │
│  the left, with   │                  │  │
│  optional         │   [image area]   │  │
│  caption.         │                  │  │
│                   └──────────────────┘  │
│                                         │
│  footer                           1/19  │
└─────────────────────────────────────────┘

Variant decision rule

• clean — The photo has a moderate, unremarkable aspect — the safe default; leave the class off and let the resolver land here for near-zero crop.
• split — The photo has an extreme aspect — a tall portrait or a full panorama — and must be shown whole, uncropped, in its own column or band.
• spotlight — The photo already matches the canvas's own aspect and can carry the whole slide full-bleed, with a solid text card guaranteeing legibility over it.
• gallery — The asset is a diagram or screenshot where whitespace and containment are the point — mats it whole on a matte with a placard, zero crop.
• statement — You want an editorial scrim-and-title hero treatment — a deliberate full-bleed gamble rather than the safe legible default.
• mirror — The composition is right but the deck's rhythm wants the image on the left instead of the right — flips the side without changing the composition.

Variants

<!-- _class: image clean -->

## clean drops the caption chrome.

Two-thirds of trials that reach the first generated report convert; the ones that stall almost never do.

![bg](sample-photo-wide.svg)

<!-- _class: image split -->

## split gives a portrait its full column.

A portrait photo wants its full height. We give it a column and let the argument run alongside.

![bg](sample-photo-tall.svg)

<!-- _class: image spotlight -->

## spotlight lets a panorama own the frame.

When the photo already matches the canvas, let it carry the slide — the message rides in a solid card so it never fights the image.

![bg](sample-photo-pano.svg)

<!-- _class: image gallery -->

## gallery mats the exhibit with a placard.

The whole asset on a matte with a placard. For diagrams and screenshots where the whitespace is the point.

![bg](sample-photo-square.svg)

<!-- _class: image statement -->

## statement rides the title on a scrim.

The title rides the photo on a scrim — a deliberate, editorial choice.

![bg](sample-photo-wide.svg)

<!-- _class: image mirror -->

## mirror lands the image on the left.

Text leads from the right; image anchors from the left.

![bg left](sample-photo-wide.svg)

Related

• diagramthe visual is a Mermaid graph, not a photo or screenshot
• contentthe slide is mostly prose with one inline visual
• titlethe image is a bookend hero, not the body of a slide
• quotethe slide is a quotation, not an image