Complete missing website media from a coding agent

Define the missing-media contract before asking for pixels

Treat a missing website image as a code task with a visual dependency, not as an invitation to generate something vaguely attractive. First inspect the route, component, layout breakpoint, nearby copy, existing asset directory, image component, naming rules, and build scripts. Write a small contract that names the image's job, subject, context, required crop, rendered dimensions, acceptable file types, size budget, rights constraints, alt-text decision, reviewer, and pass condition. If the visual cannot be described without inventing a product claim, customer, interface, or result, stop and ask for an approved brief.

Separate requirements that generation can address from requirements that code must enforce. The prompt can guide composition, lighting, negative space, and subject treatment. It cannot prove that a generated product is accurate, choose the correct semantic role in the page, create responsive derivatives, preserve a repository's conventions, or confirm that the build still passes. Those remain review and implementation work.

Make the intended slot concrete before spending. A useful acceptance note might say: one reviewed hero illustration, no baked-in headline, subject kept outside the mobile text-safe area, repository-native filenames, responsive sources produced by the existing image pipeline, explicit dimensions, and a contextual text alternative. This gives the coding agent observable checks instead of permission to replace one missing file with an unreviewed output.

Visual contract

Purpose, crop, safe area, and prohibited claimsTie the brief to the actual component and nearby copy.

Repository contract

Path, naming, formats, dimensions, and build checksUse the project's existing media conventions rather than creating a parallel pipeline.

Review contract

Named reviewer and written pass conditionDo not patch a paid generation into the project merely because the job completed.

Keep generation, finishing, and code mutation as three reviewable stages

Stage one produces a candidate. The current `@offlinecreator/mcp` package exposes separate tools for listing models, checking credits, starting a generation, checking or waiting for status, and obtaining a completed output. Its version-pinned server says `download_output` returns a short-lived signed URL rather than streaming image bytes into model context. Save the candidate promptly to a temporary working location, retain the generation identifier and prompt record, and do not treat the signed URL as a durable site asset.

Stage two turns an approved candidate into repository-ready media. Review the image at the intended desktop and mobile crops. Reject hallucinated lettering, misleading interface details, distorted products, unsafe content, poor focal placement, or anything that conflicts with the page. Then use the repository's established image tooling to create only the required derivatives, preserve aspect ratio unless an approved art direction says otherwise, record intrinsic dimensions, and compare output size against the written budget. This page does not assume that the MCP generation tool performs those finishing operations.

Stage three is a narrow patch. Move the approved files into the existing asset location, update only the owning component or content record, add the context-specific alternative, and run the project's formatter, static checks, build, and relevant visual or accessibility review. Show the reviewer both the rendered page and the diff. If the project has no established optimization command or image convention, pause for an implementation decision rather than silently choosing a new dependency or format.

1. Generate

Candidate plus generation recordA completed provider job is an input to review, not approval.

2. Finish

Approved, sized repository assetsUse existing local tooling and document every derivative.

3. Patch

Small diff plus rendered verificationKeep unrelated code and media outside the change.

Choose alt text from the image's purpose on this page

Do not ask a vision model for generic alt text and paste the answer unchanged. W3C's image guidance makes the decision contextual: an informative image needs a brief alternative that conveys its essential information; a decorative or nearby-redundant image uses an empty `alt`; a linked or button image describes the function; an image of text includes the words when they are not otherwise available; and a complex image needs its information elsewhere on the page. The same pixels can therefore require different alternatives in different placements.

Write the alternative after the approved image is placed beside final copy. Describe what the image contributes to the reader's understanding, not every visible detail, and do not start with a filename or placeholder such as “image.” If the hero is decorative because the adjacent heading and body already carry the complete message, use the repository's correct empty-alt pattern. If it introduces information absent from the copy, state that information concisely. If it depicts a generated product or interface that is merely conceptual, revise the visual or nearby disclosure rather than letting alt text imply authenticity.

WCAG 2.2 Success Criterion 1.1.1 requires presented non-text content to have a text alternative serving an equivalent purpose, subject to its listed exceptions. Passing this gate therefore requires semantic inspection of the rendered component, not merely confirming that an `alt` property exists. Review the accessibility tree or the framework's rendered HTML, and verify that decorative media is ignored while meaningful media has an equivalent alternative.

Informative

Describe the essential contributionUse page context, not a detached inventory of pixels.

Decorative or redundant

Use the project's empty-alt patternDo not force screen-reader users through repeated nearby copy.

Functional or complex

Name the action or provide the information elsewhereA visual description alone may not serve the same purpose.

Verify responsive delivery in the rendered markup

Optimization is a delivery decision, not a request to make one file smaller at any cost. Start with the component's actual rendered widths and the repository's supported pipeline. Produce the minimum useful source set, retain a fallback accepted by the project, and avoid upscaling a small generation into a soft large hero. Compare each derivative visually at the crop where it will appear; an efficient file that loses the focal subject or makes embedded detail unreadable has failed the slot.

The HTML Standard documents two distinct controls worth checking in the final markup. `srcset` with `sizes` lets a user agent choose among width variants using the declared rendered size, pixel density, zoom, and potentially network conditions. Explicit `width` and `height` let the user agent allocate image space before download. The exact framework syntax may differ, so inspect the generated HTML rather than assuming that a component name or import automatically produced the intended candidates and dimensions.

Run the page at the breakpoints named in the visual contract. Confirm that the right asset is requested, the subject survives cropping, dimensions reserve the intended space, the text-safe area remains usable, and no temporary or signed provider URL appears in source. Then run the repository's normal build and tests. Record observed file sizes and candidate selection as verification evidence, not as a universal performance claim.

Source set

Only widths the layout can useMatch generated derivatives to measured component widths.

Intrinsic size

Width and height present in final markupVerify rendered output rather than trusting source abstractions.

Stable source

Repository asset or approved durable delivery pathNever commit a short-lived generation URL as the page source.

Choose the next route from the remaining risk

Return to the creator-use-case hub when the team has not yet selected a concrete media outcome. Use draft-first publishing when the repository patch is complete but delivery to a public channel still needs a separate approval boundary. Use human-approved creative automation when the larger workflow needs explicit gates before spend, mutation, or release. These links preserve this page's narrow ownership: one missing website-media slot taken from brief through reviewed code patch.

Keep the evidence boundary visible

This page owns “mcp codebase media completion”: defining one missing slot, generating a candidate through a current tool surface, reviewing it, preparing repository-native derivatives, choosing contextual alternative text, making a narrow patch, and checking the result. It does not own general MCP setup, autonomous site redesign, model rankings, universal image-performance targets, publishing automation, or a claim that generated media is accurate or accessible by default.

The recent-source run returned 85 items with degraded coverage: X credentials were not configured, Reddit ended partial (telemetry state partial; no HTTP status recorded in this run’s stderr), and arXiv, Polymarket, and Techmeme returned no results. None of the retrieved items, including ranked adjacent MCP, coding-agent, or website-QC posts, documented generating, reviewing, optimizing, describing, and patching missing website media. Those adjacent items are not used to support adoption, practitioner consensus, reliability, speed, savings, output quality, or customer outcomes. Current product statements come from the version-pinned first-party package README and compiled schema; accessibility and responsive-image statements come from current W3C and WHATWG documentation.

Keep this page in draft until editorial review confirms that the product surface, standards guidance, and implementation boundaries remain current. Re-check the live package before execution, because this snapshot cannot establish future tools or behavior. npm also lists @offlinecreator/mcp 0.1.2; product claims on this page remain pinned to the verified 0.1.1 README and schema. If developer workflow evidence and accessibility checks can no longer support a distinct end-to-end decision path, consolidate the topic into the parent creator-use-case hub instead of expanding the page with unsupported claims.