Alt Text Assistant

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/alt-text-assistant/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core-free helper that suggests alt text for product images and post images as the merchant uploads them. Uses image filename, filename context, and a simple heuristic to offer a draft; merchant edits or accepts it. No forced alt text — the merchant can leave images untagged if they choose, but every upload gets a suggestion.

The problem

Merchants leave product images without alt text. Screen-reader users cannot see products and leave the site. SEO suffers because search engines cannot index image content. Every image is an accessibility failure and a missed opportunity.

What it does

• On image upload (media library or post editor), generate a draft alt-text suggestion from filename and image metadata (if EXIF contains description)
• Present suggestion to merchant with ‘Accept’, ‘Edit’, or ‘Skip’ options; editing flows to a text field
• Product media: pre-fill with ‘{Brand} {Product Name} {ColorSize}’ if available; merchant edits to something more descriptive
• Post media: suggest ‘Screenshot of [heading text from page]’ or ‘[object in image description]’ based on filename
• AI-powered suggestions optional (paid add-on, out of scope for core): image recognition to identify what’s in the photo
• Accessibility hints sidebar: ‘Good alt text is 100–150 characters and describes the image, not the file’ (educational, not enforced)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• No forced alt text — if a merchant skips the suggestion, the image uploads with empty alt and no enforcement (reason: some decorative images should be alt=”, and forcing alt breaks that)
• No image recognition — core uses heuristics only (reason: image recognition is a paid feature in the next tier, not core)
• No alt-text audit of existing images — this is a prospective tool for new uploads (reason: retroactive alt-text generation would need to label thousands of existing images; that is a one-time data migration task)

Data model

Media entity gains alt_suggested (text, nullable) field to store the suggestion that was offered to the merchant. No schema change required if nullable field.

API

• POST /api/media/upload-with-suggestion { file } → { url, alt_suggested }

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Media upload dialog shows filename-based alt-text draft in a text field: ‘Good alt text describes what’s in the image’. Merchant can type over it, clear it, or accept as-is. Product editor shows ‘Alt text’ field with suggestion pre-filled. Post editor shows alt field next to image preview with suggestion.

The seam — why this is core

Core owns the suggestion algorithm and the optional AI tier (if added later). Merchant owns the final alt text on save.

Core owns the interface + honest alt-text suggester; accessibility is infrastructure, not a per-country obligation or credential.

Dependencies

• Media upload endpoint (core)
• Post editor (core)
• Product editor (core)
• Filename parsing / metadata extraction (core)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Uploading a file named ‘blue-tshirt-xl.jpg’ suggests ‘Blue T-shirt, extra large’ in the alt field
• Uploading a file named ‘screenshot-dashboard.png’ suggests ‘Screenshot of dashboard’
• Product media upload suggests ‘[Brand] [Product Name] [Size/Color]’ if brand and product data are available
• Merchant can edit the suggestion inline and save the media with custom alt text
• Merchant can skip the suggestion by not filling the alt field and uploading the image with alt=” (empty)
• An image with alt=” (explicitly empty, set by merchant) renders with role=‘presentation’ (correctly marked as decorative)

Risks

Heuristics fail on ambiguous filenames (e.g., ‘IMG_1234.jpg’ → ‘Image 1234’, not useful). Merchant accepts poor suggestions and never fixes them. Suggestion field is not mandatory; if a merchant always skips it, the tool has no effect. Need to measure adoption (how often suggestions are accepted vs. skipped).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.