WHY AN <img> AND NOT A BACKGROUND

Fair question, because background-image is the obvious spelling. It is also the one that cannot be lazy, cannot be found by the browser's preload scanner, cannot carry a srcset, and cannot say it is decorative.

The one that settles it is responsive art direction. Swapping a background by width takes a media query, and this system has none — while an <img> does the whole job with srcset and sizes, which are not breakpoints and ask the browser rather than telling it.

🛑 WHAT THE DEFAULT GUARANTEES, MEASURED

A photograph you have not seen yet is behind somebody's paragraph. That is a contrast problem with no page to look at, so it is answered with arithmetic: composite the two extremes an image can reach — an all-white frame and an all-black one — over all four of the library's surfaces, in both themes, at the shipped --ds-scene-strength.

So the rule is one sentence: a scene carries ink and ink-read. The two quiet inks cannot be rescued by mixing harder — the strength that would carry ink-faint is about a tenth, and a photograph at a tenth is a smudge. If you want a caption on a picture, that is what scene-foot is for: the band it clears is the surface itself, so the caption reads at its full ratio.

tools/check-theme.mjs holds the first two rows and prints all four, so a retheme cannot walk away from the promise quietly — and cannot leave this table out of date either.

🛑 THE FILM IS THE SURFACE, WHICH IS WHY THERE IS NO VEIL COLOUR

--scene-strength is the picture's opacity, so what it mixes into is whatever is actually painted behind it. Look at the third specimen: the same two classes on a cta slab put the photograph into cream, with no line of CSS anywhere that knows cream exists.

A --ds-scene-veil token would have to name one surface, and would then be visibly the wrong colour on the other three. This way the mix follows the box, for free, in every theme.

THE FADE IS A MASK, NOT A GRADIENT OVER THE TOP

A gradient veil leaves a thinning film of colour over the photograph, so the contrast where the words are still depends on the photograph. A mask removes the picture — the cleared band is the surface itself, at the full ratio the theme states, whatever the image turns out to be.

Between --scene-clean and --scene-full the picture is fading back in. No word belongs in that band.

🛑 A FADED VARIANT CLEARS A BAND, AND YOUR CONTENT HAS TO BE IN IT

This one is easy to miss because it fails quietly. Put scene-foot on a card that lays its content out from the top and the kicker lands on a photograph at full strength — which is the one thing the fade exists to prevent. It happened here while this page was being written, and it was a screenshot that found it, because nothing else can.

So a faded variant is two decisions, not one: pick the side, then put the content on it. The card in the third specimen pushes itself to the foot and widens --scene-clean until the band covers all three lines. If you would rather not think about it, that is exactly what the plain scene is for.

🛑 IT MAKES A STACKING CONTEXT, AND THAT COSTS SOMETHING

The picture sits at z-index: -1, which is what lets the content stay exactly as it was — no wrapper, no positioning of its own. A negative layer escapes to the nearest stacking context though, and without one here the photograph would slide behind the page and vanish, so .scene isolates.

The bill: anything inside a scene that lifts itself with z-index is now trapped in that box and can no longer paint over a later section. A panel that has to escape belongs outside the scene, or in the top layer where a modal already lives.

alt="" — ALWAYS, AND IT IS NOT POLITENESS

A picture behind a headline adds nothing that a reader of the headline has missed. Announcing "photograph of fog on a treeline" before the words is noise with an author's name on it. The media is also pointer-events: none for the same reason: it is scenery, and nothing may pick it up or drag it out of the page.

A picture that is content wants a frame, in the flow, with a real description.

IT PRINTS AS NOTHING, AND HIGH CONTRAST DROPS IT TOO

The same judgement grain makes: a decorative layer that costs ink or costs contrast is a decorative layer that goes. What is left is the section on its own surface, which is exactly the page this library drew before scenes existed.

A KNOB GOES WHERE ITS CLASS GOES

--scene-clean and --scene-full are read inside the scene-foot and scene-lead rules, so they are substituted on the element carrying that class. Put them on the section. --scene-strength and --scene-focus are read on the picture and take either element.

--scene-focus is an object-position, and it is the one setting here with no theme half. Where the subject sits in a photograph is a fact about that photograph — a theme has no opinion about it, so it is written per instance and nowhere else.

WHERE THE PICTURES CAME FROM

The library ships no images at all — the same decision it made about fonts, for the same reason. Everything on this page is the book's own, and Pictures lists all sixteen with the credit each one is owed.