Adding images

Getting one in

Three ways, all equivalent:

• Drop a file onto the canvas
• Paste an image you have copied
• Click the image icon in the element bar

The file is copied into assets/images inside your project and the element refers to it by a path relative to the project — never an absolute one, so the project still works when you move the folder or hand it to someone else.

Video and icons

The media button on the left rail opens three: picture, video, icon.

Video is copied into assets/images like any other asset and referred to by a project-relative path. Its Playback options are Controls, Autoplay, Loop, Silent and Inline, and there is a Still image field for the poster.

Choosing Autoplay also switches on Silent and Inline, and that is not the app being opinionated: a browser will not autoplay a video with sound — it is blocked and the video simply never starts — and on a phone it will not play at all unless it is inline. Three switches where two are prerequisites of the first would be three ways to make something that does not work.

Icon is an inline <svg>, not <img src="icon.svg">, and the difference is the reason to have it. Inline markup inherits currentColor, so an icon set to stroke="currentColor" takes the colour of the element — which means it takes a token, and moves when the palette does. A linked SVG is a picture that happens to be vector and can never do that.

Choosing an icon reads the file and puts its markup into the document; there is nothing left on disk to point at. The Markup field in the inspector is the <svg>’s contents, editable directly, and View box is its coordinate space.

A video behind a section

Under Fill › Image, on a section or a box: Use a video behind this…

CSS has no background-video and a layer cannot be one — a layer is a pseudo-element and cannot hold a <video> — so the backdrop is a real element, first in the section, positioned behind the content:

<section class="hero">
  <video class="hero__video" src="…" autoplay muted loop playsinline
         aria-hidden="true" data-backdrop></video>
  <div class="hero__container">…</div>
</section>

It is silent, looping and inline, always. A backdrop with sound does not play — browsers block it — and one that stops after twelve seconds and sits on a frozen frame is worse than no video at all. It has no controls and is hidden from screen readers, because it is scenery and there is nothing in it to describe.

Set a still image. Anyone who has asked for less motion sees it instead of the video — video that plays on its own is a motion trigger, and the still is the same design standing still. That is why the field is there rather than optional.

A picture, or a surface

An image added this way is an <img>: a real element, in the flow, with alt text. That is right for content — a photograph of a product, a portrait, a diagram.

A photograph behind a section is not content, it is a surface. It should crop rather than squash, it should sit under the text, and it should not be announced to a screen reader as a picture.

Set as background makes that change. It is on the right-click menu and on the editing bar when an image is selected. The box gets a height so it does not collapse to nothing, and the <img> is removed — two copies of one picture is how a document goes wrong.

It lands on whatever the image was in. Inside a card, the card. Inside a section’s content band, the band — which keeps the picture within your content width. If you want it to bleed past that, edge to edge across the whole section, select the section and set a background there instead.

Back to an image element reverses it.

Choosing one directly

You do not have to start with an <img>. A background is a fill, so it lives with the colours: select the element and go to Fill › Image, then Choose a picture…. The same panel replaces it and removes it.

Removing takes the size, position, repeat and scrolling with it, rather than leaving a background-position on an element that has no background.

Framing it

Crop is the one that matters, and it is on the hover bar as well as in Adjust:

Crop	Fills the box, cropping whatever does not fit. Usually what you want
Fit	Shows all of it, letterboxed
Stretch	Squashed to the box. Rarely what is wanted — images only
Actual	Its own size
Custom	A width and a height of your own — backgrounds only

An image given a width and a height squashes without this, which is the single most common thing to go wrong with a photograph on a page.

Custom is a measurement rather than a name, so it is typed: a width, and a height you can leave empty to mean whatever keeps it in proportion. It is on every background picture, including one on a layer. An <img> has no equivalent because it does not need one — its size is its own width and height, in Size.

Position is the nine cells, the same as alignment, because it is the same question asked of a different thing: which part of the picture you keep when the box is a different shape from the photograph. It appears once there is something to lose — on a background it is under Fill › Image, on an image it is in the Picture panel once you have cropped it.

Repeat — Once, Tile, Across or Down. Tiling a small picture is how you get a texture without a huge file.

Scrolling — three answers, and they are not the same mechanism underneath. You do not have to know which; the app writes whichever CSS the answer needs.

With the page	Moves with everything else
Parallax	Moves more slowly than the page
Held still	Does not move at all

Parallax

Movement is how far the picture travels, as a share of the section’s own height. 20% is a gentle drift; 50% is unmistakable.

A picture that moves has to be a box of its own, so choosing Parallax puts it on a layer — the panel follows it there, and the blue strip at the top says which layer you are in. The section gets a clip so the overhang never shows.

What comes out is a scroll-driven animation: no JavaScript, no scroll listener, no library. It moves the layer with translate, which the browser can run on the compositor without laying the page out again, and it is wrapped in prefers-reduced-motion: no-preference — movement tied to scrolling makes some people ill, and a designer choosing parallax has not chosen that. Anyone who has asked for less motion, and any browser without scroll-driven animations, gets the picture standing still. That is the design without the movement, not a broken one.

Unlike Held still, it is measured against the section — specifically the section’s own progress through the page — so it works at any section height and on a phone.

To see it, switch the canvas to Window and scroll. Page view fits the frame to the whole page, so there is nothing to scroll and nothing for the movement to be measured against: the parallax is correct and motionless, which looks exactly like it not working. The panel says so while you are in Page view.

Held still

Held still changes what the picture is measured against. It is sized and positioned against the browser window, never against the box it is in. That is what the property means, and no other setting changes it — Crop fills the window, and the box becomes a window onto the picture. Scrolling then moves the box while the picture stays put, which is the whole effect.

So Crop is the usual answer here, not the exception. A Custom width sizes the picture against the window too — useful when you want it at its own proportions rather than filling — but it is a different look, not a correction.

To see any of it, switch the canvas to Window. Page view has no window for the picture to be held still against, so the effect is invisible there — see Working on the canvas.

If you want a picture sized to the section that also holds still, that is not background-attachment — it needs a fixed layer clipped by the section, and it is not built yet.

All of these work the same way whether the picture is an image, a background, or one on a layer.

Seeing which one it is

Anywhere this app names a picture it also shows it — in the layers list, in the Picture panel of a selected image, and in Fill › Image. A filename is the one thing about a photograph that tells you least about it.

The Picture panel is also where the Description goes: what the image shows, for anyone who cannot see it. It is not optional and it is not decoration, so it is on the panel rather than somewhere you have to go looking.

Adjustments

An Adjust section appears on anything showing a picture — an image, an element with a background photograph, or a layer.

Brightness	100% is untouched
Contrast	100% is untouched
Saturation	100% is untouched; 0% is black and white
Blur	0 is untouched

These are sliders, and they are the one place in this app where you drag a number rather than pick one. A contrast is a judgement about this photograph — this one is flat, lift it — not a decision your design system makes on behalf of every photograph that will ever be placed, the way a padding or a type size is. There is no scale for them in GenCSS, so there is nothing to snap to, and pretending otherwise would mean inventing amounts nobody agreed to.

Leaving one at its neutral value writes nothing. brightness(100%) in your CSS would claim a decision was made when none was.

Blend is how the thing meets what is under it — Multiply, Screen, Overlay, Soft light, Darken, Lighten, Difference. It earns its keep on a layer: a wash set to Screen lifts the photograph beneath it instead of covering it. See Element layers.

Nothing here touches the file. All of it is reversible.

Putting something over an image

Add a layer. A layer is a box of its own over the element, so a wash and a photograph can be on the same element without one replacing the other — which is how you get a picture that fades to dark at the bottom so white text sits on it legibly. See Element layers.