[RFC] Add alt texts to images

_images/sources/README.md

@@ -39,7 +39,9 @@ Use the following snippet to embed the diagram in the docs:
 ```
 .. raw:: html
 
-    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"></object>
+    <object data="../_images/<folder-name>/<diagram-file-name>.svg" type="image/svg+xml"
+        alt="<alt description>"
+    ></object>
 ```
 
 ### Reasoning

components/console/helpers/cursor.rst

@@ -11,7 +11,7 @@ cursor position in a console command. This allows you to write on any position
 of the output:
 
 .. image:: /_images/components/console/cursor.gif
-   :align: center
+    :alt: A command outputs on various positions on the screen, eventually drawing the letters "SF".
 
 .. code-block:: php
 

components/console/helpers/debug_formatter.rst

@@ -8,7 +8,7 @@ the results of running ``figlet symfony``, it might output something like
 this:
 
 .. image:: /_images/components/console/debug_formatter.png
-   :align: center
+    :alt: Console output, with the first line showing "RUN Running figlet", followed by lines showing the output of the command prefixed with "OUT" and "RES Finished the command" as last line in the output.
 
 Using the debug_formatter
 -------------------------

components/console/helpers/processhelper.rst

@@ -19,14 +19,17 @@ a very verbose verbosity (e.g. ``-vv``)::
 will result in this output:
 
 .. image:: /_images/components/console/process-helper-verbose.png
+    :alt: Console output showing two lines: "RUN 'figlet' 'Symfony'" and "RES Command ran successfully".
 
 It will result in more detailed output with debug verbosity (e.g. ``-vvv``):
 
 .. image:: /_images/components/console/process-helper-debug.png
+    :alt: In between the command line and the result line, the command's output is now shown prefixed by "OUT".
 
 In case the process fails, debugging is easier:
 
 .. image:: /_images/components/console/process-helper-error-debug.png
+    :alt: The last line shows "RES 127 Command dit not run successfully", and the output lines show more the error information from the command.
 
 Arguments
 ---------

components/console/helpers/progressbar.rst

@@ -5,6 +5,7 @@ When executing longer-running commands, it may be helpful to show progress
 information, which updates as your command runs:
 
 .. image:: /_images/components/console/progressbar.gif
+    :alt: Console output showing a progress bar advance to 100%, with the esimated time left, the memory usage and a special message that changes when the bar closes completion.
 
 .. note::
 

components/form.rst

@@ -511,7 +511,7 @@ done by passing a special form "view" object to your template (notice the
     {{ form_end(form) }}
 
 .. image:: /_images/form/simple-form.png
-    :align: center
+    :alt: An HTML form showing a text box labelled "Task", three select boxes for a year, month and day labelled "Due date" and a button labelled "Create Task".
 
 That's it! By printing ``form_widget(form)``, each field in the form is
 rendered, along with a label and error message (if there is one). While this is

components/http_kernel.rst

@@ -72,7 +72,9 @@ and ends with a :class:`Symfony\\Component\\HttpFoundation\\Response`.
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing all HTTP Kernel events in the Request-Response lifecycle. Each event is numbered 1 to 8 and described in detail in the following subsections."
+    ></object>
 
 The exact details of this workflow are the key to understanding how the kernel
 (and the Symfony Framework or any other library that uses the kernel) works.
@@ -504,7 +506,9 @@ to the exception.
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow-exception.svg" type="image/svg+xml"
+        alt="The HTTP KErnel flow diagram showing how exceptions bypass all further steps and are directly transformed to responses."
+    ></object>
 
 Each listener to this event is passed a :class:`Symfony\\Component\\HttpKernel\\Event\\ExceptionEvent`
 object, which you can use to access the original exception via the
@@ -663,7 +667,9 @@ your controller).
 
 .. raw:: html
 
-    <object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/http_kernel/http-workflow-subrequest.svg" type="image/svg+xml"
+        alt="The HTTP Kernel flow diagram with a sub request from a controller starting the lifecycle at step 1 again and feeding the sub Response content back into the controller."
+    ></object>
 
 To execute a sub request, use ``HttpKernel::handle()``, but change the second
 argument as follows::

components/messenger.rst

@@ -27,7 +27,9 @@ Concepts
 
 .. raw:: html
 
-    <object data="../_images/components/messenger/overview.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/messenger/overview.svg" type="image/svg+xml"
+        alt="A flow diagram visualizing how each concept relates to eachother. Each concept is described in the subsequent text."
+    ></object>
 
 **Sender**:
    Responsible for serializing and sending messages to *something*. This

components/serializer.rst

@@ -8,15 +8,20 @@ In order to do so, the Serializer component follows the following schema.
 
 .. raw:: html
 
-    <object data="../_images/components/serializer/serializer_workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/components/serializer/serializer_workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing how objects are serialized/deserialized. This is described in the subsequent paragraph."
+    ></object>
 
-As you can see in the picture above, an array is used as an intermediary between
-objects and serialized contents. This way, encoders will only deal with turning
-specific **formats** into **arrays** and vice versa. The same way, Normalizers
-will deal with turning specific **objects** into **arrays** and vice versa.
+When (de)serializing objects, the Serializer uses an array as the intermediary
+between objects and serialized contents. Encoders will only deal with
+turning specific **formats** into **arrays** and vice versa. The same way,
+normalizers will deal with turning specific **objects** into **arrays** and
+vice versa. The Serializer deals with calling the normalizers and encoders
+when serializing objects or deserializing formats.
 
-Serialization is a complex topic. This component may not cover all your use cases out of the box,
-but it can be useful for developing tools to serialize and deserialize your objects.
+Serialization is a complex topic. This component may not cover all your use
+cases out of the box, but it can be useful for developing tools to
+serialize and deserialize your objects.
 
 Installation
 ------------

components/string.rst

@@ -48,7 +48,7 @@ The following image displays the bytes, code points and grapheme clusters for
 the same word written in English (``hello``) and Hindi (``नमस्ते``):
 
 .. image:: /_images/components/string/bytes-points-graphemes.png
-   :align: center
+    :alt: Each letter in "hello" is made up of one byte, one code point and one grapheme cluster. In the Hindi translation, the first two letters ("नम") take up three bytes, one code point and one grapheme cluster. The last letters ("स्ते") each take up six bytes, two code points and one grapheme cluster.
 
 Usage
 -----

components/var_dumper.rst

@@ -354,6 +354,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/01-simple.png
+    :alt: Dump output showing the array with length five and all keys and values.
 
 .. note::
 
@@ -371,6 +372,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/02-multi-line-str.png
+    :alt: Dump output showing the string on multiple lines in between three quotes.
 
 .. code-block:: php
 
@@ -385,6 +387,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/03-object.png
+    :alt: Dump output showing the PropertyExample object and all three properties with their values.
 
 .. note::
 
@@ -403,6 +406,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/04-dynamic-property.png
+    :alt: Dump output showing the DynamicPropertyExample object and both declared and undeclared properties with their values.
 
 .. code-block:: php
 
@@ -415,6 +419,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/05-soft-ref.png
+    :alt: Dump output showing the "aCircularReference" property value referencing the parent object, instead of showing all properties again.
 
 .. code-block:: php
 
@@ -428,6 +433,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/06-constants.png
+    :alt: Dump output with the "E_WARNING" constant shown as value of "severity".
 
 .. code-block:: php
 
@@ -441,6 +447,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/07-hard-ref.png
+    :alt: Dump output showing the referenced arrays.
 
 .. code-block:: php
 
@@ -451,6 +458,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/08-virtual-property.png
+    :alt: Dump output of the ArrayObject.
 
 .. code-block:: php
 
@@ -464,6 +472,7 @@ then its dump representation::
     dump($var);
 
 .. image:: /_images/components/var_dumper/09-cut.png
+    :alt: Dump output where the children of the Container object are hidden.
 
 .. _var-dumper-advanced:
 

components/workflow.rst

@@ -22,6 +22,7 @@ process is called a *place*. You do also define *transitions* that describe
 the action to get from one place to another.
 
 .. image:: /_images/components/workflow/states_transitions.png
+    :alt: An example state diagram for a workflow, showing transitions and places.
 
 A set of places and transitions creates a **definition**. A workflow needs
 a ``Definition`` and a way to write the states to the objects (i.e. an

console.rst

@@ -77,6 +77,7 @@ commands support name and option completion, and some can even complete
 values.
 
 .. image:: /_images/components/console/completion.gif
+    :alt: The terminal completes the command name "secrets:remove" and the argument "SOME_OTHER_SECRET".
 
 First, make sure you installed and setup the "bash completion" package for
 your OS (typically named ``bash-completion``). Then, install the Symfony

contributing/code/stack_trace.rst

@@ -91,8 +91,8 @@ Several things need to be paid attention to when picking a stack trace
 from your development environment through a web browser:
 
 1. Are there several exceptions? If yes, the most interesting one is
-   often exception 1/n which, is shown *last* in the example below (it
-   is the one marked as an exception [1/2]).
+   often exception 1/n which, is shown *last* in the default exception page
+   (it is the one marked as ``exception [1/2]`` in the below example).
 2. Under the "Stack Traces" tab, you will find exceptions in plain
    text, so that you can easily share them in e.g. bug reports. Make
    sure to **remove any sensitive information** before doing so.
@@ -102,8 +102,8 @@ from your development environment through a web browser:
    are getting, but are not what the term "stack trace" refers to.
 
 .. image:: /_images/contributing/code/stack-trace.gif
-   :align: center
-   :class: with-browser
+    :alt: The default Symfony exception page with the "Exceptions", "Logs" and "Stack Traces" tabs.
+    :class: with-browser
 
 Since stack traces may contain sensitive data, they should not be
 exposed in production. Getting a stack trace from your production

contributing/documentation/overview.rst

@@ -25,8 +25,8 @@ while you're reading the Symfony documentation.
 and you'll be redirected to GitHub:
 
 .. image:: /_images/contributing/docs-github-edit-page.png
-   :align: center
-   :class: with-browser
+    :alt: The "Edit this page" button is located directly below the first heading.
+    :class: with-browser
 
 **Step 2.** Edit the contents, describe your changes and click on the
 **Propose file change** button.
@@ -36,8 +36,8 @@ and you'll be redirected to GitHub:
 also display a preview of your changes:
 
 .. image:: /_images/contributing/docs-github-create-pr.png
-   :align: center
-   :class: with-browser
+    :alt: The "Comparing changes" page on GitHub.
+    :class: with-browser
 
 If everything is correct, click on the **Create pull request** button.
 
@@ -152,7 +152,7 @@ exact changes that you want to propose, select the appropriate branches where
 changes should be applied:
 
 .. image:: /_images/contributing/docs-pull-request-change-base.png
-   :align: center
+    :alt: The base branch select option on the GitHub page.
 
 In this example, the **base fork** should be ``symfony/symfony-docs`` and
 the **base** branch should be the ``5.4``, which is the branch that you selected

contributing/documentation/standards.rst

@@ -146,6 +146,36 @@ Files and Directories
       ├─ vendor/
       └─ ...
 
+Images and Diagrams
+-------------------
+
+* **Diagrams** must adhere to the Symfony docs style. These are created
+  using the Dia_ application, to make sure everyone can edit them. See the
+  `README on GitHub`_ for instructions on how to create them.
+* All images and diagrams must contain **alt descriptions**:
+
+  * Keep the descriptions concise, do not duplicate information surrounding
+    the figure;
+  * Describe complex diagrams in text surrounding the diagram instead of
+    the alt description. In these cases, alt descriptions must describe
+    where the longer description can be found (e.g. "These elements are
+    described further in the next sections");
+  * Start descriptions with a capital letter and end with a period;
+  * Do not start with "A screenshot of", "Diagram of", etc. except when
+    it's useful to know the exact type (e.g. a specific diagram type).
+
+.. code-block:: text
+
+    .. image:: _images/example-screenshot.png
+        :alt: Some concise description of the screenshot.
+
+    .. raw:: html
+
+        <object data="_images/example-diagram.svg" type="image/svg+xml"
+            alt="Some concise description."
+        ></object>
+
+
 English Language Standards
 --------------------------
 
@@ -201,4 +231,6 @@ In addition, documentation follows these rules:
 .. _`American English Oxford Dictionary`: https://www.lexico.com/definition/american_english
 .. _`headings and titles`: https://en.wikipedia.org/wiki/Letter_case#Headings_and_publication_titles
 .. _`Serial (Oxford) Commas`: https://en.wikipedia.org/wiki/Serial_comma
+.. _`Dia`: http://dia-installer.de/
+.. _`README on GitHub`: https://github.com/symfony/symfony-docs/blob/6.4/_images/sources/README.md
 .. _`nosism`: https://en.wikipedia.org/wiki/Nosism

controller/error_pages.rst

@@ -10,18 +10,16 @@ Symfony catches all the exceptions and displays a special **exception page**
 with lots of debug information to help you discover the root problem:
 
 .. image:: /_images/controller/error_pages/exceptions-in-dev-environment.png
-   :alt: A typical exception page in the development environment
-   :align: center
-   :class: with-browser
+    :alt: A typical exception page in the development environment with the full stacktrace and log information.
+    :class: with-browser
 
 Since these pages contain a lot of sensitive internal information, Symfony won't
 display them in the production environment. Instead, it'll show a minimal and
 generic **error page**:
 
 .. image:: /_images/controller/error_pages/errors-in-prod-environment.png
-   :alt: A typical error page in the production environment
-   :align: center
-   :class: with-browser
+    :alt: A typical error page in the production environment.
+    :class: with-browser
 
 Error pages for the production environment can be customized in different ways
 depending on your needs:

doctrine.rst

@@ -185,8 +185,11 @@ objects to a ``product`` table in your database. Each property in the ``Product`
 entity can be mapped to a column in that table. This is usually done with attributes:
 the ``#[ORM\Column(...)]`` comments that you see above each property:
 
-.. image:: /_images/doctrine/mapping_single_entity.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/doctrine/mapping_single_entity.svg" type="image/svg+xml"
+        alt="Doctrine mapping between properties of a Product PHP object and the data in the product database table"
+    ></object>
 
 The ``make:entity`` command is a tool to make life easier. But this is *your* code:
 add/remove fields, add/remove methods or update configuration.
@@ -586,8 +589,8 @@ the :ref:`doctrine-queries` section.
     will display the number of queries and the time it took to execute them:
 
     .. image:: /_images/doctrine/doctrine_web_debug_toolbar.png
-       :align: center
-       :class: with-browser
+        :alt: The web dev toolbar showing the Doctrine item.
+        :class: with-browser
 
     If the number of database queries is too high, the icon will turn yellow to
     indicate that something may not be correct. Click on the icon to open the

doctrine/associations.rst

@@ -409,8 +409,11 @@ When you go to ``/product``, a single row is added to both the ``category`` and
 to whatever the ``id`` is of the new category. Doctrine manages the persistence of this
 relationship for you:
 
-.. image:: /_images/doctrine/mapping_relations.png
-    :align: center
+.. raw:: html
+
+    <object data="../_images/doctrine/mapping_relations.svg" type="image/svg+xml"
+        alt="Doctrine mapping associated Product and Category entities to a product and category database table"
+    ></object>
 
 If you're new to an ORM, this is the *hardest* concept: you need to stop thinking
 about your database, and instead *only* think about your objects. Instead of setting
@@ -456,8 +459,11 @@ Doctrine silently makes a second query to find the ``Category`` that's related
 to this ``Product``. It prepares the ``$category`` object and returns it to
 you.
 
-.. image:: /_images/doctrine/mapping_relations_proxy.png
-    :align: center
+.. raw:: html
+
+    <object data="../_images/doctrine/mapping_relations_proxy.svg" type="image/svg+xml"
+        alt="Doctrine only querying Category data when needed"
+    ></object>
 
 What's important is the fact that you have access to the product's related
 category, but the category data isn't actually retrieved until you ask for

form/create_custom_field_type.rst

@@ -94,7 +94,9 @@ following set of fields as the "postal address":
 
 .. raw:: html
 
-    <object data="../_images/form/form-custom-type-postal-address.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form-custom-type-postal-address.svg" type="image/svg+xml"
+        alt="A wireframe of the custom field type, showing five text inputs: two address lines, the City, the State and the ZIP code."
+    ></object>
 
 As explained above, form types are PHP classes that implement
 :class:`Symfony\\Component\\Form\\FormTypeInterface`, although it's more
@@ -429,12 +431,23 @@ second part of the Twig block name (e.g. ``_row``) defines which form type part
 is being rendered (row, widget, help, errors, etc.)
 
 The article about form themes explains the
-:ref:`form fragment naming rules <form-fragment-naming>` in detail. The
-following diagram shows some of the Twig block names defined in this example:
+:ref:`form fragment naming rules <form-fragment-naming>` in detail. These
+are some examples of Twig block names for the postal address type:
 
 .. raw:: html
 
-    <object data="../_images/form/form-custom-type-postal-address-fragment-names.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form-custom-type-postal-address-fragment-names.svg" type="image/svg+xml"
+        alt="The wireframe with some block names highlighted, these are also listed below the image."
+    ></object>
+
+``postal_address_row``
+    The full form type block.
+``postal_address_addressLine1_help``
+    The help message block below the first address line.
+``postal_address_state_widget``
+    The text input widget for the State field.
+``postal_address_zipCode_label``
+    The label block of the ZIP Code field.
 
 .. caution::
 

form/data_transformers.rst

@@ -440,8 +440,11 @@ In the above example, the transformer was used as a "model" transformer.
 In fact, there are two different types of transformers and three different
 types of underlying data.
 
-.. image:: /_images/form/data-transformer-types.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/form/data-transformer-types.svg" type="image/svg+xml"
+        alt="Flow diagram with the Model transformer between Model and Norm data, and the View transformer between Norm and View data. This is described in detail below the diagram."
+    ></object>
 
 In any form, the three different types of data are:
 
@@ -481,7 +484,7 @@ To use the view transformer, call ``addViewTransformer()``.
     data. So your model transformer cannot reduce the number of items within the
     Collection (i.e. filtering out some items), as in that case the collection
     ends up with some empty children.
-    
+
     A possible workaround for that limitation could be not using the underlying
     object directly, but a DTO (Data Transfer Object) instead, that implements
     the transformation of such incompatible data structures.

form/events.rst

@@ -29,16 +29,28 @@ register an event listener to the ``FormEvents::PRE_SUBMIT`` event as follows::
 The Form Workflow
 -----------------
 
+In the lifecycle of a form, there are two moments where the form data can
+be updated:
+
+1. During **pre-population** (``setData()``) when building the form;
+2. When handling **form submission** (``handleRequest()``) to update the
+   form data based on the values the user entered.
+
 .. raw:: html
 
-    <object data="../_images/form/form_workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form_workflow.svg" type="image/svg+xml"
+        alt="A generic flow diagram showing the two phases. These are
+        described in the next subsections."
+    ></object>
 
 1) Pre-populating the Form (``FormEvents::PRE_SET_DATA`` and ``FormEvents::POST_SET_DATA``)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. raw:: html
 
-    <object data="../_images/form/form_prepopulation_workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form_prepopulation_workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing the two events that are dispatched during pre-population."
+    ></object>
 
 Two events are dispatched during pre-population of a form, when
 :method:`Form::setData() <Symfony\\Component\\Form\\Form::setData>`
@@ -111,7 +123,9 @@ View data        Normalized data transformed using a view transformer
 
 .. raw:: html
 
-    <object data="../_images/form/form_submission_workflow.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form_submission_workflow.svg" type="image/svg+xml"
+        alt="A flow diagram showing the three events that are dispatched when handling form submissions."
+    ></object>
 
 Three events are dispatched when
 :method:`Form::handleRequest() <Symfony\\Component\\Form\\Form::handleRequest>`

form/form_customization.rst

@@ -51,10 +51,12 @@ customized using other Twig functions, as illustrated in the following diagram:
 
 .. raw:: html
 
-    <object data="../_images/form/form-field-parts.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form-field-parts.svg" type="image/svg+xml"
+        alt="Wireframe showing all functions in a form row, which are mentioned directly below."
+    ></object>
 
 The :ref:`form_label() <reference-forms-twig-label>`,
-:ref:`form_widget() <reference-forms-twig-widget>`,
+:ref:`form_widget() <reference-forms-twig-widget>` (the HTML input),
 :ref:`form_help() <reference-forms-twig-help>` and
 :ref:`form_errors() <reference-forms-twig-errors>` Twig functions give you total
 control over how each form field is rendered, so you can fully customize them:

form/form_themes.rst

@@ -247,7 +247,9 @@ In both cases, the ``field-part`` can be any of these valid form field parts:
 
 .. raw:: html
 
-    <object data="../_images/form/form-field-parts.svg" type="image/svg+xml"></object>
+    <object data="../_images/form/form-field-parts.svg" type="image/svg+xml"
+        alt="A wireframe showing all form field parts: form_row, form_label, form_widget, form_help and form_errors."
+    ></object>
 
 Fragment Naming for All Fields of the Same Type
 ...............................................

form/tailwindcss.rst

@@ -9,7 +9,7 @@ classes so out of the box, your forms will look decent. Customization is almost
 going to be required so this theme makes that easy.
 
 .. image:: /_images/form/tailwindcss-form.png
-   :align: center
+    :alt: An HTML form showing a range of form types styled using TailwindCSS.
 
 To use, first be sure you have installed and integrated `Tailwind CSS`_ and the
 `form plugin`_. Follow their respective documentation to install both packages.

introduction/from_flat_php_to_symfony.rst

@@ -657,7 +657,9 @@ It's a beautiful thing.
 
 .. raw:: html
 
-    <object data="../_images/http/request-flow.svg" type="image/svg+xml"></object>
+    <object data="../_images/http/request-flow.svg" type="image/svg+xml"
+        alt="A flow diagram visualizing the previously described process from front controller to response."
+    ></object>
 
 Where Symfony Delivers
 ----------------------

introduction/http_fundamentals.rst

@@ -17,8 +17,11 @@ HTTP (Hypertext Transfer Protocol) is a text language that allows two machines
 to communicate with each other. For example, when checking for the latest
 `xkcd`_ comic, the following (approximate) conversation takes place:
 
-.. image:: /_images/http/xkcd-full.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/http/xkcd-full.svg" type="image/svg+xml"
+        alt="A sequence diagram showing the browser sending &quot;Can I see today's comic?&quot; to the xkcd server. The server prepares the page's HTML and sents it back to the browser."
+    ></object>
 
 HTTP is the term used to describe this text-based language. The goal of
 your server is *always* to understand text requests and return text responses.
@@ -38,8 +41,11 @@ and then waits for the response.
 Take a look at the first part of the interaction (the request) between a
 browser and the xkcd web server:
 
-.. image:: /_images/http/xkcd-request.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/http/xkcd-request.svg" type="image/svg+xml"
+        alt="A sequence diagram showing the request from browser to the xkcd server."
+    ></object>
 
 In HTTP-speak, this HTTP request would actually look something like this:
 
@@ -100,8 +106,11 @@ client needs (via the URI) and what the client wants to do with that resource
 prepares the resource and returns it in an HTTP response. Consider the response
 from the xkcd web server:
 
-.. image:: /_images/http/xkcd-full.png
-   :align: center
+.. raw:: html
+
+    <object data="../_images/http/xkcd-full.svg" type="image/svg+xml"
+        alt="The full sequence diagram with the xkcd server sending the page's HTML back to the browser."
+    ></object>
 
 Translated into HTTP, the response sent back to the browser will look something
 like this:
@@ -346,7 +355,9 @@ to do:
 
 .. raw:: html
 
-    <object data="../_images/http/request-flow.svg" type="image/svg+xml"></object>
+    <object data="../_images/http/request-flow.svg" type="image/svg+xml"
+        alt="A flow diagram visualizing the request-response flow. Each step is written out in text in the next section."
+    ></object>
 
 Incoming requests are interpreted by the :doc:`Routing component </routing>` and
 passed to PHP functions that return ``Response`` objects.

mercure.rst

@@ -67,7 +67,11 @@ you must start it with the ``--no-tls`` option.
 Running a Mercure Hub
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. image:: /_images/mercure/schema.png
+.. raw:: html
+
+    <object data="../_images/mercure/hub.svg" type="image/svg+xml"
+        alt="Flow diagram showing a Symfony app communicating with the Mercure Hub using a POST request, and the Mercure Hub using SSE to communicate to the clients."
+    ></object>
 
 If you use the Docker integration, a hub is already up and running,
 and you can go straight to the next section.
@@ -309,6 +313,7 @@ as patterns:
     the received events:
 
     .. image:: /_images/mercure/chrome.png
+        :alt: The Chrome DevTools showing the EventStream tab containing information about each SSE event.
 
     To use it:
 
@@ -328,7 +333,11 @@ The Mercure protocol comes with a discovery mechanism.
 To leverage it, the Symfony application must expose the URL of the Mercure Hub
 in a ``Link`` HTTP header.
 
-.. image:: /_images/mercure/discovery.png
+.. raw:: html
+
+    <object data="../_images/mercure/discovery.svg" type="image/svg+xml"
+        alt="Flow diagram showing the Link response header set by the Symfony app to respond to an API request for a book with ID 1."
+    ></object>
 
 You can create ``Link`` headers with the ``Discovery`` helper class
 (under the hood, it uses the :doc:`WebLink Component </web_link>`)::
@@ -693,6 +702,8 @@ enable it::
     $ composer require --dev symfony/debug-pack
 
 .. image:: /_images/mercure/panel.png
+    :alt: The Mercure panel of the Symfony Profiler, showing information like time, memory, topics and data of each message sent by Mercure.
+    :class: with-browser
 
 Async dispatching
 -----------------

profiler.rst

@@ -25,8 +25,8 @@ toolbar injected at the bottom of your pages to open the web interface of the
 Symfony Profiler, which will look like this:
 
 .. image:: /_images/profiler/web-interface.png
-   :align: center
-   :class: with-browser
+    :alt: The Symfony Web profiler page.
+    :class: with-browser
 
 .. note::
 
@@ -199,13 +199,13 @@ event::
     use Symfony\Component\HttpKernel\KernelInterface;
 
     // ...
-    
+
     class MySubscriber implements EventSubscriberInterface
     {
         public function __construct(private KernelInterface $kernel)
         {
         }
-        
+
         // ...
 
         public function onKernelResponse(ResponseEvent $event)

quick_tour/the_big_picture.rst

@@ -52,8 +52,8 @@ it as follows:
 Try your new app by going to ``http://localhost:8000`` in a browser!
 
 .. image:: /_images/quick_tour/no_routes_page.png
-   :align: center
-   :class: with-browser
+    :alt: The default Symfony welcome page.
+    :class: with-browser
 
 Fundamentals: Route, Controller, Response
 -----------------------------------------

rate_limiter.rst

@@ -45,7 +45,9 @@ squares).
 
 .. raw:: html
 
-    <object data="_images/rate_limiter/fixed_window.svg" type="image/svg+xml"></object>
+    <object data="_images/rate_limiter/fixed_window.svg" type="image/svg+xml"
+        alt="A timeline showing fixed windows that accept a maximum of 5 hits."
+    ></object>
 
 Its main drawback is that resource usage is not evenly distributed in time and
 it can overload the server at the window edges. In this example,
@@ -66,7 +68,9 @@ using a 1 hour window that slides over the timeline:
 
 .. raw:: html
 
-    <object data="_images/rate_limiter/sliding_window.svg" type="image/svg+xml"></object>
+    <object data="_images/rate_limiter/sliding_window.svg" type="image/svg+xml"
+        alt="The same timeline with a sliding window that accepts only 5 hits in the previous hour."
+    ></object>
 
 As you can see, this removes the edges of the window and would prevent the
 6th request at 11:45.
@@ -89,18 +93,20 @@ Token Bucket Rate Limiter
 This technique implements the `token bucket algorithm`_, which defines
 continuously updating the budget of resource usage. It roughly works like this:
 
-* A bucket is created with an initial set of tokens;
-* A new token is added to the bucket with a predefined frequency (e.g. every second);
-* Allowing an event consumes one or more tokens;
-* If the bucket still contains tokens, the event is allowed; otherwise, it's denied;
-* If the bucket is at full capacity, new tokens are discarded.
+#. A bucket is created with an initial set of tokens;
+#. A new token is added to the bucket with a predefined frequency (e.g. every second);
+#. Allowing an event consumes one or more tokens;
+#. If the bucket still contains tokens, the event is allowed; otherwise, it's denied;
+#. If the bucket is at full capacity, new tokens are discarded.
 
 The below diagram shows a token bucket of size 4 that is filled with a rate
 of 1 token per 15 minutes:
 
 .. raw:: html
 
-    <object data="_images/rate_limiter/token_bucket.svg" type="image/svg+xml"></object>
+    <object data="_images/rate_limiter/token_bucket.svg" type="image/svg+xml"
+        alt="A timeline showing the token bucket over time, as described in this section."
+    ></object>
 
 This algorithm handles more complex back-off burst management.
 For instance, it can allow a user to try a password 5 times and then only

reference/forms/types/choice.rst

@@ -41,7 +41,7 @@ end users and the array values are the internal values used in the form field::
 This will create a ``select`` drop-down like this:
 
 .. image:: /_images/reference/form/choice-example1.png
-   :align: center
+    :alt: A choice list form input with the options "Maybe", "Yes" and "No".
 
 If the user selects ``No``, the form will return ``false`` for this field. Similarly,
 if the starting data for this field is ``true``, then ``Yes`` will be auto-selected.
@@ -137,7 +137,7 @@ by passing a multi-dimensional ``choices`` array::
     ]);
 
 .. image:: /_images/reference/form/choice-example4.png
-   :align: center
+    :alt: A choice list with the options "Yes" and "No" grouped under "Main Statuses" and the options "Backordered" and "Discontinued" under "Out of Stock Statuses".
 
 To get fancier, use the `group_by`_ option instead.
 

reference/forms/types/options/choice_label.rst.inc

@@ -39,7 +39,7 @@ This method is called for *each* choice, passing you the ``$choice`` and
 This will give you:
 
 .. image:: /_images/reference/form/choice-example2.png
-   :align: center
+    :alt: A choice list with the options "Definitely!", "NO" and "MAYBE".
 
 If your choice values are objects, then ``choice_label`` can also be a
 :ref:`property path <reference-form-option-property-path>`. Imagine you have some

reference/forms/types/options/group_by.rst.inc

@@ -35,7 +35,7 @@ This groups the dates that are within 3 days into "Soon" and everything else int
 a "Later" ``<optgroup>``:
 
 .. image:: /_images/reference/form/choice-example5.png
-   :align: center
+    :alt: A choice list with "now" and "tomorrow" grouped under "Soon", and "1 week" and "1 month" grouped under "Later".
 
 If you return ``null``, the option won't be grouped. You can also pass a string
 "property path" that will be called to get the group. See the `choice_label`_ for

reference/forms/types/options/preferred_choices.rst.inc

@@ -42,7 +42,7 @@ be especially useful if your values are objects::
 This will "prefer" the "now" and "tomorrow" choices only:
 
 .. image:: /_images/reference/form/choice-example3.png
-   :align: center
+    :alt: A choice list with "now" and "tomorrow" on top, separated by a line from "1 week" and "1 month".
 
 Finally, if your values are objects, you can also specify a property path string
 on the object that will return true or false.

security.rst

@@ -590,7 +590,7 @@ website. If you visit your homepage right now, you *will* have access and
 you'll see that you're visiting a page behind the firewall in the toolbar:
 
 .. image:: /_images/security/anonymous_wdt.png
-   :align: center
+   :alt: The Symfony profiler toolbar where the Security information shows "Authenticated: no" and "Firewall name: main"
 
 Visiting a URL under a firewall doesn't necessarily require you to be authenticated
 (e.g. the login form has to be accessible or some parts of your application
@@ -2603,7 +2603,9 @@ Authentication Events
 
 .. raw:: html
 
-    <object data="./_images/security/security_events.svg" type="image/svg+xml"></object>
+    <object data="../_images/security/security_events.svg" type="image/svg+xml"
+        alt="A flow diagram showing the authentication events that are described in this section in a request-response cycle."
+    ></object>
 
 :class:`Symfony\\Component\\Security\\Http\\Event\\CheckPassportEvent`
     Dispatched after the authenticator created the :ref:`security passport <security-passport>`.

security/login_link.rst

@@ -301,6 +301,7 @@ This will send an email like this to the user:
 
 .. image:: /_images/security/login_link_email.png
    :align: center
+   :alt: A default Symfony e-mail containing the text "Click on the button below to confirm you want to sign in" and the button with the login link.
 
 .. tip::
 

security/remember_me.rst

@@ -217,6 +217,7 @@ After logging in, you can use the security profiler to see if this badge is
 present:
 
 .. image:: /_images/security/profiler-badges.png
+    :alt: The Security page of the Symfony profiler, with the "Authenticators" tab showing the remember me badge in the passport object.
 
 Without this badge, remember me will be not be activated (regardless of all
 other settings).

setup/upgrade_major.rst

@@ -40,8 +40,8 @@ using a deprecated feature. When visiting your application in the
 in your browser, these notices are shown in the web dev toolbar:
 
 .. image:: /_images/install/deprecations-in-profiler.png
-   :align: center
-   :class: with-browser
+    :alt: The Logs page of the Symfony Profiler showing the deprecation notices.
+    :class: with-browser
 
 Ultimately, you should aim to stop using the deprecated functionality.
 Sometimes the warning might tell you exactly what to change.

translation.rst

@@ -1300,16 +1300,17 @@ Pseudo-localization translator
 
     The pseudolocalization translator is meant to be used for development only.
 
-The following image shows the main menu of the interface of a popular Internet
-service:
+The following image shows a typical menu on a webpage:
 
 .. image:: /_images/translation/pseudolocalization-interface-original.png
+    :alt: A menu showing multiple items nicely aligned next to eachother.
 
 This other image shows the same menu when the user switches the language to
 Spanish. Unexpectedly, some text is cut and other contents are so long that
 they overflow and you can't see them:
 
 .. image:: /_images/translation/pseudolocalization-interface-translated.png
+    :alt: In Spanish, some menu items contain more letters which result in them being cut.
 
 These kind of errors are very common, because different languages can be longer
 or shorter than the original application language. Another common issue is to
@@ -1414,10 +1415,14 @@ readable, contents to help you internationalize it. See for example the
 difference in the `Symfony Demo`_ application. This is the original page:
 
 .. image:: /_images/translation/pseudolocalization-symfony-demo-disabled.png
+    :alt: The Symfony demo login page.
+    :class: with-browser
 
 And this is the same page with pseudolocalization enabled:
 
 .. image:: /_images/translation/pseudolocalization-symfony-demo-enabled.png
+    :alt: The Symfony demo login page with pseudolocalization.
+    :class: with-browser
 
 Summary
 -------

workflow.rst

@@ -33,6 +33,7 @@ step or stage in the process is called a *place*. You also define *transitions*,
 which describe the action needed to get from one place to another.
 
 .. image:: /_images/components/workflow/states_transitions.png
+    :alt: An example state diagram for a workflow, showing transitions and places.
 
 A set of places and transitions creates a **definition**. A workflow needs
 a ``Definition`` and a way to write the states to the objects (i.e. an

workflow/dumping-workflows.rst

@@ -36,14 +36,17 @@ to dump it as an image:
 The DOT image will look like this:
 
 .. image:: /_images/components/workflow/blogpost.png
+    :alt: A state diagram of the Symfony workflow created by DOT.
 
 The Mermaid image will look like this:
 
 .. image:: /_images/components/workflow/blogpost_mermaid.png
+    :alt: A state diagram of the Symfony workflow created by Mermaid.
 
 The PlantUML image will look like this:
 
 .. image:: /_images/components/workflow/blogpost_puml.png
+    :alt: A state diagram of the Symfony workflow created by PlantUML.
 
 If you are creating workflows outside of a Symfony application, use the
 ``GraphvizDumper`` or ``StateMachineGraphvizDumper`` class to create the DOT
@@ -316,6 +319,7 @@ Below is the configuration for the pull request state machine with styling added
 The PlantUML image will look like this:
 
 .. image:: /_images/components/workflow/pull_request_puml_styled.png
+    :alt: A state diagram created by PlantUML with custom transition colors and descriptions.
 
 .. _`Graphviz`: https://www.graphviz.org
 .. _`Mermaid CLI`: https://github.com/mermaid-js/mermaid-cli

workflow/workflow-and-state-machine.rst

@@ -25,11 +25,13 @@ Examples
 The simplest workflow looks like this. It contains two places and one transition.
 
 .. image:: /_images/components/workflow/simple.png
+    :alt: A simple state diagram showing a single transition between two places.
 
 Workflows could be more complicated when they describe a real business case. The
 workflow below describes the process to fill in a job application.
 
 .. image:: /_images/components/workflow/job_application.png
+    :alt: A complex state diagram showing many places with multiple possible transitions between them.
 
 When you fill in a job application in this example there are 4 to 7 steps
 depending on the job you are applying for. Some jobs require personality
@@ -63,6 +65,7 @@ pull request. At any time, you can also "update" the pull request, which
 will result in another continuous integration run.
 
 .. image:: /_images/components/workflow/pull_request.png
+    :alt: A state diagram for the pull request process described previously.
 
 Below is the configuration for the pull request state machine.