RFC 97: Alt Text Capabilities #97
Conversation
text/097-alt-text-capabilities.md
Outdated
|
|
||
| Here are some of the things we will ideally not be doing: | ||
| 1. We will not be doing away with the title field for the AbstractImage model. This is because titles will still be used to identify specific images, especially among a list or point of reference. | ||
| 2. We will not fall back to the title in the absence of an alt text. This is because we want to enforce alternative text, and a fallback (to another fallback) would be counter-productive to this effort. |
There was a problem hiding this comment.
Question: Should we consider an opt-in to the legacy behaviour to not break existing Wagtail installations' behaviour? E.g. a Wagtail setting.
There was a problem hiding this comment.
Well, images that have already defaulted to their titles in the absence of an alt text ideally should not be affected. The change will affect images from after this new behaviour has been introduced.
@Stormheg What are your thoughts on this?
text/097-alt-text-capabilities.md
Outdated
|
|
||
| ### 2. Adding `image_description` field to `AbstractImage` | ||
|
|
||
| The next major action is to add an `image_description` field to the AbstractImage class for a high-level overview of the image. It will be used as the alt text inside the image listing view and inside image picker dialogs. With this in place, the behaviour of the gallery in the admin interface would be such that stored images are described. This would be important to screen-reader users using the Wagtail admin, and it would be a small step in mentally preparing editors to be thorough at the point of image usage. However, with backward compatibility in mind, this new field will default to a blank string for existing images. |
There was a problem hiding this comment.
Suggestion (readibility): I think it might it make read better to call out the specific goal of this change explicitly in this RFC, e.g. improving accessibility of the Wagtail admin interface for the administrative users.
There was a problem hiding this comment.
Looking at it now, this does improve readability,
|
Thank you @Chiemezuo - I had a read and cannot see anything I would like to add. Thank you so much for putting this together. It may be good to work through whether this RFC replaces the other similar RFC #51 |
|
Thanks @Chiemezuo I think that makes sense, can you please update the RFC with a link to the other one and a note about this one superseding that one. Additionally, a comment on the other RFC. Amazing work here, excited to see this be outworked. |
|
Thank you @lb- |
thibaudcolas
changed the title
thibaudcolas
changed the title
|
One nice-to-have feature that isn't mentioned here is the ability to switch an existing |
|
Regarding fallback - I think a fallback is needed to support existing sites.
|
|
Hey @vsalvino, I think I can answer your above points. We're planning to write upgrade considerations explaining how existing sites can make use of the image_description field by doing a data migration from a custom alt text field (a common custom implementation we've seen) to the new image_description field. This data migration is something developers have to write and run themselves.
We explicitly don't want to fallback to the title as it is often a garbage filename and something we very much want to move away from as a default in Wagtail. Yes, this is breaking change, but one we believe needs to be made. If one does want to retain the implicit title-as-alt-text implementation as fallback, I would suggest overriding AbstractImage's
Yep! This is already on our radar as part of the implementation 👍 Do you feel this addresses your concerns? |
|
Thanks, definitely document My perspective - almost all sites are using the stock Image model. And most sites have thousands or tens of thousands of images. |
|
Thanks for the reply @vsalvino. Discussion about this is good, though I'm not sure I fully understand your perspective and concern. The data migration I mentioned (and that you appear to be perceiving as something that would impede upgrading?) would only be recommended (but not mandated) for sites using a custom image model with an alt text field. The intent of this recommendation being they can transfer any alt text they already have for existing images and adopt the new Wagtail defaults over their own custom implementation. Developers of a site using the stock image model ('sites that have no alt text') won't have to perform any upgrade steps at all. We're not requiring the image description for existing images be filled during the upgrade if that part is unclear. The resulting change in behavior will be that instead of images being rendered with a garbage filename alt attribute there won't be an alt attribute at all. If a visualization helps, this is what the HTML diff would look like. -<img source="DSC_01234.jpeg" alt="DSC_01234.jpeg">
+<img source="DSC_01234.jpeg">To reiterate the reason behind this (in different words): we consider no alt text to be equivalent to bad alt text. The difference being that missing alt text is easier for accessibility checker tools to flag. I don't feel this will be a behavioral change that non-accessibility focused developers would really care about. |
|
That sounds great - thanks for the detailed reply. |
There was a problem hiding this comment.
It seems to me like there is a large gap between what the RFC covers and what I see discussed in the comments to the RFC / what we’ve discussed in meetings. @Chiemezuo could you work to resolve that gap? For the RFC to be meaningfully approved, it needs to be a clear representation of our plans for implementation.
Here are particular aspects of the proposal that must be crystal-clear:
- How any proposed changes affect stock image rendering (
{% image my_img %}), in particular what is the proposed generation of thealtattribute on an image rendition. A diagram might help. - What specific breaking changes are foreseen, and how they will be mitigated.
And I would also like to see explicitly covered:
- Whether there are any foreseen changes to images added to content via rich text (where there are already contextual alt text fields)
- How the proposed changes would affect the "bulk upload" view, as we had discussed specific challenges there in recent meetings.
|
For anyone interested in this, we had internal discussions about the proposal and have devised changes to respond to my feedback. @Chiemezuo will update the RFC, I’d recommend holding off from further reviews in the meantime. |
There was a problem hiding this comment.
Minor point of formatting: I’d recommend breaking up your paragraphs into multiple lines (see for example Semantic Line Breaks). This will make it easier for reviewers to comment on a more specific point of your proposal.
|
Hi, for us it is very important that we can set an alt text per image in the imaging library. For example: "Voedselbosbouw team", "Voedselbosbouw logo", "portrait of Kaat", "people planting trees". And in Dutch as well, so this would probably need to be multi-lingual. We have no need of changing alt texts based on the page the image is shown, "people planting trees" would still be a good description for us. [updated comment for clarification] |
Hi @wimfeijen For example, say I have image "🖼️", and I have pages "1️⃣" and "2️⃣". At the point of uploading the image, the description will be set, and it will be fixed. |
| There will be a warning message that shows at the image upload/edit form that indicates that although the the field is optional, Wagtail recommends editors fill it. | ||
|
|
||
| ### 3. Documentation efforts | ||
| We will include a note in the upgrade considerations on how developers can migrate. In practice, some developers have added their own alt text field to their custom image model. These migration instructions will help this group of developers migrate from their own alt text field to the new image description field. |
There was a problem hiding this comment.
Wondering whether we should specify the changes we intend to make in more detail. ('how to migrate to ImageBlock'; 'how to switch from a custom alt text implementation to the new description field')
Now that we have decided to do fallback to the title and generally be more forgiving when it comes to upgrading, precisely documenting what the upgrade instructions will entail feels less important to me.
| flowchart LR | ||
| Start[🖼️ Image in the CMS] --> B{Vanilla image model\n alt text\n implementation?} | ||
| B -- Yes --> G | ||
| B -- No, custom alt text at model level --> C{Does the custom alt text use\n AbstractImage.default_alt_text\n or AbstractRendition.alt?} | ||
| C -- Yes --> D[Same as vanilla\n implementation, except\n bespoke alt text\n could be mandatory] | ||
| C -- No --> E([🟠 Uncharted territory,\n implementation-dependent]) | ||
| D --> G{How does the image render?} | ||
| G -- In the CMS --> Y(["🔵 alt='{title}'"]) | ||
| G -- "Direct image reference\n in template tag\n (ImageChooserBlock, foreign key)" --> YY(["🟠 alt='{title}'"]) | ||
| G -- Custom StreamField block --> K(["🔵 alt='{custom}'"]) | ||
| G -- In rich text --> R(["🟠 Contextual alt text\n field pre-filled with title\n (opt-out of reusing title)"]) | ||
| R --> S(["🟠 alt='{contextual}'\n or alt='{title}' or alt=''\n based on user decision"]) | ||
| ``` |
There was a problem hiding this comment.
Aside: I think diagraming with a markup language is pretty cool!
View the rendered RFC with graphs
In its current state, Wagtail’s alt text functionality presents a significant accessibility challenge. Its approach to alt text relies heavily on the implementation of developers who use Wagtail, with the only default mechanism being that when alt text is not provided, the title of the image is used as the alt text. The problem with this is that image titles are also defaulted to what the file is saved as, and site editors are not mandated to change the titles from this default. Research by Wagtail’s accessibility team has shown that many sites have not attempted to customize the alt text mechanism, instead, relying on the default to file names. Much too often, this leads to a very poor experience for screen-reader users.
Additionally, the developers who create their own ways of enforcing alt text do so in a way that does not allow alt text to be tailored to the context in which the image is used. This is likely due to a general lack of awareness of the value that contextual alt text provides to users. Therefore with images in Wagtail, we have a lot of sites not adhering to Web Accessibility Standards, despite the developers behind them thinking otherwise.
This RFC proposes a solution to improve the overall accessibility of Wagtail sites by expanding the alt text capabilities provided out of the box, thereby enforcing good practices. It approaches this by adding supported mechanisms for handling alt texts in their most common use-case scenarios; such as in StreamField Image blocks, StructBlocks, and by providing helpful image descriptions in the AbstractImage model.
Achieving these objectives, will by extension, provide a way for contextual alt text to be supported for images, especially when they appear in more than one place in a Wagtail website.