toolkit

Alt-text writer · Playbook

Image Alt-Text Standards

Summary. How to write the alt text sigilyph generates and publishes — what makes good alt, which images to skip, and the WordPress media process. Local fallback; point sigilyph at a live Outline wiki (OUTLINE + OUTLINE_API_URL, collection via SIGILYPH_WIKI_COLLECTION) for the team’s own version.

Surfaced by. sigilyph: content images with a missing or empty alt, and the descriptive alt it writes for each.

What good alt text is

  • Describe what’s meaningful in context, concisely (under ~125 characters). What would a sighted reader lose if the image didn’t load? Say that.
  • No “image of” / “picture of” / “photo of” — screen readers already announce it’s an image.
  • Include text that’s inside the image (a sign, a chart label) when it carries meaning.
  • Logos → the brand/logo wording (e.g. “Acme Roofing logo”), not a visual description.
  • Keywords are a bonus, not the goal. Natural description that happens to include a relevant term is fine; stuffing keywords into alt is a WCAG and quality problem.

Which images to skip

  • Decorative images — purely aesthetic backgrounds, spacers, dividers — take an empty alt="" so screen readers skip them. sigilyph auto-skips role="presentation"/aria-hidden/1×1 pixels; use --include-decorative only when a “decorative” image is actually informative.

Publishing (WordPress)

  1. sigilyph resolves each page image to its media-library item and updates the alt_text field there — so the fix applies everywhere the image is used, not just this page.
  2. Dry-run first — review the suggested alt per image, then --apply. Only images whose alt actually changes are written, and the prior value is kept.
  3. Alt text is an accessibility requirement (WCAG 1.1.1) first and an SEO signal second — write for the person using a screen reader.