Skip to content

fix(gallery): describe each still in its alt text instead of the API it teaches - #221

Merged
TMHSDigital merged 2 commits into
mainfrom
fix/213-alt-text
Sep 23, 2026
Merged

TMHSDigital merged 2 commits into
mainfrom
fix/213-alt-text

Conversation

@TMHSDigital

Copy link
Copy Markdown
Owner

Summary

Closes #213. Every gallery image's alt described the API an entry teaches, not the picture: "{name} — {first sentence of teaches}", with 29 of 79 cut at 160 characters. Detail-page, zoom and landing images said only "{name} render".

Type

  • feat
  • fix — accessibility and content
  • docs / chore / ci / refactor

Changes

  • alt on all 79 entries in examples/gallery.json and showcase/gallery.json. Each is one sentence, written by looking at the committed hero; the longest is 135 characters. Examples:
    • light-link-studio: "Two spheres on pedestals: a brightly lit orange sphere labelled LINKED and a dark grey sphere labelled UNLINKED."
    • lod-decimate-chain: "Three red and white rockets labelled LOD0, LOD1 and LOD2, each more coarsely faceted than the last."
    • text-version-stamp stays version-neutral: "…the Blender version number in large gold 3D characters."
  • build_gallery.py uses it for the card image, detail hero, zoom image and zoom button (aria-label="View full size: …"). New check_alts() fails the build on a missing alt or one over 200 characters. The card_alt / first_sentence / assert_alts_survive_dotted_paths helpers are removed; their only job was deriving the old alt.
  • Landing page (template.html.j2): both card grids use ex.alt, falling back to the old text.
  • Docs: CLAUDE.md (the one example-wiring sentence), CONTRIBUTING.md step 3 and docs/new-example-prompt.md say new entries need an alt.

Evidence

  • live-run-proven (local, no Blender):
    • Regenerated gallery: 79 card alts, 0 ending in "…". stone-well detail hero and zoom both read "A round stone well of grey blocks under a four-post wooden roof, with a bucket hanging inside."
    • Landing page: all 14 card alts use alt; none end in " render".
    • Falsified: deleting campfire's alt makes build_gallery.py exit 1 with gallery entry 'campfire' has no 'alt': add one sentence describing what its still shows. Restored.
    • JSON diff: pure insertions (79 lines); both files round-trip byte-identically through json.
  • inspection-only: alts describe the committed stills. For the 25 heroes Committed hero stills do not match what the scripts render #200 found drifted, I kept the wording general enough to hold after a re-render (e.g. treasure-chest "An open wooden treasure chest with a vaulted lid and dark iron bands").

Merge note

This touches build_gallery.py and template.html.j2, as does #220 (fonts and og card), but in different hunks. Whichever merges second gets main merged in and the gallery regenerated, which the new Validate drift check enforces.

Checklist

  • Explicit paths only. The CLAUDE.md edit is deliberate and one line.
  • Counts and manifest unchanged.
  • The new check was falsified once (above).
  • DCO Signed-off-by: present.
  • No credentials, emails, or local paths.

🤖 Generated with Claude Code

…it teaches

Every gallery image's alt was derived from `teaches`, which says what the
code proves, not what the picture shows, and 29 of 79 card alts were cut at
160 characters. Detail-page, zoom and landing images said only
"<name> render".

- Each examples/ and showcase/ gallery.json entry gains an `alt`: one
  sentence written from the committed still (all 79, longest 135 chars).
- build_gallery.py uses it for the card, the detail hero, the zoom image
  and the zoom button label, and fails the build on a missing or overlong
  alt. The teaches-derived card_alt/first_sentence helpers go.
- The landing template uses it for both card grids.
- CLAUDE.md, CONTRIBUTING.md and docs/new-example-prompt.md say new entries
  need one.

Closes #213

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
@github-actions github-actions Bot added examples Runnable smoke-gated examples under examples/ showcase Budget-conformance props under showcase/ documentation Improvements or additions to documentation labels Sep 23, 2026
Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>

# Conflicts:
#	scripts/build_gallery.py
@TMHSDigital

Copy link
Copy Markdown
Owner Author

Merged main (with #219 and #220) into this branch. The one conflict was in scripts/build_gallery.py constants: kept #220's OG_CARD_* and this PR's ALT_MAX, and dropped the retired _ALT_CAP. With real alts available, detail pages' og:image:alt / twitter:image:alt now use the entry's alt instead of ": the example's own headless render". Gallery regenerated in the merge commit.

@TMHSDigital
TMHSDigital merged commit 8b3ed95 into main Sep 23, 2026
11 checks passed
@TMHSDigital
TMHSDigital deleted the fix/213-alt-text branch September 23, 2026 09:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation examples Runnable smoke-gated examples under examples/ showcase Budget-conformance props under showcase/

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Gallery alt text describes the API, not the picture

1 participant