Why alt text, image dimensions, loading, and failure states need to be designed together

A project image can have the right URL and still leave questions unanswered: what readers see if it does not appear, how much space the page should reserve before it loads, and what information the image actually contributes.

Images on this site have different jobs. Project cards have thumbnails, design work links to external albums, the about page has a portrait that can be enlarged, and an image beside each article’s author opens an introduction. They should not all share the same alt text and loading settings.

I start by identifying what an image does in its particular location, then consider its dimensions, loading, and failure states together. These choices all become part of the page readers receive.

Alt text should describe the purpose, not rephrase the filename

The alt text for project thumbnails comes from each project’s localized title; design images use descriptions from the project data. These identify the item on display, but that does not mean they describe every image in sufficient detail. A short label such as “EDM” still needs to be assessed against the actual content.

The control that opens the author introduction is different. In the Chinese version, it is labeled “認識林予晴” (“About Lin Yuqing”), and author text appears beside the image. The portrait uses alt="" and aria-hidden="true" to avoid repeating the same identifying information here.

W3C’s image tutorial says that decorative images, which add no information to the content, should have empty alt text rather than omit the alt attribute.[3] Whether an image is decorative depends on its context. Being small or sitting inside a button is not enough reason to empty its alt text.

If an image contains a process or numbers that readers need to understand, the project name alone is not sufficient. Assessing that is part of content review; adding an HTML attribute does not do it automatically.

Dimensions reserve space before an image appears

MDN explains that width and height can provide an image’s intrinsic dimensions so the browser can allocate space before it loads. This is one way to reduce layout shifts.[2]

Project thumbnails on this site combine dimension attributes, a fixed-aspect-ratio container, and object-cover. The about-page portrait uses dimensions from the imported image, while its container and CSS determine the visible crop. Dimension attributes and the final display size are not the same thing.

Images in the design gallery have width="300" and height="200", with h-auto w-full for their display styling. Those are implementation settings. They do not establish that every external original has a true aspect ratio of 3:2, or that the entire gallery has no layout shifts. The external images’ actual dimensions and the card heights after loading still need to be checked separately.

My review focuses on whether the reserved aspect ratio suits the way the image is presented. Cropped images need a check for important content being cut off. A tall image intended to appear in full should not inherit another thumbnail’s aspect ratio just to make the layout look tidy.

Loading hints depend on where the image appears

The project list and design gallery use loading="lazy". The main portrait on the about page uses loading="eager" and fetchpriority="high"; the portrait beside the author introduction also uses eager. These are the settings at those particular locations, not rules that every image should copy.

loading="lazy" lets the browser defer loading based on conditions such as distance from the viewport. decoding="async" is a hint about when decoding and rendering should happen. The attributes address different concerns.[2]

I therefore do not treat async as a substitute for lazy or give every image high priority. Deciding whether readers need an image immediately on arrival provides a better basis for loading hints than copying the same attributes across the site.

There are no before-and-after performance measurements here. The choice of attributes alone cannot tell us how much faster anything became.

Failure feedback should preserve the image’s purpose

The site’s external design images have dedicated error markers. A shared browser script listens for error, hides the failed image, and displays a loading-failure message that includes the project description. During initialization, it also checks images that have finished loading but have no usable width.

The gallery script separately removes the card’s loading state after load or error and schedules a layout recalculation. These are two responsibilities: explaining that an image is unavailable, and handling the card’s state and layout.

The external link wrapping the image remains, so the HTML still contains an entry point to the project album after the image fails. Whether the album link itself works is a separate question. Image error handling cannot guarantee that destination is available.

This custom failure feedback applies only to images with the corresponding markers. Ordinary project thumbnails and all portraits do not automatically receive the same feedback, and there is no automatic retry. An article should not describe handling for one gallery as coverage for every image on the site.

Be clear about what remains without JavaScript

Alt text, dimensions, and native links remain in the HTML. JavaScript handles the custom error text and the gallery’s dynamic states. If the script cannot run, the custom failure message does not become visible simply because it exists in the template; it stays hidden.

The external links for design work also have readable names, but that does not replace checking each image’s presentation without scripts. Native HTML provides a foundation, not a guarantee that every loading state has an equivalent fallback.

This separation helps me decide what to test: first the content the page receives, then the behavior added by scripts. Checking the page only with a working connection and every image loaded is not enough.

Start image review with concrete questions

The following are suggested checks, not a list of tests all performed in this round:

• If the image does not appear, can readers still identify the item, and does the control still have a name?
• Do the dimensions and CSS aspect ratio fit the actual image, and does cropping remove important content?
• Is an image needed on arrival being deferred until an unsuitable moment?
• If an image request is deliberately made to fail, does the loading state end, and do the feedback and destination still serve their purpose?
• With JavaScript disabled, are the main content, alternative text, and native links still understandable?

If the only answer is “the image appears,” the review has not yet addressed failure or alternative content.

Scope of this account

This article draws on the site’s current project pages, design-image data, about page, article-author component, and shared and gallery scripts. This round did not individually test external image ratios, screen-reader behavior, disconnected-network scenarios, or every image failure path. It also includes no new measurements of loading speed or layout shift.

What the source establishes is how the code divides these responsibilities and which images use which settings. Assessing whether the presentation is appropriate still requires looking at the image content and actual use context.

Sources

[2] https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img [3] https://www.w3.org/WAI/tutorials/images/decorative