image alt text best practices

In short. Alt text is what screen readers announce, search engines index, and browsers show when an image fails to load. The rule is simple: describe what the image CONVEYS, not what it SHOWS. Decorative images get an empty alt (alt=""), not the word "decorative." Functional images describe the action, not the visual. Keep it under ~125 characters. That's it — the rest of this page is worked examples, an audit checklist, and troubleshooting.

On this page: The rule, in detail · Length · Common mistakes · Examples · Audit steps · Alt text by page type

How to write image alt text in SGEN

Describe what the image CONVEYS, not what it SHOWS. Skip decorative images entirely. Keep under ~125 characters.

Alt text is the text that screen readers announce for blind or low-vision users, search engines use to understand image content, and browsers display when an image fails to load. Done well, it's invisible — readers get the same information regardless of whether they see the image. Done badly, it's noise, miscommunication, or accessibility failure.

Where to find it in SGEN:

• Per-image alt: the admin → Media Library → click image → Alt Text field
• Inline image alt: SG-Builder → click the image component → Alt Text field in right panel
• Bulk edit alt: the admin → Media → select multiple → Edit metadata → Alt text

The Media Library alt applies site-wide for that image; the inline alt (set in SG-Builder) applies to that specific placement and takes precedence when both are set.

The rule, in detail

Describe what the image CONVEYS

Bad: "A red sports car" Good: "The 2026 model, lower roofline + redesigned grille" (if the post is about the redesign)

The bad version describes pixels. The good version describes what the reader is meant to take away.

Skip decorative images

Bad: alt="decorative divider" Good: alt="" (empty)

Decorative images — patterns, dividers, background flourishes, illustrative graphics that don't add information — get an empty alt attribute. Screen readers skip them silently. Don't write "decorative" or "image" or "spacer" — those create noise.

Functional images describe the action

Bad: alt="magnifying glass icon" Good: alt="Search"

If clicking the image does something (open a search box, submit a form, navigate), describe what happens — not the visual.

Images of text quote the text

Bad: alt="screenshot of an error message" Good: alt="Error: Site backup failed — disk full. Retry or contact support."

If the image is a screenshot containing text, the alt text quotes that text. Otherwise, blind users can't read what the image says.

Complex visuals get short alt + long description

For charts, diagrams, infographics:

`` alt="Sales by quarter — see description below for data table" ``

Then put a data table or paragraph below the image with the full breakdown. Alt text alone can't carry a complex visual.

Length

Aim for ~125 characters. Some screen readers cut off at that point.

If the image NEEDS more, structure it as:

• Brief alt (≤125 chars) that captures the essence
• Long description nearby (caption, paragraph below, or aria-describedby linking to a hidden full description)

SEO vs accessibility — why they aren't in conflict

Good alt text is good SEO. Search engines reward image relevance and accessibility. The same description that helps a screen-reader user also helps Google understand what the image depicts.

The conflict only emerges when authors write KEYWORD-STUFFED alt text for SEO ("best CRM software CRM tools sales platform CRM SaaS"). Screen reader users hear noise; SEO is no better than concise relevant text would be. Lose-lose.

The right alt text is the one a human editor would write to describe the image honestly in context. That text also happens to be the SEO-optimal text.

Common mistakes

Examples

These examples use a typical SGEN customer running an e-commerce and editorial blog.

Blog post hero image — office interior

Context: post about a studio's redesign.

❌ alt="Modern office with natural light and open workspace" ✅ alt="The new flagship — wood floors and pendant lighting replaced last year's industrial concrete look"

Product feature screenshot — SGEN Builder UI

❌ alt="Screenshot of SGEN Builder" ✅ alt="SGEN Builder editor showing the responsive breakpoint switcher above the canvas"

Customer logo wall — decorative grid

❌ alt="Company logo" (repeated 30 times in a grid) ✅ Mark as decorative with alt="" for each logo. Add a heading above: "Trusted by 30+ teams including Studio A, Studio B, Studio C..."

Author headshot in author bio

❌ alt="Photo of Jane Doe" ✅ alt="Jane Doe" (or alt="" if the name is already in the caption)

Infographic with multiple data points

❌ alt="Quarterly revenue chart" ✅ alt="Q1-Q4 2025 revenue grew from $1.2M to $4.8M — see data table below" + actual data table beneath the image

Product image — Canvas Tote Bag

Context: e-commerce product page.

❌ alt="Tote bag" ✅ alt="Canvas Tote Bag — natural undyed cotton, rolled handles, interior zip pocket" (describes the product detail customers would want to know)

Promotional banner — sale event

Context: homepage hero image for a product sale.

❌ alt="Banner image" ✅ alt="" (the banner's message — "Sticker Pack, now $3.99" — is in overlaid text that screen readers will read; the image itself is decorative)

This is the most nuanced case: if the image contains text that your page also has as HTML text, the image is decorative and gets empty alt. If the text only exists in the image (not as HTML), quote it verbatim.

Steps to audit your site's alt text

Steps

1. Inventory

Open the admin → Media Library. Sort by "missing alt." Count how many images have no alt text set.

2. Categorize each image

For each image, decide: content / decorative / functional / image-of-text. This drives which alt pattern to use.

3. Write alt text by type

• Content images: describe meaning, ≤125 chars. Focus on what the reader should take away.
• Decorative images: set alt to empty string (alt=""). Never write "decorative" or "spacer."
• Functional images: describe the action ("Search", "Add to cart", "Open menu").
• Images of text: quote the text verbatim.
• Complex visuals: brief alt (≤125 chars) + long description in a caption or paragraph below.

4. Set the alt text

For each image in the audit, open the image in the Media Library and set the Alt Text field. For inline image placements with different context, also update the inline alt via SG-Builder → image component → Alt Text field.

5. Test with a screen reader

Visit 3-4 representative pages with macOS VoiceOver (Cmd+F5) or Windows Narrator (Win+Ctrl+Enter). Listen for:

• Images being announced with no description (alt missing)
• Announcements of "decorative", "spacer", "image" (bad alt text)
• Alt text that doesn't match the image's purpose in context

6. Run an accessibility audit

Use the admin → Site Tools → Lighthouse or an external tool (axe, WAVE) to confirm zero alt-text failures after your changes.

Example audit result: 847 images in media library. 312 had missing alt. After audit: 280 content images got descriptive alt, 28 decorative images got empty alt, 4 functional (social icons) got action-based alt. Lighthouse accessibility score went from 74 to 96.

What success looks like

• No image in the media library has an empty Alt field UNLESS it's a decorative image (which intentionally uses empty alt).
• Audit tool (axe, WAVE, Lighthouse) reports zero alt-text failures.
• Screen-reader walk-through of representative pages reads naturally.
• New content contributors know the pattern: describe what it conveys, not what it shows.
• A style guide entry documents the team's alt text rules for future authors.

What to do if it does not work

"My screen reader announces 'image' but no description." Alt attribute is missing entirely (not even empty). Set it — either to a description or to empty for decorative.

"My screen reader reads 'decorative image' or 'spacer'." You wrote literal "decorative" in the alt field. For decorative images, alt should be empty string, not the word "decorative."

"My Lighthouse score on accessibility dropped." Recent images probably missing alt. Audit the last 20 images uploaded.

"My image SEO traffic is flat." Alt text alone won't drive image search. Also need: descriptive filenames (not IMG_4823.jpg), proper image dimensions, fast load times.

"Two alt texts for the same image — Media Library and inline — which wins?" The inline value (set in SG-Builder on the image component) takes precedence for that specific placement. The Media Library value is the fallback when no inline override is set.

Alt text patterns by content area

Different page types have distinct image patterns. Use these as quick references:

Writing quality checklist

Use this checklist before publishing any page with new images:

• [ ] Every content image has alt text describing what it conveys (not what it shows)
• [ ] Every decorative image has empty alt (alt="")
• [ ] Every functional image (linked, clickable) describes the action
• [ ] Every image of text quotes that text verbatim
• [ ] All alt text is ≤125 characters (or has a long description nearby)
• [ ] No alt text starts with "image of", "picture of", or "photo of"
• [ ] No alt text repeats the caption
• [ ] No alt text is keyword-stuffed

Length reference

For reference: "Canvas Tote Bag — natural undyed cotton, rolled handles, interior zip pocket" is 71 characters — well within target.

Priority order for audits

If you have a large media library and limited time, prioritize in this order:

1. Content pages with high traffic — home, about, product pages. Fixes here have the biggest SEO + accessibility impact.
2. Images that are also links or buttons — functional images with missing alt are WCAG failures, not merely best-practice gaps.
3. Images containing text — banners, screenshots, infographics. Blind users can't read image-text without alt.
4. Product images — each one needs accurate alt for e-commerce accessibility compliance.
5. Blog post heroes — high volume but lower urgency than the above.
6. Decorative images — need empty alt (not no alt), but screen impact is lower than content images.

AI captioner and file-naming workflow

SGEN's AI Media Captions feature generates an alt text suggestion for each image at upload time. On the default setup, the captioner reads the filename — not the image content — to produce its suggestion. A file named IMG_9843.jpg yields a useless suggestion. A file named yourstore-product-category-variant.jpg yields something workable.

Name the file before you upload. Follow this pattern: [brand]-[subject]-[angle-or-variant].[ext]

`` yourstore-classic-t-shirt-front-view.jpg ✓ yourstore-canvas-tote-bag-side-detail.jpg ✓ IMG_9843.jpg ✗ no context product photo.jpg ✗ spaces break URLs final_v3_USE_THIS.jpg ✗ junk words ``

After upload, the AI suggestion lands in the Alt Text field. Treat it as a first draft — improve with product detail, brand voice, and the 5-12 word target. If the suggestion is already accurate and on-brand, accept it as-is.

Review cadence. At upload: 30-second review per image. Weekly: filter Media Library to "Missing alt text" and resolve any that were missed. Before launch: confirm count is zero for all page-embedded images. After a photography batch: rename files before uploading, then bulk-review AI suggestions in one session.

The AI only runs once at upload time. After that, the Alt Text field stays exactly as you leave it — it does not overwrite edits.

Alt text writing standard (quick reference)

• Lead with the subject. Skip "image of" — screen readers already say "image" before reading alt text. Start with what the image shows.
• 5-12 words for most product images. Complex visuals (charts, diagrams) can go up to 25 words.
• Include brand, product, and material when visible. "your business Canvas Tote Bag, beige cotton, front view" beats "tote bag".
• Functional images describe the action, not the appearance. "Buy Canvas Tote Bag" on an image-link to cart — not "canvas bag photo".
• Empty alt for decorative images. Do not type "decorative" — leave the field blank. Screen readers skip alt="" silently.
• Test out loud. Read the alt text aloud before saving. If it sounds awkward, rewrite until it flows naturally.

Related reading

• SG-Modules → Page Builder — image component reference, including the Alt Text field in the right panel
• SG-Core → Media Library — where per-image and bulk alt-text editing lives
• Blog categories vs tags strategy — companion content best practice