CMS Media Variants, Alt Text, and Asset Ownership

An editorial image is more than a URL. A public record may need a stable media ID, source dimensions, responsive variants, crop behavior, alternative text, decorative intent, caption, rights state, and publication status. The renderer must choose a variant that fits the layout without silently replacing the editor's meaningful crop. Text alternatives describe the image's function in context, not its file name. Private uploads must remain outside the public media path until publication grants access. A CMS attachment can be referenced by multiple articles, so deleting one post must not blindly delete the underlying bytes. Conversely, replacing an image should not leave unbounded orphaned variants or stale cached assets without a retention rule.

Working case

Article 447 uses a 2600-pixel inspection diagram and a 640-pixel crop for a card. The card crop hides a numbered annotation that the full page relies on, so the same alternative text cannot serve both contexts. A second article references the same full image. An editor replaces the source, but the frontend keeps the old CDN URL and mixes the new caption with old pixels. A draft upload is accidentally exposed through a predictable public attachment URL. The corrected model records asset ID and version, intended usage, dimensions and variant URLs, context-specific text alternatives, and publication scope. The card either receives an approved crop with its own description or uses the full image. Old assets retire only after reference and cache windows are understood.

Implementation boundary

function publicAsset(media, placement) {
  if (!media.published || !media.variants[placement]) return null;
  const variant = media.variants[placement];
  return {
    assetId: media.id,
    version: media.version,
    width: variant.width,
    height: variant.height,
    alt: variant.decorative ? "" : variant.alt
  };
}

const inspectionDiagram = {
  id: 83, version: 4, published: true,
  variants: { card: { width: 640, height: 400,
    decorative: false, alt: "Two marked inspection zones" } }
};
console.log(publicAsset(inspectionDiagram, "card"));

Store media references in the article revision rather than embedding arbitrary raw upload URLs throughout HTML. Validate MIME type, dimensions, byte size, and actual decoded format before accepting a variant. Give a public asset an immutable versioned URL or a content digest so a new image cannot be confused with old cached bytes. Generate width descriptors from real output dimensions; do not label a 640-pixel file as 1280 pixels. Reserve width and height or an aspect ratio in the page so image loading does not shift content. Ask for alt text at the placement level when the meaning differs by use, while allowing a decorative image to use an empty alternative. Track whether a draft asset is publicly reachable by its storage policy, not merely whether a CMS post is draft.

Cost and boundaries

Generating V variants for N source images costs work proportional to decoded pixels and encoded output sizes; a naive build can multiply storage by N times V. Serving an appropriately sized variant reduces transfer bytes and decode work on narrow screens, but too many widths fragment caches. A reference index from media ID to published article revisions takes additional storage and update work, yet makes safe retirement decisions possible. Immutable asset URLs simplify cache correctness because a published revision names exact bytes. Long retention increases storage cost; early deletion can break cached pages and backlinks. Measure variant bytes, largest image render timing, 404s for media, and orphaned asset age. Avoid claiming one image format is always best without target-browser and quality tests.

Failure trace

Upload a file whose extension says one format but whose decoded bytes say another, and reject it before publication. Ask for a card crop with a missing annotation, then verify its alternative text and caption still convey the necessary information. Render a 640-pixel variant in a high-density 1280-pixel slot and inspect whether the chosen variant is large enough without sending the 2600-pixel original to every device. Replace the image while a CDN cache holds the old URL; the new article revision must point to a new versioned asset. Delete one of two referencing articles and verify the shared asset remains. Unpublish the final reference, wait through the stated retention period, and only then retire the bytes and variants.

Verification

Every width descriptor matches the actual variant bytes.
Published revisions reference exact media versions.
Shared assets survive removal of only one referencing article.

Practice drill

Model two articles sharing media ID 83 and one unpublished upload 91. Build a reference list for published revisions, then calculate which assets may be served publicly and which are candidates for retirement. Provide two variants with true intrinsic dimensions and a distinct card crop. Render a card and article using their own text alternatives. Update the source and create a new asset version; keep the old version available while published revision 8 still references it. Add a validation failure for an empty alternative on an informative image, a false width descriptor, and a draft object with a public storage URL.

Decision note

A media reference binds content, meaning, and exact bytes; lifecycle decisions follow published references, not upload filenames.

Common Mistakes

Using the filename as alt text.
Serving draft uploads from public object storage by predictable URL.
Deleting shared media when one article is unpublished.

Apply and check

Build Project: CMS Publication Reconciliation and review Web Development: CMS publication contracts.