Image SEO: alt text, formats, sizes and lazy loading

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Image SEO: alt text, formats, sizes and lazy loading

Images are usually the heaviest part of the production site and the part search engines and screen readers understand least. Fix them at the source: the image component, the upload pipeline and the templates, so every image is described, sized and served efficiently.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Delete original image files.
- Write alt text that stuffs keywords.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Inventory

List where images come from (static files, a CMS, user uploads, a CDN) and how they are rendered (a framework image component, plain `<img>`, CSS backgrounds). Report images with no alt, oversized files, missing width and height, and lazy loading on above-the-fold images.

### 2. Alt text

Meaningful images get alt text that says what they show in context; decorative images get `alt=""`. For dynamic images, build alt text from data (a product's name and what the screenshot shows). Add an alt field to upload forms where users add images.

### 3. Formats and sizes

Serve WebP or AVIF with fallbacks through the framework's image component or the CDN, responsive `srcset` and `sizes`, and source files resized to the largest size actually shown. Set width and height (or aspect ratio) on every image to prevent layout shift.

### 4. Loading

Lazy-load images below the fold; never lazy-load the main above-the-fold image, and give it `fetchpriority="high"`. Use descriptive file names for new images. Add important images to the sitemap if the site depends on image search.

## Done means

- [ ] Every meaningful image has alt text and decorative ones have empty alt.
- [ ] Images are served in modern formats at the sizes shown, with srcset where useful.
- [ ] Every image has width and height or an aspect ratio.
- [ ] Below-the-fold images lazy-load and the hero image does not.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.