How to write image alt text in SGEN

The short answer

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

What is this for?

Alt text is the text that:

• Screen readers announce when a blind or low-vision user encounters an image
• Search engines use to understand image content (and rank you in image search)
• Browsers display when an image fails to load (slow connection, broken URL)

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.

This page is the rule.

Good use cases

• You're publishing your first blog post and don't know what to put in the alt field.
• You inherited a site with 500 images and want to audit + fix systematically.
• You're writing your team's content guidelines for new authors.
• Your accessibility audit flagged "low quality alt text" and you need a fix pattern.

What NOT to use this for

• Don't use alt text as a place to stuff keywords for SEO. Search engines see through it; it harms accessibility; modern SEO doesn't reward it.
• Don't write alt text that repeats the image caption. Screen readers will read both and confuse the listener.
• Don't write "image of [thing]" or "picture of [thing]" — screen readers already announce it as an image.

How this connects to other features

• SG-Modules → Page Builder — the image component where inline alt text is set in the right-side panel
• SG-Core → Media Library — the central alt text field that applies when the image is reused across pages
• Blog post editor — inline image alt set per-insert, separate from the Media Library entry
• Accessibility audits — the admin → Site Tools → Lighthouse (when available) surfaces alt text failures

Before you start

• Know the difference between your Media Library alt text (applies site-wide for that image) and the inline image alt text (applies for that specific placement). If both are set, the inline value takes precedence.
• Have a screen reader available for final testing: macOS VoiceOver (Cmd+F5) or Windows Narrator (Win+Ctrl+Enter).
• If auditing an existing site, start with the admin → Media Library sorted by "missing alt" to find the highest-priority fixes first.

Where to find it

• 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 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.

Where to find it

• 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 (per the bulk-alt-text-edit feature shipped May 2026)

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.

Related reading

• SG-Modules → Page Builder — image component reference
• SG-Core → Media Library — where bulk alt-text editing lives
• Blog categories vs tags strategy — companion content best practice