Skip to content

Link W3C Alt Decision Tree URL in alt-text system instruction#462

Closed
adamsilverstein wants to merge 1 commit intoWordPress:developfrom
adamsilverstein:improve-alt-text-generation
Closed

Link W3C Alt Decision Tree URL in alt-text system instruction#462
adamsilverstein wants to merge 1 commit intoWordPress:developfrom
adamsilverstein:improve-alt-text-generation

Conversation

@adamsilverstein
Copy link
Copy Markdown
Member

@adamsilverstein adamsilverstein commented Apr 22, 2026

Summary

  • Adds the canonical W3C "An alt Decision Tree" URL (https://www.w3.org/WAI/tutorials/images/decision-tree/) inline with the already-named reference in includes/Abilities/Image/alt-text-system-instruction.php.
  • Replaces the original parenthetical with an em-dash so we don't nest parentheses around the URL.
  • One-line change to the shared system instruction used by every alt-text surface (block editor, media library, bulk action, CLI), which all resolve to the ai/alt-text-generation ability.

Why

Models trained on web content often have strong priors anchored to well-known URLs. Linking the canonical guide gives the model a concrete reference point for the decision framework the instruction explicitly names (decorative / functional / informative / complex). It also documents the authoritative source for anyone reading the prompt later.

What's not in this PR

  • No changes to TS callers — they pass only params, not prompt text.
  • No changes to Alt_Text_Generation.php or the guidelines injection system — the URL belongs in the instruction itself, not a guideline CPT entry.
  • No translation wrapping — the heredoc is intentionally untranslated (system instruction for the model, not user-visible UI).

Closes #461

Test plan

  • php -l includes/Abilities/Image/alt-text-system-instruction.php passes
  • Trigger alt-text generation via block editor on a local WP install with an AI provider configured; output still sensible
  • Trigger alt-text generation via media library modal; output still sensible
  • E2E specs run clean:
    • tests/e2e/specs/experiments/alt-text-generation.spec.js
    • tests/e2e/specs/experiments/alt-text-generation-bulk.spec.js
Open WordPress Playground Preview

Add the canonical guide URL (https://www.w3.org/WAI/tutorials/images/decision-tree/)
inline with the named reference so the model has a concrete anchor for the
decision framework, and future readers can find the authoritative source.

Refs WordPress#461
@github-actions
Copy link
Copy Markdown

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

@codecov
Copy link
Copy Markdown

codecov Bot commented Apr 22, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.72%. Comparing base (4c9699f) to head (dbd92e4).

Additional details and impacted files
@@            Coverage Diff             @@
##             develop     #462   +/-   ##
==========================================
  Coverage      67.72%   67.72%           
  Complexity       959      959           
==========================================
  Files             60       60           
  Lines           4836     4836           
==========================================
  Hits            3275     3275           
  Misses          1561     1561           
Flag Coverage Δ
unit 67.72% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@adamsilverstein
Copy link
Copy Markdown
Member Author

Closing — the inline decision tree in the system instruction already specifies the decorative/functional/informative/complex rules explicitly, so adding the URL is unlikely to change model output. Not worth the churn for documentation-only value. Closing alongside #461.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Proposal: Link W3C Alt Decision Tree URL in alt-text system instruction

1 participant