Adaptive Media Source Component

Serve each image and video at a size and format the viewer's device can actually use.

involved Front-End Performance

What it adds

One media component that chooses source, format, and dimensions from the rendered box and the browser's declared support.

What your agent is told to do

1
Find every place the app renders a raw image or video element and route them all through a single component, so source selection is decided in one place rather than per template.
2
Derive the candidate widths from the sizes the element is genuinely rendered at across the app's breakpoints, and describe those sizes to the browser accurately — an inaccurate size hint is worse than none.
3
Always render an intrinsic width and height or an aspect ratio, so the box occupies its final space before any bytes arrive.
4
Offer modern formats with a defined fallback order, and confirm the fallback renders when the preferred format is unsupported or its derivative is missing.
5
Do not generate the derivatives here. Producing and storing sized, compressed files belongs to the Visual Asset Optimization Pipeline brief; this component only chooses among derivatives that already exist and falls back to the original when one does not.

Edge cases it handles

Space must be reserved before the media loads. Without intrinsic dimensions, every image on the page pushes the content below it down as it arrives, and a reader loses their place mid-sentence.
Private and access-controlled media must stay private. A transformation or resizing URL must not become an unauthenticated public read of an asset the viewer would otherwise need permission to see.
A device with a high pixel ratio will request enormous sources unless the ladder is capped. Clamp the effective multiplier so a phone does not download a four-thousand-pixel image to fill a thumbnail.
A transformed source that returns an error or an unsupported format must fall back to the original rather than leaving a broken element in the layout.
Video needs a poster image sized by the same rules, and autoplay must be suppressed where the viewer has asked to reduce motion or is on a metered connection.
Decorative media takes an empty alternative text so it is skipped by screen readers; meaningful media must carry text that survives the source swapping.
Where a crop differs by breakpoint rather than just resolution, the component must select a different crop, not merely a smaller version of the wide one.

Definition of done

Every image and video in the app renders through the one component.
Each element reserves its final dimensions before the source loads.
The width served matches the rendered size, with a capped multiplier for high-density screens.
An unsupported format or a missing derivative falls back to the original with nothing visibly broken.
Access-controlled media cannot be read through a transformation URL without authorization.
Alternative text is preserved regardless of which source is chosen.
Derivative generation is delegated to the asset pipeline rather than reimplemented in the component.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Visual Asset Optimization Pipeline

Bundle-Aware Component Imports

Layout Shift Guard

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.