Image Alt Text Best Practices
How to write effective image alt text in SGEN
Alt text is the short description attached to every image on your site. Screen readers announce it to visitors who cannot see images. Search engines index it alongside the image. And on SGEN, it feeds into image schema, SEO signals, and the Media Library's coverage audit. This guide covers the full workflow: naming your files before upload, writing alt text that is clear and specific, deciding when to leave the field empty, and getting the most from SGEN's AI caption tool without letting it ship unreviewed copy.
What is this for?
This guide is for anyone who uploads images in SGEN and wants those images to be findable, accessible, and brand-correct.
The alt text you write here does three things at once:
- It is announced aloud by screen readers for visitors who rely on assistive technology.
- It is indexed by search engines as a signal about what the image shows — and by extension, what the page is about.
- It shows as fallback text in email clients, slow connections, and browser modes that suppress images.
None of those three jobs can be delegated fully to AI. SGEN's captioner gives you a draft. Your team turns the draft into something that is accurate, on-brand, and written for an actual human reader.
This guide also explains how file naming connects to caption quality. On SGEN's default setup, the AI captioner reads the filename — not the image itself — when generating its suggestion. A file named IMG_9843.jpg yields a useless suggestion. A file named acme-ethiopia-yirgacheffe-bag.jpg yields something workable. Getting into the habit of naming before you upload cuts the review time in half.
Good use cases
Use this guide when you are:
Example 1: Naming product images before upload at your business.
your business's marketing team photographs a new single-origin batch — your premium product, 12oz bags. The photographer delivers files named DSC_4421.jpg through DSC_4438.jpg. Before uploading, the team renames them:
When these upload with AI Media Captions enabled, the suggested alt text reads:
The suggestions are a foundation, not the final copy. The team rewrites to match brand voice:
The 5–12-word rule applies to most product images: enough to identify the subject, brand, and distinguishing detail. No more.
Example 2: Auditing alt-text coverage before the your detailed content piece launch.
Three days before launch, the team filters the Media Library to Images → Missing alt text. The count reads 18. They walk down the list, open each image's edit drawer, and either accept the AI suggestion (if it reads clearly) or rewrite it (if the suggestion is generic).
The target before launch: the Missing alt text count reaches zero on every image used on a live page. Images in the library that are not yet on any page can wait; images embedded on published pages cannot.
Example 3: Handling decorative images correctly.
Not every image carries meaning. A faint background texture, a horizontal rule graphic, a decorative divider between sections — these communicate nothing to a screen reader and should not be described.
For these images, set the alt text field to an empty string (leave it blank and save). Screen readers skip images with empty alt attributes. If the AI captioner has pre-populated a suggestion, clear it deliberately before saving.
The rule: if removing the image would not change the meaning of the page for a sighted visitor, it is decorative. Empty alt. If removing it would break the page — a product photo, a chart, a logo — it carries meaning and needs a description.
Uploading a new batch of product images and want to set them up correctly from the start — filename first, alt text second, AI suggestion as the starting point.
Working through a backlog of unlabeled images before a launch or an accessibility audit.
Training a team member on the alt-text standard for your site.
Deciding whether a particular image needs alt text at all (decorative images should have an empty alt attribute, not a description).
Checking that image SEO is wired up correctly — that the text you write here is reaching the public page's alt attribute and SGEN's SEO signals.
What NOT to use this for
Alt text is for assistive technology and search engines — it is not shown on the public page. If a chart or diagram needs a visible explanation for all visitors, add a text caption below the image in the page editor. The alt text describes what the image shows; the caption explains what it means.
How this connects to other features
The global toggle at Media Library → Settings → Enable AI Media Captions controls whether new uploads receive an auto-generated suggestion in the alt text field. This best-practices guide tells you what to do with those suggestions; the settings doc (media-library/04-ai-captions-and-settings) tells you how to turn the feature on or off and what it costs. Read that guide for the full setting and caveat list.
Before you start
- You are signed in to SGEN as an admin with access to the Media Library.
Where to go
To write or edit alt text for an existing image:
- Open the left navigation.
- Click Media Library.
- Find the image (use the search bar or the Missing alt text filter tab to prioritize).
- Click the image row to open its edit drawer.
- Edit the Alt text field directly.
- Click Save.
To write alt text at upload time:
- Click + Upload files in the Media Library.
- After the file uploads, the edit drawer opens (or the new row appears — click it).
- If AI Media Captions is on, the Alt text field is pre-populated. Review it. Edit or accept.
- Click Save.
To audit coverage:
- In the Media Library, select the Missing alt text filter tab.
- Walk the resulting list. Open each image, write or review alt text, save.
Steps
Open Finder or File Explorer. Rename the image before dragging it into the SGEN upload dialog.
Follow this pattern: [brand]-[subject]-[angle-or-variant].[ext]
Good filenames: acme-ethiopia-yirgacheffe-bag-front.jpg acme-canvas-tote-bag-side-detail.jpg acme-barista-tshirt-natural-cotton-model-front.jpg acme-brewing-guide-2026-cover.jpg acme-coffee-sticker-pack-spread.jpg
Avoid: IMG_9843.jpg ← no context, AI suggestion will be useless product photo.jpg ← spaces break URL handling final_v3_USE_THIS.jpg ← junk words, AI suggestion inherits them tote.jpg ← too short, loses brand and detailOn SGEN's default setup, the AI captioner reads only the filename — not the image itself. A descriptive filename is the single most impactful action you can take before upload. (Source: media-library/04-ai-captions-and-settings — "generates suggestions from the filename when no AI provider is configured.")
With AI Media Captions on (check at Media Library → Settings), upload the file. After the upload completes, click the new row to open the edit drawer.
Read the Alt text field. The AI suggestion will look something like:
Filename: acme-ethiopia-yirgacheffe-bag-front.jpg
Suggestion: "your business your premium product Bag Front"That is a passable first draft. Now improve it with three edits:
- Add the product detail that matters — weight, quantity, material, color, context.
- Rewrite in brand voice — not title-case words, but a proper phrase.
- Keep it between 5 and 20 words for a standard product image.
Before: "your business your premium product Bag Front"
After: "12oz bag of your business your premium product whole bean coffee, single origin, front view"If the suggestion is already accurate and on-brand, accept it as-is. Do not rewrite for the sake of it.
Most product and editorial images fit comfortably in 5 to 12 words. More than 20 words usually signals that the description belongs in a visible caption, not in the alt attribute.
| Image type | Target length | Example |
|---|---|---|
| Single product, front | 8–12 words | "12oz bag of your business your premium product whole bean coffee, front" |
| Product detail crop | 6–10 words | "your business Canvas Tote Bag handle stitching, close-up" |
| Model on product | 8–15 words | "your business Barista T-Shirt in natural cotton, front view, size M on model" |
| Decorative / texture | 0 words | alt="" — leave blank |
| Chart or diagram | Up to 25 words, or describe in body text | "Bar chart: Ethiopia blend sales up 34% in Q1 2026 vs. Q1 2025" |
| Logo | 3–5 words | "your business logo" |
If an image is purely decorative — a background texture, a divider line, a spacer shape — set the alt text to an empty string. Do this deliberately: if the AI captioner pre-populated a suggestion, clear it.
In the SGEN Media Library edit drawer, leave the Alt text field blank and click Save. SGEN renders this as alt="" on the public page, which tells screen readers to skip the image.
Do not type words like "decorative" or "spacer" into the field. An empty string is the correct value; anything else makes the screen reader announce something.
After saving, open the public page that uses this image in a private or incognito window. Right-click the image and choose Inspect. Look for the alt attribute on the <img> tag.
<!-- What you should see on the public page after saving alt text in the Media Library: -->
<img src="/media/acme-ethiopia-yirgacheffe-bag-front.jpg" alt="12oz bag of your business your premium product whole bean coffee, single origin, front view" width="800" height="800"
>The text in the alt attribute matches what you saved. That text is what screen readers announce and what search engines index. (Source: seo/01-audit-seo-across-site — "Alt text from the Media Library appears in the rendered alt attribute on every public page.")
Before any page goes live, open Media Library → Missing alt text. Every image on that list that is embedded on a published page must be resolved before launch.
The practical workflow:
- Filter Media Library to Missing alt text.
- For each image in the list: check whether it is used on any published page.
- If yes: open the edit drawer, write alt text (or generate and review the AI suggestion), save.
- If no: add it to your backlog — not a launch blocker, but needs attention.
- Repeat until the Missing alt text count for page-embedded images is zero.
One-time launches are not enough. Every image added to the site needs a review pass. The most sustainable pattern:
- At upload: always review the AI suggestion before saving. Takes 30 seconds per image.
- Weekly: filter Media Library to Missing alt text and resolve any that were missed at upload.
- Before launch: filter to Missing alt text, confirm count is zero for all page-embedded images.
- After a photography batch: rename all files to match the naming convention before uploading, then bulk-review the AI suggestions in a single session.
This pattern prevents backlog accumulation. A site with 200 images and a weekly 20-minute review habit stays clean. A site with no habit builds a debt that takes days to resolve.
What success looks like
- Every content-bearing image in your Media Library has a non-empty alt text field that a human has read and approved.
- Every decorative image has an explicitly empty alt text (blank field, saved).
- The Missing alt text count in the Media Library is zero for images embedded on published pages.
- On the public page, right-clicking an image and choosing Inspect shows an
altattribute that matches what you saved in the Media Library. - The SEO Manager (at SEO → SEO Manager) shows no image-schema gaps on your product pages or blog posts with key images.
- A screen reader or accessibility checker run against your public site returns no "missing alt text" violations for content images.
- Your team follows the file-naming convention consistently enough that AI suggestions are useful starting points, not noise.
What to do if it does not work
The filename is too vague. On SGEN's default setup, the captioner reads only the filename — a file named IMG_9843.jpg yields nothing useful. Rename the file to a descriptive phrase before your next upload. For files already in the library with bad filenames, write the alt text manually in the edit drawer.
Reference: the alt text writing standard
A quick reference for team members writing or reviewing alt text. These are accessibility and SEO conventions — not SGEN-specific rules.
Lead with the subject. Do not start with "image of" or "photo of" — screen readers already announce "image" before reading the alt text. Start with what the image shows: "12oz bag of your business your premium product.." not "An image showing a 12oz bag..".
5–12 words for most product images. Long enough to identify the subject with key details; short enough to not interrupt the reading flow. Complex images (charts, diagrams, multi-subject group photos) can go up to 25 words.
Include brand, product, and material when they are visible. "your business Canvas Tote Bag, beige cotton with AC monogram, front view" beats "tote bag". The brand name adds search signal; the material and angle help a non-sighted visitor picture the product.
Include color and texture when they are content-bearing. For a coffee roaster, "espresso-brown kraft paper bag with hand-printed label" tells a story. "bag" does not.
Write for screen-reader listeners. Read your alt text aloud. Does it make sense in the flow of the surrounding page content? If the heading above says "your premium product," the alt text does not need to repeat the name — it can describe what the image adds: "front view, 12oz, resealable valve closure".
Functional images describe the action, not the appearance. If an image is a button or a link, write where it goes or what it does: "Buy Canvas Tote Bag" on an image-link to the cart — not "Canvas Tote Bag, front view, beige cotton".
Empty alt for decorative images, always. Do not type "decorative" or "spacer." Leave the field blank. SGEN renders alt="". Screen readers skip it.
Test out loud. Read the alt text aloud before saving. If it sounds awkward, rewrite until it flows. This takes thirty seconds per image and is the fastest way to catch descriptions that are technically accurate but sound wrong when announced by a screen reader.