diff --git a/Documentation-rendertest/ImagesAndFigures/FloatAndAlignment.rst b/Documentation-rendertest/ImagesAndFigures/FloatAndAlignment.rst
index 8b2f07f41..acc691ce9 100644
--- a/Documentation-rendertest/ImagesAndFigures/FloatAndAlignment.rst
+++ b/Documentation-rendertest/ImagesAndFigures/FloatAndAlignment.rst
@@ -20,7 +20,7 @@ Image float left
 
 .. |example-teaser-left| image:: ../images/q150_cccccc.png
    :alt: Left floating image
-   :class: float-left with-shadow
+   :class: float-start with-shadow
 
 |example-teaser-left|
 Typesetting is the composition of text by means of arranging physical
@@ -41,7 +41,7 @@ Image float right
 
 .. |example-teaser-right| image:: ../images/q150_cccccc.png
    :alt: Right floating image
-   :class: float-right with-shadow
+   :class: float-end with-shadow
 
 |example-teaser-right|
 Typesetting is the composition of text by means of arranging physical
@@ -62,7 +62,8 @@ Figure float left
 
 .. figure:: ../images/q150_cccccc.png
    :alt: Left floating figure
-   :class: float-left with-shadow
+   :align: left
+   :class: with-shadow
 
    A figure floated to the left
 
@@ -85,7 +86,8 @@ Figure float right
 
 .. figure:: ../images/q150_cccccc.png
    :alt: Right floating figure
-   :class: float-right with-shadow
+   :align: right
+   :class: with-shadow
 
    A figure floated to the right
 
diff --git a/composer.json b/composer.json
index ee2f8844f..ffe86093a 100644
--- a/composer.json
+++ b/composer.json
@@ -8,7 +8,7 @@
         "ext-dom": "*",
         "ext-libxml": "*",
         "brotkrueml/twig-codehighlight": "^1.0",
-        "league/flysystem": "^1.1.10",
+        "league/flysystem": "^3.29",
         "phpdocumentor/dev-server": "^1.9.4",
         "phpdocumentor/filesystem": "^1.9",
         "phpdocumentor/guides": "^1.9",
diff --git a/composer.lock b/composer.lock
index 0dc5bbbfa..99dcd569c 100644
--- a/composer.lock
+++ b/composer.lock
@@ -4,7 +4,7 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "a539658a6108a63f5757061bda1439ce",
+    "content-hash": "6bc548c131c804a8eba2d57af4be3cae",
     "packages": [
         {
             "name": "brotkrueml/twig-codehighlight",
@@ -876,54 +876,55 @@
         },
         {
             "name": "league/flysystem",
-            "version": "1.1.10",
+            "version": "3.32.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/thephpleague/flysystem.git",
-                "reference": "3239285c825c152bcc315fe0e87d6b55f5972ed1"
+                "reference": "254b1595b16b22dbddaaef9ed6ca9fdac4956725"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/thephpleague/flysystem/zipball/3239285c825c152bcc315fe0e87d6b55f5972ed1",
-                "reference": "3239285c825c152bcc315fe0e87d6b55f5972ed1",
+                "url": "https://api.github.com/repos/thephpleague/flysystem/zipball/254b1595b16b22dbddaaef9ed6ca9fdac4956725",
+                "reference": "254b1595b16b22dbddaaef9ed6ca9fdac4956725",
                 "shasum": ""
             },
             "require": {
-                "ext-fileinfo": "*",
-                "league/mime-type-detection": "^1.3",
-                "php": "^7.2.5 || ^8.0"
+                "league/flysystem-local": "^3.0.0",
+                "league/mime-type-detection": "^1.0.0",
+                "php": "^8.0.2"
             },
             "conflict": {
-                "league/flysystem-sftp": "<1.0.6"
+                "async-aws/core": "<1.19.0",
+                "async-aws/s3": "<1.14.0",
+                "aws/aws-sdk-php": "3.209.31 || 3.210.0",
+                "guzzlehttp/guzzle": "<7.0",
+                "guzzlehttp/ringphp": "<1.1.1",
+                "phpseclib/phpseclib": "3.0.15",
+                "symfony/http-client": "<5.2"
             },
             "require-dev": {
-                "phpspec/prophecy": "^1.11.1",
-                "phpunit/phpunit": "^8.5.8"
-            },
-            "suggest": {
-                "ext-ftp": "Allows you to use FTP server storage",
-                "ext-openssl": "Allows you to use FTPS server storage",
-                "league/flysystem-aws-s3-v2": "Allows you to use S3 storage with AWS SDK v2",
-                "league/flysystem-aws-s3-v3": "Allows you to use S3 storage with AWS SDK v3",
-                "league/flysystem-azure": "Allows you to use Windows Azure Blob storage",
-                "league/flysystem-cached-adapter": "Flysystem adapter decorator for metadata caching",
-                "league/flysystem-eventable-filesystem": "Allows you to use EventableFilesystem",
-                "league/flysystem-rackspace": "Allows you to use Rackspace Cloud Files",
-                "league/flysystem-sftp": "Allows you to use SFTP server storage via phpseclib",
-                "league/flysystem-webdav": "Allows you to use WebDAV storage",
-                "league/flysystem-ziparchive": "Allows you to use ZipArchive adapter",
-                "spatie/flysystem-dropbox": "Allows you to use Dropbox storage",
-                "srmklive/flysystem-dropbox-v2": "Allows you to use Dropbox storage for PHP 5 applications"
+                "async-aws/s3": "^1.5 || ^2.0",
+                "async-aws/simple-s3": "^1.1 || ^2.0",
+                "aws/aws-sdk-php": "^3.295.10",
+                "composer/semver": "^3.0",
+                "ext-fileinfo": "*",
+                "ext-ftp": "*",
+                "ext-mongodb": "^1.3|^2",
+                "ext-zip": "*",
+                "friendsofphp/php-cs-fixer": "^3.5",
+                "google/cloud-storage": "^1.23",
+                "guzzlehttp/psr7": "^2.6",
+                "microsoft/azure-storage-blob": "^1.1",
+                "mongodb/mongodb": "^1.2|^2",
+                "phpseclib/phpseclib": "^3.0.36",
+                "phpstan/phpstan": "^1.10",
+                "phpunit/phpunit": "^9.5.11|^10.0",
+                "sabre/dav": "^4.6.0"
             },
             "type": "library",
-            "extra": {
-                "branch-alias": {
-                    "dev-master": "1.1-dev"
-                }
-            },
             "autoload": {
                 "psr-4": {
-                    "League\\Flysystem\\": "src/"
+                    "League\\Flysystem\\": "src"
                 }
             },
             "notification-url": "https://packagist.org/downloads/",
@@ -933,40 +934,77 @@
             "authors": [
                 {
                     "name": "Frank de Jonge",
-                    "email": "info@frenky.net"
+                    "email": "info@frankdejonge.nl"
                 }
             ],
-            "description": "Filesystem abstraction: Many filesystems, one API.",
+            "description": "File storage abstraction for PHP",
             "keywords": [
-                "Cloud Files",
                 "WebDAV",
-                "abstraction",
                 "aws",
                 "cloud",
-                "copy.com",
-                "dropbox",
-                "file systems",
+                "file",
                 "files",
                 "filesystem",
                 "filesystems",
                 "ftp",
-                "rackspace",
-                "remote",
                 "s3",
                 "sftp",
                 "storage"
             ],
             "support": {
                 "issues": "https://github.com/thephpleague/flysystem/issues",
-                "source": "https://github.com/thephpleague/flysystem/tree/1.1.10"
+                "source": "https://github.com/thephpleague/flysystem/tree/3.32.0"
             },
-            "funding": [
+            "time": "2026-02-25T17:01:41+00:00"
+        },
+        {
+            "name": "league/flysystem-local",
+            "version": "3.31.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/thephpleague/flysystem-local.git",
+                "reference": "2f669db18a4c20c755c2bb7d3a7b0b2340488079"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/thephpleague/flysystem-local/zipball/2f669db18a4c20c755c2bb7d3a7b0b2340488079",
+                "reference": "2f669db18a4c20c755c2bb7d3a7b0b2340488079",
+                "shasum": ""
+            },
+            "require": {
+                "ext-fileinfo": "*",
+                "league/flysystem": "^3.0.0",
+                "league/mime-type-detection": "^1.0.0",
+                "php": "^8.0.2"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "League\\Flysystem\\Local\\": ""
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
                 {
-                    "url": "https://offset.earth/frankdejonge",
-                    "type": "other"
+                    "name": "Frank de Jonge",
+                    "email": "info@frankdejonge.nl"
                 }
             ],
-            "time": "2022-10-04T09:16:37+00:00"
+            "description": "Local filesystem adapter for Flysystem.",
+            "keywords": [
+                "Flysystem",
+                "file",
+                "files",
+                "filesystem",
+                "local"
+            ],
+            "support": {
+                "source": "https://github.com/thephpleague/flysystem-local/tree/3.31.0"
+            },
+            "time": "2026-01-23T15:30:45+00:00"
         },
         {
             "name": "league/mime-type-detection",
@@ -1675,30 +1713,35 @@
         },
         {
             "name": "phpdocumentor/flyfinder",
-            "version": "1.1.0",
+            "version": "2.0.0",
             "source": {
                 "type": "git",
                 "url": "https://github.com/phpDocumentor/FlyFinder.git",
-                "reference": "6e145e676d9fbade7527fd8d4c99ab36b687b958"
+                "reference": "92f5c407f63952fb66a6bb8c0489935b9c605888"
             },
             "dist": {
                 "type": "zip",
-                "url": "https://api.github.com/repos/phpDocumentor/FlyFinder/zipball/6e145e676d9fbade7527fd8d4c99ab36b687b958",
-                "reference": "6e145e676d9fbade7527fd8d4c99ab36b687b958",
+                "url": "https://api.github.com/repos/phpDocumentor/FlyFinder/zipball/92f5c407f63952fb66a6bb8c0489935b9c605888",
+                "reference": "92f5c407f63952fb66a6bb8c0489935b9c605888",
                 "shasum": ""
             },
             "require": {
-                "league/flysystem": "^1.0",
-                "php": "^7.2||^8.0"
+                "league/flysystem": "^3.0",
+                "php": "^8.0||^8.1||^8.2||^8.3"
             },
             "require-dev": {
-                "league/flysystem-memory": "~1",
-                "mockery/mockery": "^1.3"
+                "league/flysystem-memory": "~3",
+                "mockery/mockery": "^1.4",
+                "phpstan/extension-installer": "^1.4",
+                "phpstan/phpstan": "^1.12",
+                "phpstan/phpstan-phpunit": "^1.4",
+                "phpunit/phpunit": "^9.0",
+                "vimeo/psalm": "^5.26"
             },
             "type": "library",
             "extra": {
                 "branch-alias": {
-                    "dev-master": "1.x-dev"
+                    "dev-master": "2.x-dev"
                 }
             },
             "autoload": {
@@ -1720,9 +1763,9 @@
             ],
             "support": {
                 "issues": "https://github.com/phpDocumentor/FlyFinder/issues",
-                "source": "https://github.com/phpDocumentor/FlyFinder/tree/1.1.0"
+                "source": "https://github.com/phpDocumentor/FlyFinder/tree/2.0.0"
             },
-            "time": "2021-06-04T13:44:40+00:00"
+            "time": "2024-09-15T19:58:36+00:00"
         },
         {
             "name": "phpdocumentor/guides",
diff --git a/packages/typo3-docs-theme/assets/sass/components/_images.scss b/packages/typo3-docs-theme/assets/sass/components/_images.scss
index 5c637cdfd..f4b5b91f2 100644
--- a/packages/typo3-docs-theme/assets/sass/components/_images.scss
+++ b/packages/typo3-docs-theme/assets/sass/components/_images.scss
@@ -17,15 +17,20 @@ figure {
     &:not(:first-child) {
         @extend .mt-3;
     }
+    &.float-start,
+    &.float-end,
+    // Deprecated: legacy Bootstrap 4 class names — remove after migration period (see #1179)
     &.float-left,
     &.float-right {
         margin-bottom: $spacer;
         max-width: 50%;
     }
+    &.float-start,
     &.float-left {
         float: left;
         margin-right: $spacer;
     }
+    &.float-end,
     &.float-right {
         float: right;
         margin-left: $spacer;
@@ -37,6 +42,8 @@ figure {
 }
 
 @media (max-width: 575.98px) {
+    figure.float-start,
+    figure.float-end,
     figure.float-left,
     figure.float-right {
         float: none;
diff --git a/packages/typo3-docs-theme/assets/sass/components/_rst.scss b/packages/typo3-docs-theme/assets/sass/components/_rst.scss
index daef8b2d7..c7d6efdbc 100644
--- a/packages/typo3-docs-theme/assets/sass/components/_rst.scss
+++ b/packages/typo3-docs-theme/assets/sass/components/_rst.scss
@@ -32,11 +32,14 @@
         display: inline-block;
         max-width: 100%;
         height: auto;
+        // Deprecated: legacy Bootstrap 4 class names — remove after migration period (see #1179)
+        &.float-start,
         &.float-left {
             float: left;
             margin-right: $spacer;
             margin-bottom: $spacer;
         }
+        &.float-end,
         &.float-right {
             float: right;
             margin-left: $spacer;
@@ -57,6 +60,17 @@
             }
         }
     }
+    @media (max-width: 575.98px) {
+        img.float-start,
+        img.float-end,
+        img.float-left,
+        img.float-right {
+            float: none;
+            max-width: 100%;
+            margin-left: 0;
+            margin-right: 0;
+        }
+    }
     .plantuml object {
         height: auto !important;
     }
diff --git a/packages/typo3-docs-theme/resources/config/typo3-docs-theme.php b/packages/typo3-docs-theme/resources/config/typo3-docs-theme.php
index 8a2fc7098..5960e4370 100644
--- a/packages/typo3-docs-theme/resources/config/typo3-docs-theme.php
+++ b/packages/typo3-docs-theme/resources/config/typo3-docs-theme.php
@@ -29,6 +29,7 @@
 use T3Docs\Typo3DocsTheme\Directives\ConfvalMenuDirective;
 use T3Docs\Typo3DocsTheme\Directives\DirectoryTreeDirective;
 use T3Docs\Typo3DocsTheme\Directives\FigureDirective;
+use T3Docs\Typo3DocsTheme\Directives\ImageDirective;
 use T3Docs\Typo3DocsTheme\Directives\GlossaryDirective;
 use T3Docs\Typo3DocsTheme\Directives\GroupTabDirective;
 use T3Docs\Typo3DocsTheme\Directives\IncludeDirective;
@@ -203,6 +204,7 @@
         ->set(DirectoryTreeDirective::class)
         ->set(FigureDirective::class)
         ->arg('$startingRule', service(DirectiveContentRule::class))
+        ->set(ImageDirective::class)
         ->set(GlossaryDirective::class)
         ->set(GroupTabDirective::class)
         ->set(IncludeDirective::class)
diff --git a/packages/typo3-docs-theme/resources/public/css/theme.css b/packages/typo3-docs-theme/resources/public/css/theme.css
index be8d0e527..4064e5338 100644
--- a/packages/typo3-docs-theme/resources/public/css/theme.css
+++ b/packages/typo3-docs-theme/resources/public/css/theme.css
@@ -24704,15 +24704,15 @@ dl.command .command-arguments section {
 figure figcaption p:last-child {
   margin-bottom: 0;
 }
-figure.float-left, figure.float-right {
+figure.float-start, figure.float-end, figure.float-left, figure.float-right {
   margin-bottom: 1rem;
   max-width: 50%;
 }
-figure.float-left {
+figure.float-start, figure.float-left {
   float: left;
   margin-right: 1rem;
 }
-figure.float-right {
+figure.float-end, figure.float-right {
   float: right;
   margin-left: 1rem;
 }
@@ -24722,6 +24722,8 @@ figure.align-center {
 }
 
 @media (max-width: 575.98px) {
+  figure.float-start,
+  figure.float-end,
   figure.float-left,
   figure.float-right {
     float: none;
@@ -24825,13 +24827,15 @@ article *:hover > a.headerlink, article *:hover > a.permalink, article *:hover .
   max-width: 100%;
   height: auto;
 }
-.rst-content img.float-left,
+.rst-content img.float-start, .rst-content img.float-left,
+.rst-content object.float-start,
 .rst-content object.float-left {
   float: left;
   margin-right: 1rem;
   margin-bottom: 1rem;
 }
-.rst-content img.float-right,
+.rst-content img.float-end, .rst-content img.float-right,
+.rst-content object.float-end,
 .rst-content object.float-right {
   float: right;
   margin-left: 1rem;
@@ -24844,13 +24848,14 @@ article *:hover > a.headerlink, article *:hover > a.permalink, article *:hover .
   margin-right: auto;
 }
 @media (max-width: 575.98px) {
-  .rst-content img.float-left, .rst-content img.float-right,
-  .rst-content object.float-left,
-  .rst-content object.float-right {
+  .rst-content img.float-start,
+  .rst-content img.float-end,
+  .rst-content img.float-left,
+  .rst-content img.float-right {
     float: none;
+    max-width: 100%;
     margin-left: 0;
     margin-right: 0;
-    max-width: 100%;
   }
 }
 .rst-content .plantuml object {
diff --git a/packages/typo3-docs-theme/resources/template/body/figure.html.twig b/packages/typo3-docs-theme/resources/template/body/figure.html.twig
index 9a46ae8ff..9ff4ea6da 100644
--- a/packages/typo3-docs-theme/resources/template/body/figure.html.twig
+++ b/packages/typo3-docs-theme/resources/template/body/figure.html.twig
@@ -1,6 +1,11 @@
-{%- set alignMap = {'left': 'float-left', 'right': 'float-right', 'center': 'align-center'} -%}
+{# Maps RST :align: values to CSS classes. Duplicated in image.html.twig — keep in sync. #}
+{# See also: FigureDirective.php / ImageDirective.php for :class: float-left/right rewriting #}
+{%- set alignMap = {'left': 'float-start', 'right': 'float-end', 'center': 'align-center'} -%}
 {%- set alignClass = node.hasOption('align') ? alignMap[node.option('align')]|default('') : '' -%}
-{%- set classes = ([node.classesString, alignClass]|join(' '))|trim -%}
+{%- set classes = node.classesString|trim -%}
+{%- if alignClass and alignClass not in (classes ? classes|split(' ') : []) -%}
+    {%- set classes = ([classes, alignClass]|join(' '))|trim -%}
+{%- endif -%}
 <figure
     {%- if classes %} class="{{ classes }}"{% endif -%}
     {%- if node.hasOption('figwidth') %} style="{% if node.hasOption('figwidth') %}width: {{ node.option('figwidth') }};{% endif %}"{% endif -%}
diff --git a/packages/typo3-docs-theme/resources/template/body/image.html.twig b/packages/typo3-docs-theme/resources/template/body/image.html.twig
index 9b98b0ca1..3701f60c5 100644
--- a/packages/typo3-docs-theme/resources/template/body/image.html.twig
+++ b/packages/typo3-docs-theme/resources/template/body/image.html.twig
@@ -2,9 +2,14 @@
 {%- if node.hasOption('zoom') -%}
 <span data-zoom="{{ node.option('zoom') }}"{% if node.hasOption('gallery') %} data-gallery="{{ node.option('gallery') }}"{% endif %}{% if node.hasOption('zoom-factor') %} data-zoom-factor="{{ node.option('zoom-factor') }}"{% endif %}{% if node.hasOption('zoom-indicator') %} data-zoom-indicator="{{ node.option('zoom-indicator') }}"{% endif %}>
 {%- endif -%}
-{%- set alignMap = {'left': 'float-left', 'right': 'float-right', 'center': 'align-center'} -%}
+{# Maps RST :align: values to CSS classes. Duplicated in figure.html.twig — keep in sync. #}
+{# See also: FigureDirective.php / ImageDirective.php for :class: float-left/right rewriting #}
+{%- set alignMap = {'left': 'float-start', 'right': 'float-end', 'center': 'align-center'} -%}
 {%- set alignClass = node.hasOption('align') ? alignMap[node.option('align')]|default('') : '' -%}
-{%- set classes = ([node.classesString, alignClass]|join(' '))|trim -%}
+{%- set classes = node.classesString|trim -%}
+{%- if alignClass and alignClass not in (classes ? classes|split(' ') : []) -%}
+    {%- set classes = ([classes, alignClass]|join(' '))|trim -%}
+{%- endif -%}
 <img
     src="{%- if node.value is external_target -%} {{ node.value }} {%- else -%} {{ asset(node.value) }} {%- endif -%}"
     {% if node.hasOption('width') %}width="{{ node.option('width') }}"{% endif%}
diff --git a/packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php b/packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php
index 2cd1bf4c2..7b1c73d36 100644
--- a/packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php
+++ b/packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php
@@ -6,6 +6,7 @@
 
 use phpDocumentor\Guides\NodeRenderers\TemplateNodeRenderer;
 use phpDocumentor\Guides\RestructuredText\Directives\FigureDirective as BaseFigureDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\ImageDirective as BaseImageDirective;
 use phpDocumentor\Guides\TemplateRenderer;
 use Symfony\Component\Config\FileLocator;
 use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
@@ -15,7 +16,6 @@
 use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
 use Symfony\Component\DependencyInjection\Loader\PhpFileLoader;
 use Symfony\Component\DependencyInjection\Reference;
-use T3Docs\Typo3DocsTheme\Directives\FigureDirective;
 use T3Docs\Typo3DocsTheme\Nodes\Inline\CodeInlineNode;
 use T3Docs\Typo3DocsTheme\Nodes\Inline\ComposerInlineNode;
 use T3Docs\Typo3DocsTheme\Nodes\Inline\FileInlineNode;
@@ -114,14 +114,19 @@ public function prepend(ContainerBuilder $container): void
     }
 
     /**
-     * Remove the base library's FigureDirective in favor of our custom implementation
-     * that supports zoom functionality.
+     * Remove the base library's directives in favor of our custom implementations.
+     *
+     * - FigureDirective: supports zoom functionality and float class deprecation
+     * - ImageDirective: uses composition to add float class deprecation handling
      */
     public function process(ContainerBuilder $container): void
     {
-        // Remove the base library's FigureDirective to let our custom one take over
         if ($container->hasDefinition(BaseFigureDirective::class)) {
             $container->removeDefinition(BaseFigureDirective::class);
         }
+
+        if ($container->hasDefinition(BaseImageDirective::class)) {
+            $container->removeDefinition(BaseImageDirective::class);
+        }
     }
 }
diff --git a/packages/typo3-docs-theme/src/Directives/FigureDirective.php b/packages/typo3-docs-theme/src/Directives/FigureDirective.php
index e2cecb7ec..7ae5ccffc 100644
--- a/packages/typo3-docs-theme/src/Directives/FigureDirective.php
+++ b/packages/typo3-docs-theme/src/Directives/FigureDirective.php
@@ -21,13 +21,16 @@
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
 use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use Psr\Log\LoggerInterface;
 
+use function array_filter;
 use function dirname;
+use function explode;
+use function implode;
 use function in_array;
 use function is_string;
-use function preg_replace;
-use function trim;
 
 /**
  * Renders a figure with optional zoom functionality.
@@ -55,12 +58,15 @@
  */
 final class FigureDirective extends BaseDirective
 {
+    use RewritesLegacyFloatClasses;
+
     private const VALID_ZOOM_MODES = ['lightbox', 'gallery', 'inline', 'lens'];
 
     /** @param Rule<CollectionNode> $startingRule */
     public function __construct(
         private readonly DocumentNameResolverInterface $documentNameResolver,
         private readonly Rule $startingRule,
+        private readonly LoggerInterface $logger,
     ) {}
 
     public function getName(): string
@@ -85,16 +91,39 @@ public function process(
             dirname($blockContext->getDocumentParserContext()->getContext()->getCurrentAbsolutePath()),
             $directive->getData(),
         ));
-        // Strip float classes from the inner image - floating should only
-        // apply to the <figure> element to keep the caption below the image.
-        // Note: Currently the framework's postProcessNode() only processes the
-        // top-level FigureNode, so the inner image's classesString is empty.
-        // We strip here for forward-compatibility should this behavior change.
-        $imageClass = isset($scalarOptions['class']) && is_string($scalarOptions['class'])
+        // Handle float classes on the figure element
+        $figureClass = isset($scalarOptions['class']) && is_string($scalarOptions['class'])
             ? $scalarOptions['class']
             : null;
-        if ($imageClass !== null) {
-            $imageClass = trim((string) preg_replace('/\bfloat-(left|right)\b/', '', $imageClass)) ?: null;
+
+        if ($figureClass !== null) {
+            // Detect and rewrite legacy float-left/float-right to float-start/float-end
+            // See also: figure.html.twig / image.html.twig alignMap for :align: option mapping
+            if ($this->hasLegacyFloatClass($figureClass)) {
+                $this->logger->warning(
+                    'Using `:class: float-left` / `:class: float-right` is deprecated. '
+                    . 'Use `:align: left` / `:align: right` instead.',
+                    $blockContext->getLoggerInformation(),
+                );
+                $figureClass = $this->rewriteLegacyFloatClasses($figureClass);
+                // Update the raw directive option so that DirectiveRule::postProcessNode
+                // uses the rewritten class when calling setClasses() on the node
+                $directive->addOption(new DirectiveOption('class', $figureClass));
+            }
+        }
+
+        // Strip float classes from the inner image — floating should only apply
+        // to the <figure> element to keep the caption below the image.
+        // Non-float classes (e.g. with-shadow) are still propagated to the
+        // inner <img> so they can style the image itself.
+        if ($figureClass !== null) {
+            $imageClasses = array_filter(
+                explode(' ', $figureClass),
+                static fn(string $class): bool => !in_array($class, ['float-start', 'float-end'], true),
+            );
+            $imageClass = $imageClasses !== [] ? implode(' ', $imageClasses) : null;
+        } else {
+            $imageClass = null;
         }
 
         $image = $image->withOptions([
@@ -121,7 +150,8 @@ public function process(
             $filteredOptions['zoom'] = null;
         }
 
-        // Remove options that are already handled by the image node
+        // Remove options that are already handled by the image node or by
+        // DirectiveRule::postProcessNode (class is handled via setClasses())
         unset(
             $filteredOptions['width'],
             $filteredOptions['height'],
diff --git a/packages/typo3-docs-theme/src/Directives/ImageDirective.php b/packages/typo3-docs-theme/src/Directives/ImageDirective.php
new file mode 100644
index 000000000..d53cc5597
--- /dev/null
+++ b/packages/typo3-docs-theme/src/Directives/ImageDirective.php
@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\Directives;
+
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
+use phpDocumentor\Guides\RestructuredText\Directives\ImageDirective as BaseImageDirective;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
+use Psr\Log\LoggerInterface;
+
+use function is_string;
+
+/**
+ * Decorates the upstream ImageDirective to detect and rewrite deprecated float class names.
+ *
+ * Intercepts `:class: float-left` / `:class: float-right` and rewrites them to
+ * `float-start` / `float-end` (Bootstrap 5) before delegating to the upstream directive,
+ * emitting a deprecation warning.
+ *
+ * Uses composition instead of inheritance because the upstream class is declared final.
+ * The upstream instance is created internally to avoid Symfony service decoration
+ * side effects with tagged directive services.
+ *
+ * The deprecation warning additionally mentions `float-start`/`float-end` as
+ * alternatives because substitution images (|name|) do not support the `:align:`
+ * option — only `:class:` is available.
+ *
+ * Note: process() delegates to $this->inner->process() which internally calls
+ * BaseDirective::process() including withKeepExistingOptions(). We intentionally
+ * skip the outer BaseDirective::process() to avoid double-applying options.
+ *
+ * @see BaseImageDirective (upstream, composed)
+ * @see https://github.com/phpDocumentor/guides/issues/1303 (final removal request)
+ * @see FigureDirective (same float class rewriting for figures)
+ */
+final class ImageDirective extends BaseDirective
+{
+    use RewritesLegacyFloatClasses;
+
+    private readonly BaseImageDirective $inner;
+
+    public function __construct(
+        DocumentNameResolverInterface $documentNameResolver,
+        private readonly LoggerInterface $logger,
+    ) {
+        $this->inner = new BaseImageDirective($documentNameResolver);
+    }
+
+    public function getName(): string
+    {
+        return 'image';
+    }
+
+    public function process(
+        BlockContext $blockContext,
+        Directive $directive,
+    ): Node|null {
+        // Detect and rewrite legacy float classes before delegating to upstream
+        // See also: figure.html.twig / image.html.twig alignMap for :align: option mapping
+        if ($directive->hasOption('class')) {
+            $classValue = $directive->getOption('class')->getValue();
+            if (is_string($classValue) && $this->hasLegacyFloatClass($classValue)) {
+                $this->logger->warning(
+                    'Using `:class: float-left` / `:class: float-right` is deprecated. '
+                    . 'Use `:align: left` / `:align: right` instead, or `float-start` / `float-end` for substitution images.',
+                    $blockContext->getLoggerInformation(),
+                );
+                $directive->addOption(new DirectiveOption('class', $this->rewriteLegacyFloatClasses($classValue)));
+            }
+        }
+
+        return $this->inner->process($blockContext, $directive);
+    }
+}
diff --git a/packages/typo3-docs-theme/src/Directives/IncludeDirective.php b/packages/typo3-docs-theme/src/Directives/IncludeDirective.php
index 47cc5bb62..1e7845672 100644
--- a/packages/typo3-docs-theme/src/Directives/IncludeDirective.php
+++ b/packages/typo3-docs-theme/src/Directives/IncludeDirective.php
@@ -54,9 +54,6 @@ public function processNode(
     }
 
 
-    /**
-     * @throws \League\Flysystem\FileNotFoundException
-     */
     public function resolveGlobInclude(BlockContext $blockContext, string $inputPath, Directive $directive): LiteralBlockNode|CollectionNode|CodeNode
     {
         $parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
@@ -103,9 +100,6 @@ public function resolveGlobInclude(BlockContext $blockContext, string $inputPath
         return new CollectionNode($nodes);
     }
 
-    /**
-     * @throws \League\Flysystem\FileNotFoundException
-     */
     public function resolveBasicInclude(BlockContext $blockContext, string $inputPath, Directive $directive): LiteralBlockNode|CollectionNode|CodeNode
     {
         $parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
@@ -121,9 +115,6 @@ public function resolveBasicInclude(BlockContext $blockContext, string $inputPat
         return $this->getCollectionFromPath($origin, $path, $directive, $blockContext);
     }
 
-    /**
-     * @throws \League\Flysystem\FileNotFoundException
-     */
     public function getCollectionFromPath(\League\Flysystem\FilesystemInterface|\phpDocumentor\FileSystem\FileSystem $origin, string $path, Directive $directive, BlockContext $blockContext): LiteralBlockNode|CollectionNode|CodeNode
     {
         $contents = $origin->read($path);
diff --git a/packages/typo3-docs-theme/src/Directives/RewritesLegacyFloatClasses.php b/packages/typo3-docs-theme/src/Directives/RewritesLegacyFloatClasses.php
new file mode 100644
index 000000000..14f32a7dc
--- /dev/null
+++ b/packages/typo3-docs-theme/src/Directives/RewritesLegacyFloatClasses.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\Directives;
+
+use function preg_match;
+use function preg_replace;
+
+/**
+ * Shared logic for detecting and rewriting deprecated Bootstrap 4 float class names.
+ *
+ * Rewrites `float-left` → `float-start` and `float-right` → `float-end` (Bootstrap 5
+ * logical properties). Used by both FigureDirective and ImageDirective.
+ *
+ * @see FigureDirective
+ * @see ImageDirective
+ */
+trait RewritesLegacyFloatClasses
+{
+    private function hasLegacyFloatClass(string $classValue): bool
+    {
+        return (bool) preg_match('/\bfloat-(left|right)\b/', $classValue);
+    }
+
+    private function rewriteLegacyFloatClasses(string $classValue): string
+    {
+        return (string) preg_replace(
+            ['/\bfloat-left\b/', '/\bfloat-right\b/'],
+            ['float-start', 'float-end'],
+            $classValue,
+        );
+    }
+}
diff --git a/packages/typo3-docs-theme/src/Directives/SiteSetSettingsDirective.php b/packages/typo3-docs-theme/src/Directives/SiteSetSettingsDirective.php
index cda78f18e..68e22e9fb 100644
--- a/packages/typo3-docs-theme/src/Directives/SiteSetSettingsDirective.php
+++ b/packages/typo3-docs-theme/src/Directives/SiteSetSettingsDirective.php
@@ -126,7 +126,6 @@ public function processNode(
     }
 
     /**
-     * @throws \League\Flysystem\FileNotFoundException
      * @throws FileLoadingException
      */
     public function loadFileFromDocumentation(BlockContext $blockContext, string $filename): string
diff --git a/packages/typo3-docs-theme/src/EventListeners/CopyResources.php b/packages/typo3-docs-theme/src/EventListeners/CopyResources.php
index 093eb77fa..6abc9d455 100644
--- a/packages/typo3-docs-theme/src/EventListeners/CopyResources.php
+++ b/packages/typo3-docs-theme/src/EventListeners/CopyResources.php
@@ -4,8 +4,9 @@
 
 namespace T3Docs\Typo3DocsTheme\EventListeners;
 
-use League\Flysystem\Adapter\Local;
+use League\Flysystem\FilesystemException;
 use League\Flysystem\Filesystem;
+use League\Flysystem\Local\LocalFilesystemAdapter;
 use phpDocumentor\Guides\Event\PostRenderProcess;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\Finder\Finder;
@@ -35,29 +36,31 @@ public function __invoke(PostRenderProcess $event): void
             return;
         }
 
-        $source = new Filesystem(new Local($fullResourcesPath));
+        $source = new Filesystem(new LocalFilesystemAdapter($fullResourcesPath));
 
-        /** @var \League\Flysystem\FilesystemInterface */
         $destination = $event->getCommand()->getDestination();
 
         $finder = new Finder();
         $finder->files()->in($fullResourcesPath);
 
         foreach ($finder as $file) {
-            $stream = $source->readStream($file->getRelativePathname());
-            if ($stream === false) {
-                $this->logger->warning(sprintf('Cannot read stream from "%s"', $file->getRealPath()));
-                continue;
+            $stream = null;
+            try {
+                $stream = $source->readStream($file->getRelativePathname());
+                $destinationPath = sprintf(
+                    '%s/%s%s',
+                    self::DESTINATION_PATH,
+                    $file->getRelativePath() !== '' ? $file->getRelativePath() . '/' : '',
+                    $file->getFilename()
+                );
+                $destination->putStream($destinationPath, $stream);
+            } catch (FilesystemException $e) {
+                $this->logger->warning(sprintf('Cannot copy resource "%s": %s', $file->getRealPath(), $e->getMessage()));
+            } finally {
+                if (is_resource($stream)) {
+                    fclose($stream);
+                }
             }
-
-            $destinationPath = sprintf(
-                '%s/%s%s',
-                self::DESTINATION_PATH,
-                $file->getRelativePath() !== '' ? $file->getRelativePath() . '/' : '',
-                $file->getFilename()
-            );
-            $destination->putStream($destinationPath, $stream);
-            is_resource($stream) && fclose($stream);
         }
     }
 }
diff --git a/packages/typo3-docs-theme/src/Twig/TwigExtension.php b/packages/typo3-docs-theme/src/Twig/TwigExtension.php
index e3cc2635b..3b81facc4 100644
--- a/packages/typo3-docs-theme/src/Twig/TwigExtension.php
+++ b/packages/typo3-docs-theme/src/Twig/TwigExtension.php
@@ -4,7 +4,7 @@
 
 namespace T3Docs\Typo3DocsTheme\Twig;
 
-use League\Flysystem\Exception;
+use League\Flysystem\FilesystemException;
 use LogicException;
 use phpDocumentor\Guides\Nodes\AnchorNode;
 use phpDocumentor\Guides\Nodes\DocumentTree\DocumentEntryNode;
@@ -617,7 +617,7 @@ private function copyAsset(
                     $renderContext->getLoggerInformation(),
                 );
             }
-        } catch (LogicException|Exception $e) {
+        } catch (LogicException|FilesystemException $e) {
             $this->logger->error(
                 sprintf('Unable to write file "%s", %s', $outputPath, $e->getMessage()),
                 $renderContext->getLoggerInformation(),
diff --git a/packages/typo3-docs-theme/tests/unit/Directives/FigureDirectiveTest.php b/packages/typo3-docs-theme/tests/unit/Directives/FigureDirectiveTest.php
new file mode 100644
index 000000000..d9f0d46e7
--- /dev/null
+++ b/packages/typo3-docs-theme/tests/unit/Directives/FigureDirectiveTest.php
@@ -0,0 +1,264 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\Tests\Unit\Directives;
+
+use phpDocumentor\Guides\Nodes\CollectionNode;
+use phpDocumentor\Guides\Nodes\FigureNode;
+use phpDocumentor\Guides\Nodes\InlineCompoundNode;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
+use phpDocumentor\Guides\ParserContext;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use T3Docs\Typo3DocsTheme\Directives\FigureDirective;
+
+final class FigureDirectiveTest extends TestCase
+{
+    private FigureDirective $subject;
+    private DocumentNameResolverInterface&MockObject $documentNameResolver;
+    /** @var Rule<CollectionNode>&MockObject */
+    private Rule&MockObject $startingRule;
+    private LoggerInterface&MockObject $logger;
+
+    protected function setUp(): void
+    {
+        $this->documentNameResolver = $this->createMock(DocumentNameResolverInterface::class);
+        $this->documentNameResolver->method('absoluteUrl')->willReturn('/resolved/image.png');
+        $this->startingRule = $this->createMock(Rule::class);
+        $this->logger = $this->createMock(LoggerInterface::class);
+
+        $this->subject = new FigureDirective(
+            $this->documentNameResolver,
+            $this->startingRule,
+            $this->logger,
+        );
+    }
+
+    #[Test]
+    public function getNameReturnsFigure(): void
+    {
+        self::assertSame('figure', $this->subject->getName());
+    }
+
+    #[Test]
+    public function processReturnsNullWhenStartingRuleReturnsNull(): void
+    {
+        $this->startingRule->method('apply')->willReturn(null);
+
+        $result = $this->subject->process(
+            $this->createBlockContext(),
+            new Directive('', 'figure', 'image.png'),
+        );
+
+        self::assertNull($result);
+    }
+
+    #[Test]
+    public function processRewritesLegacyFloatLeftClass(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-left'),
+        ]);
+
+        $this->logger->expects(self::once())
+            ->method('warning')
+            ->with(self::stringContains('deprecated'));
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        // The directive class option should be rewritten for postProcessNode
+        self::assertSame('float-start', $directive->getOption('class')->getValue());
+        // The inner image should NOT have float classes
+        self::assertNull($result->getImage()->getOption('class'));
+    }
+
+    #[Test]
+    public function processRewritesLegacyFloatRightClass(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-right'),
+        ]);
+
+        $this->logger->expects(self::once())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        self::assertSame('float-end', $directive->getOption('class')->getValue());
+        self::assertNull($result->getImage()->getOption('class'));
+    }
+
+    #[Test]
+    public function processPreservesNonFloatClassesOnInnerImage(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', 'with-shadow float-left'),
+        ]);
+
+        $this->logger->expects(self::once())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        // Directive updated with rewritten classes
+        self::assertSame('with-shadow float-start', $directive->getOption('class')->getValue());
+        // Inner image gets only non-float classes
+        self::assertSame('with-shadow', $result->getImage()->getOption('class'));
+    }
+
+    #[Test]
+    public function processDoesNotRewriteModernClasses(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-start'),
+        ]);
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        // Float classes stripped from inner image
+        self::assertNull($result->getImage()->getOption('class'));
+    }
+
+    #[Test]
+    public function processHandlesNoClassOption(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png');
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        self::assertNull($result->getImage()->getOption('class'));
+    }
+
+    #[Test]
+    public function processHandlesNonStringClassValue(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', true),
+        ]);
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+    }
+
+    #[Test]
+    public function processFiltersInvalidZoomMode(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'zoom' => new DirectiveOption('zoom', 'invalid-mode'),
+        ]);
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        self::assertNull($result->getOption('zoom'));
+    }
+
+    #[Test]
+    #[DataProvider('validZoomModeProvider')]
+    public function processAcceptsValidZoomModes(string $mode): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'zoom' => new DirectiveOption('zoom', $mode),
+        ]);
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        self::assertSame($mode, $result->getOption('zoom'));
+    }
+
+    /** @return \Generator<string, array{string}> */
+    public static function validZoomModeProvider(): \Generator
+    {
+        yield 'lightbox' => ['lightbox'];
+        yield 'gallery' => ['gallery'];
+        yield 'inline' => ['inline'];
+        yield 'lens' => ['lens'];
+    }
+
+    #[Test]
+    public function processPassesImageOptionsToImageNode(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'width' => new DirectiveOption('width', '200'),
+            'height' => new DirectiveOption('height', '100'),
+            'alt' => new DirectiveOption('alt', 'test image'),
+            'scale' => new DirectiveOption('scale', '50'),
+        ]);
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        self::assertSame('200', $result->getImage()->getOption('width'));
+        self::assertSame('100', $result->getImage()->getOption('height'));
+        self::assertSame('test image', $result->getImage()->getOption('alt'));
+        self::assertSame('50', $result->getImage()->getOption('scale'));
+    }
+
+    #[Test]
+    public function processStripsFloatStartFromInnerImage(): void
+    {
+        $this->startingRule->method('apply')->willReturn(new CollectionNode([new InlineCompoundNode([])]));
+
+        $directive = new Directive('', 'figure', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-end with-border'),
+        ]);
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(FigureNode::class, $result);
+        // Float-end stripped, only with-border remains
+        self::assertSame('with-border', $result->getImage()->getOption('class'));
+    }
+
+    private function createBlockContext(): BlockContext
+    {
+        $parserContext = $this->createMock(ParserContext::class);
+        $parserContext->method('getCurrentAbsolutePath')->willReturn('/test');
+        $parserContext->method('getLoggerInformation')->willReturn(['rst-file' => 'test.rst']);
+        $parserContext->method('getInitialHeaderLevel')->willReturn(1);
+
+        $documentParserContext = $this->createMock(DocumentParserContext::class);
+        $documentParserContext->method('getContext')->willReturn($parserContext);
+        $documentParserContext->method('getLoggerInformation')->willReturn(['rst-file' => 'test.rst']);
+
+        return new BlockContext($documentParserContext, '', false, 0);
+    }
+}
diff --git a/packages/typo3-docs-theme/tests/unit/Directives/ImageDirectiveTest.php b/packages/typo3-docs-theme/tests/unit/Directives/ImageDirectiveTest.php
new file mode 100644
index 000000000..a207a7701
--- /dev/null
+++ b/packages/typo3-docs-theme/tests/unit/Directives/ImageDirectiveTest.php
@@ -0,0 +1,143 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\Tests\Unit\Directives;
+
+use phpDocumentor\Guides\Nodes\ImageNode;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
+use phpDocumentor\Guides\RestructuredText\Parser\Directive;
+use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
+use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
+use phpDocumentor\Guides\ParserContext;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\MockObject\MockObject;
+use PHPUnit\Framework\TestCase;
+use Psr\Log\LoggerInterface;
+use T3Docs\Typo3DocsTheme\Directives\ImageDirective;
+
+final class ImageDirectiveTest extends TestCase
+{
+    private ImageDirective $subject;
+    private DocumentNameResolverInterface&MockObject $documentNameResolver;
+    private LoggerInterface&MockObject $logger;
+
+    protected function setUp(): void
+    {
+        $this->documentNameResolver = $this->createMock(DocumentNameResolverInterface::class);
+        $this->documentNameResolver->method('absoluteUrl')->willReturn('/resolved/image.png');
+        $this->logger = $this->createMock(LoggerInterface::class);
+        $this->subject = new ImageDirective($this->documentNameResolver, $this->logger);
+    }
+
+    #[Test]
+    public function getNameReturnsImage(): void
+    {
+        self::assertSame('image', $this->subject->getName());
+    }
+
+    #[Test]
+    public function processRewritesLegacyFloatLeftClass(): void
+    {
+        $directive = new Directive('', 'image', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-left'),
+        ]);
+
+        $this->logger->expects(self::once())
+            ->method('warning')
+            ->with(self::stringContains('deprecated'));
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+        self::assertSame('float-start', $directive->getOption('class')->getValue());
+    }
+
+    #[Test]
+    public function processRewritesLegacyFloatRightClass(): void
+    {
+        $directive = new Directive('', 'image', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-right'),
+        ]);
+
+        $this->logger->expects(self::once())
+            ->method('warning')
+            ->with(self::stringContains('deprecated'));
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+        self::assertSame('float-end', $directive->getOption('class')->getValue());
+    }
+
+    #[Test]
+    public function processRewritesLegacyClassWithOtherClasses(): void
+    {
+        $directive = new Directive('', 'image', 'image.png', [
+            'class' => new DirectiveOption('class', 'with-shadow float-left'),
+        ]);
+
+        $this->logger->expects(self::once())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+        self::assertSame('with-shadow float-start', $directive->getOption('class')->getValue());
+    }
+
+    #[Test]
+    public function processDoesNotRewriteModernClasses(): void
+    {
+        $directive = new Directive('', 'image', 'image.png', [
+            'class' => new DirectiveOption('class', 'float-start'),
+        ]);
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+        self::assertSame('float-start', $directive->getOption('class')->getValue());
+    }
+
+    #[Test]
+    public function processHandlesNoClassOption(): void
+    {
+        $directive = new Directive('', 'image', 'image.png');
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+    }
+
+    #[Test]
+    public function processHandlesNonStringClassValue(): void
+    {
+        $directive = new Directive('', 'image', 'image.png', [
+            'class' => new DirectiveOption('class', true),
+        ]);
+
+        $this->logger->expects(self::never())->method('warning');
+
+        $result = $this->subject->process($this->createBlockContext(), $directive);
+
+        self::assertInstanceOf(ImageNode::class, $result);
+    }
+
+    private function createBlockContext(): BlockContext
+    {
+        $parserContext = $this->createMock(ParserContext::class);
+        $parserContext->method('getCurrentAbsolutePath')->willReturn('/test');
+        $parserContext->method('getLoggerInformation')->willReturn(['rst-file' => 'test.rst']);
+        $parserContext->method('getInitialHeaderLevel')->willReturn(1);
+
+        $documentParserContext = $this->createMock(DocumentParserContext::class);
+        $documentParserContext->method('getContext')->willReturn($parserContext);
+        $documentParserContext->method('getLoggerInformation')->willReturn(['rst-file' => 'test.rst']);
+
+        return new BlockContext($documentParserContext, '', false, 0);
+    }
+}
diff --git a/packages/typo3-docs-theme/tests/unit/Directives/RewritesLegacyFloatClassesTest.php b/packages/typo3-docs-theme/tests/unit/Directives/RewritesLegacyFloatClassesTest.php
new file mode 100644
index 000000000..811b041b5
--- /dev/null
+++ b/packages/typo3-docs-theme/tests/unit/Directives/RewritesLegacyFloatClassesTest.php
@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace T3Docs\Typo3DocsTheme\Tests\Unit\Directives;
+
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\Test;
+use PHPUnit\Framework\TestCase;
+use T3Docs\Typo3DocsTheme\Directives\RewritesLegacyFloatClasses;
+
+final class RewritesLegacyFloatClassesTest extends TestCase
+{
+    private object $subject;
+
+    protected function setUp(): void
+    {
+        // Anonymous class to expose the private trait methods for testing
+        $this->subject = new class () {
+            use RewritesLegacyFloatClasses;
+
+            public function callHasLegacyFloatClass(string $classValue): bool
+            {
+                return $this->hasLegacyFloatClass($classValue);
+            }
+
+            public function callRewriteLegacyFloatClasses(string $classValue): string
+            {
+                return $this->rewriteLegacyFloatClasses($classValue);
+            }
+        };
+    }
+
+    #[Test]
+    #[DataProvider('legacyFloatClassDetectionProvider')]
+    public function hasLegacyFloatClassDetectsCorrectly(string $classValue, bool $expected): void
+    {
+        self::assertSame($expected, $this->subject->callHasLegacyFloatClass($classValue));
+    }
+
+    /** @return \Generator<string, array{string, bool}> */
+    public static function legacyFloatClassDetectionProvider(): \Generator
+    {
+        yield 'float-left' => ['float-left', true];
+        yield 'float-right' => ['float-right', true];
+        yield 'float-left with other classes' => ['with-shadow float-left', true];
+        yield 'float-right with other classes' => ['float-right with-border', true];
+        yield 'both legacy classes' => ['float-left float-right', true];
+        yield 'modern float-start' => ['float-start', false];
+        yield 'modern float-end' => ['float-end', false];
+        yield 'no float classes' => ['with-shadow with-border', false];
+        yield 'empty string' => ['', false];
+        yield 'partial match float-leftover' => ['float-leftover', false];
+        yield 'partial match afloat-right' => ['afloat-right', false];
+    }
+
+    #[Test]
+    #[DataProvider('legacyFloatClassRewriteProvider')]
+    public function rewriteLegacyFloatClassesRewritesCorrectly(string $classValue, string $expected): void
+    {
+        self::assertSame($expected, $this->subject->callRewriteLegacyFloatClasses($classValue));
+    }
+
+    /** @return \Generator<string, array{string, string}> */
+    public static function legacyFloatClassRewriteProvider(): \Generator
+    {
+        yield 'float-left to float-start' => ['float-left', 'float-start'];
+        yield 'float-right to float-end' => ['float-right', 'float-end'];
+        yield 'preserves other classes' => ['with-shadow float-left', 'with-shadow float-start'];
+        yield 'rewrites both' => ['float-left float-right', 'float-start float-end'];
+        yield 'modern classes unchanged' => ['float-start', 'float-start'];
+        yield 'no float classes unchanged' => ['with-shadow', 'with-shadow'];
+        yield 'empty string unchanged' => ['', ''];
+    }
+}
diff --git a/tests/Integration/tests/images/Float/expected/index.html b/tests/Integration/tests/images/Float/expected/index.html
index ae08a9f23..0b06446d9 100644
--- a/tests/Integration/tests/images/Float/expected/index.html
+++ b/tests/Integration/tests/images/Float/expected/index.html
@@ -1,123 +1,386 @@
-        <!-- content start -->
-                <section class="section" id="document-title">
-            <h1>Document Title<a class="headerlink" href="#document-title" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h1>
-            
-    <p>Lorem Ipsum Dolor.</p>
+<!DOCTYPE html>
+<html class="no-js" lang="en">
+<head>
+    <title>Float Tests
+        documentation</title>
+
+    
+<meta charset="utf-8">
+<meta content="width=device-width, initial-scale=1.0" name="viewport">
+<meta content="phpdocumentor/guides" name="generator">
+<meta content="" name="docsearch:name">
+<meta content="" name="docsearch:package_type">
+<meta content="" name="docsearch:release">
+<meta content="" name="docsearch:version">
+<meta content="2023-01-01T12:00:00+00:00" name="docsearch:modified">
+<meta content="2023-01-01T12:00:00+00:00" name="dc.modified">
+<meta content="2023-01-01T12:00:00+00:00" property="article:modified_time">
+    <link href="http://purl.org/dc/elements/1.1/" rel="schema.dc">
+<link href="_resources/css/theme.css" rel="stylesheet">
+<link href="https://docs.typo3.org/search/" rel="search" title="Search">
+<script src="https://cdn.typo3.com/typo3infrastructure/universe/dist/webcomponents-loader.js"></script>
+<script src="https://cdn.typo3.com/typo3infrastructure/universe/dist/typo3-universe.js" type="module"></script>
+                        <link href="#" rel="top" title="Float Tests"/>
+    </head>
+<body>
+<div class="page">
+    <header>
+    <div class="page-topbar">
+        <div class="page-topbar-inner">
+            <typo3-universe active="documentation">
+                <div style="display: block; height: 44px; background-color: #313131;"></div>
+            </typo3-universe>
+        </div>
+    </div>
+    <div class="page-header">
+        <div class="page-header-inner">
+            <div class="d-flex flex-wrap">
+                <div class="logo-wrapper">
+                    <a class="logo" href="https://docs.typo3.org/" title="TYPO3 Documentation">
+                        <img alt="TYPO3 Logo" class="logo-image" src="_resources/img/typo3-logo.svg" width="484" height="130">
+                    </a>
+                </div>
+                <div class="align-self-center order-lg-2 order-last">
+                    
+<div class="toc-header">
+    <div class="toc-title pe-3">
+                            <a class="toc-title-project" href="#">Float Tests</a>
+            </div>
+    </div>                </div>
+                <div class="ms-auto order-lg-3 d-flex">
+                    <div class="menu-search-wrapper">
+                        <button id="toc-toggle" class="btn btn-light d-block d-lg-none" tabindex="0" aria-controls="toc-collapse" aria-expanded="false">
+                            <i class="fas fa-bars"></i> <span class="visually-hidden">Mobile Menu</span>
+                        </button>
+                        <all-documentations-menu data-override-url="_resources/js/menu-proxy.php"></all-documentations-menu>
+                                                <search role="search">
+                            <form action="https://docs.typo3.org/search/search" id="global-search-form" method="get">
+                                <div class="sr-only"><label for="globalsearchinput">TYPO3 documentation...</label></div>
+                                <div class="input-group mb-3 mt-sm-3">
+                                    <select class="form-select search__scope" id="searchscope" name="scope">
+                                        <option value="">Search all</option>
+                                    </select>
+                                    <input autocomplete="off" class="form-control shadow-none" id="globalsearchinput" name="q" placeholder="TYPO3 documentation..." type="text" value="">
+                                    <button class="btn btn-light" type="submit"><i class="fa fa-search"></i>&nbsp;<span class="d-none d-md-inline">Search</span></button>
+                                </div>
+                            </form>
+                            <div id="global-search-root"></div>
+                        </search>
+                        <div class="position-relative d-inline-block">
+                            <button id="options-toggle" class="btn btn-light d-block" type="button" aria-expanded="false">
+                                <i class="fas fa-cog"></i> <span class="visually-hidden">Options</span>
+                            </button>
 
-            <section class="section" id="figure-align-left">
-            <h2>Figure align left<a class="headerlink" href="#figure-align-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="float-left">
+                            <div id="options-panel"
+                                 class="shadow p-3"
+                                 role="menu"
+                                 aria-hidden="true">
+                                <h6 class="dropdown-header text-muted text-uppercase small mb-2">Options</h6>
+
+                                                                                                            <a class="dropdown-item d-flex align-items-center gap-2" href="_sources/index.rst.txt" rel="nofollow noopener" target="_blank">
+        <i class="fas fa-code"></i>
+        View source
+    </a>
+    <a class="dropdown-item d-flex align-items-center gap-2" href="https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/WritingDocsOfficial/GithubMethod.html" id="btnHowToEdit" rel="nofollow noopener" target="_blank">
+        <i class="fas fa-info-circle"></i>
+        How to edit
+    </a>
+                                                                                                                <a class="dropdown-item d-flex align-items-center gap-2" href="singlehtml/Index.html" target="_blank" rel="noopener">
+                                            <i class="fas fa-print"></i>
+                                            Full documentation (single file)
+                                        </a>
+                                                                                                </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+</header>    <main class="page-main">
+        <div class="page-main-inner">
+            <div class="page-main-navigation">
+                <nav>
+
+                    <div id="toc-collapse">
+                                                <div aria-label="main navigation" class="toc"
+                             role="navigation">
+                                <all-documentations-menu-mobile
+        data-override-url="_resources/js/menu-proxy.php"></all-documentations-menu-mobile>
+    <div aria-label="Main navigation" class="main_menu" role="navigation">
+                <p class="caption">Float Tests</p>
+        
+    </div>
+                        </div>
+                    </div>
+                </nav>
+            </div>
+            <div class="page-main-content">
+                <div class="rst-content">                        <nav aria-label="breadcrumbs navigation" class="breadcrumb-bar" role="navigation">
+        
+<ol class="breadcrumb">
+                <li aria-current="page"  class="breadcrumb-item  active">Float Tests</li>
+        </ol>
+        <div class="breadcrumb-additions"></div>
+    </nav>
+                    
+<article class="document" itemscope="itemscope" itemtype="http://schema.org/Article" role="main">
+    <div itemprop="articleBody">
+        <!-- content start -->
+                <section class="section" id="float-tests">
+            <h1>Float Tests<a class="headerlink" href="#float-tests" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h1>
+            <section class="section" id="align-left">
+            <h2>Align Left<a class="headerlink" href="#align-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-start">
     <img
     src="typo3-logo.png"
-            alt="Left aligned figure"        />
+            alt="Left figure"        />
 
             
                     <figcaption>
-    <p>Caption for left-aligned figure</p>
+    <p>Left aligned figure</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="figure-align-right">
-            <h2>Figure align right<a class="headerlink" href="#figure-align-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="float-right">
+            <section class="section" id="align-right">
+            <h2>Align Right<a class="headerlink" href="#align-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-end">
     <img
     src="typo3-logo.png"
-            alt="Right aligned figure"        />
+            alt="Right figure"        />
 
             
                     <figcaption>
-    <p>Caption for right-aligned figure</p>
+    <p>Right aligned figure</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="figure-align-center">
-            <h2>Figure align center<a class="headerlink" href="#figure-align-center" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <section class="section" id="align-center">
+            <h2>Align Center<a class="headerlink" href="#align-center" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
             <figure class="align-center">
     <img
     src="typo3-logo.png"
-            alt="Center aligned figure"        />
+            alt="Center figure"        />
 
             
                     <figcaption>
-    <p>Caption for center-aligned figure</p>
+    <p>Center aligned figure</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="image-align-left">
-            <h2>Image align left<a class="headerlink" href="#image-align-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <img
+            <section class="section" id="legacy-figure-class">
+            <h2>Legacy Figure Class<a class="headerlink" href="#legacy-figure-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-start">
+    <img
     src="typo3-logo.png"
-            alt="Left aligned image"        class="float-left"/>
+            alt="Legacy float-left figure"        />
+
+            
+                    <figcaption>
+    <p>Should rewrite to float-start</p>
+</figcaption>
+            </figure>
     </section>
-            <section class="section" id="image-align-right">
-            <h2>Image align right<a class="headerlink" href="#image-align-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <section class="section" id="legacy-figure-right">
+            <h2>Legacy Figure Right<a class="headerlink" href="#legacy-figure-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-end">
+    <img
+    src="typo3-logo.png"
+            alt="Legacy float-right figure"        />
+
+            
+                    <figcaption>
+    <p>Should rewrite to float-end</p>
+</figcaption>
+            </figure>
+    </section>
+            <section class="section" id="legacy-image-left">
+            <h2>Legacy Image Left<a class="headerlink" href="#legacy-image-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
             <img
     src="typo3-logo.png"
-            alt="Right aligned image"        class="float-right"/>
+            alt="Legacy float-left image"        class="float-start"/>
     </section>
-            <section class="section" id="image-align-center">
-            <h2>Image align center<a class="headerlink" href="#image-align-center" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <section class="section" id="legacy-image-right">
+            <h2>Legacy Image Right<a class="headerlink" href="#legacy-image-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
             <img
     src="typo3-logo.png"
-            alt="Center aligned image"        class="align-center"/>
+            alt="Legacy float-right image"        class="float-end"/>
     </section>
-            <section class="section" id="figure-with-float-class">
-            <h2>Figure with float class<a class="headerlink" href="#figure-with-float-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="float-left">
+            <section class="section" id="mixed-legacy-with-extra-class">
+            <h2>Mixed Legacy With Extra Class<a class="headerlink" href="#mixed-legacy-with-extra-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-start with-shadow">
     <img
     src="typo3-logo.png"
-            alt="Figure with float-left class"        />
+            alt="Mixed class figure"        />
 
             
                     <figcaption>
-    <p>Float class on figure</p>
+    <p>Should rewrite float-left but keep with-shadow</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="figure-with-float-right-class">
-            <h2>Figure with float-right class<a class="headerlink" href="#figure-with-float-right-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="float-right">
+            <section class="section" id="align-plus-legacy-class">
+            <h2>Align Plus Legacy Class<a class="headerlink" href="#align-plus-legacy-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-start">
     <img
     src="typo3-logo.png"
-            alt="Figure with float-right class"        />
+            alt="Both align and legacy class"        />
 
             
                     <figcaption>
-    <p>Float-right class on figure</p>
+    <p>Should use align, class gets rewritten to float-start</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="figure-with-float-class-and-extra-classes">
-            <h2>Figure with float class and extra classes<a class="headerlink" href="#figure-with-float-class-and-extra-classes" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="float-left with-shadow">
+            <section class="section" id="image-align-left">
+            <h2>Image Align Left<a class="headerlink" href="#image-align-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <img
+    src="typo3-logo.png"
+            alt="Image align left"        class="float-start"/>
+    </section>
+            <section class="section" id="image-align-right">
+            <h2>Image Align Right<a class="headerlink" href="#image-align-right" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <img
+    src="typo3-logo.png"
+            alt="Image align right"        class="float-end"/>
+    </section>
+            <section class="section" id="modern-float-start-no-warning">
+            <h2>Modern Float Start (No Warning)<a class="headerlink" href="#modern-float-start-no-warning" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <figure class="float-start">
     <img
     src="typo3-logo.png"
-            alt="Figure with float and shadow"        />
+            alt="Modern float-start figure"        />
 
             
                     <figcaption>
-    <p>Float class combined with other classes</p>
+    <p>Already uses modern class, no rewriting needed</p>
 </figcaption>
             </figure>
     </section>
-            <section class="section" id="image-with-float-class">
-            <h2>Image with float class<a class="headerlink" href="#image-with-float-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            <section class="section" id="modern-float-end-image-no-warning">
+            <h2>Modern Float End Image (No Warning)<a class="headerlink" href="#modern-float-end-image-no-warning" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
             <img
     src="typo3-logo.png"
-            alt="Image with float-right class"        class="float-right"/>
+            alt="Modern float-end image"        class="float-end"/>
     </section>
-            <section class="section" id="figure-with-align-and-extra-class">
-            <h2>Figure with align and extra class<a class="headerlink" href="#figure-with-align-and-extra-class" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
-            <figure class="with-border float-left">
-    <img
+            <section class="section" id="substitution-image-left">
+            <h2>Substitution Image Left<a class="headerlink" href="#substitution-image-left" data-bs-toggle="modal" data-bs-target="#linkReferenceModal"  title="Reference this headline">&nbsp;<i class="fa-solid fa-link"></i></a></h2>
+            
+    <p>Use the <img
     src="typo3-logo.png"
-            alt="Figure with align and border"        />
+            alt="Substitution logo"        class="float-start"/> inline text here.</p>
 
-            
-                    <figcaption>
-    <p>Align option combined with extra class</p>
-</figcaption>
-            </figure>
     </section>
     </section>
         <!-- content end -->
+    </div>
+</article>
+                        
+                    </div>
+            </div>
+        </div>
+    </main>
+
+    <div class="modal fade" id="linkReferenceModal" tabindex="-1" aria-labelledby="linkReferenceModalLabel"
+    aria-hidden="true" data-current-filename="index">
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title" id="linkReferenceModalLabel">Reference to the headline</h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body">
+                <div class="alert alert-success d-none" id="permalink-alert-success" role="alert"></div>
+                <div class="mb-3">
+                    <div class="permalink-short-wrapper">
+                        <label for="permalink-short" class="col-form-label">Permalink (Shortlink)</label>
+                        <div class="input-group">
+                            <input class="form-control code" id="permalink-short" readonly>
+                            <button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-short"><i class="far fa-clone"></i></button>
+                        </div>
+                        <p><em>Copy and freely share the link</em></p>
+                    </div>
+                    <label for="permalink-uri" class="col-form-label">URL</label>
+                    <div class="input-group">
+                        <input class="form-control code" id="permalink-uri" readonly>
+                        <button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-uri"><i class="far fa-clone"></i></button>
+                    </div>
+                </div>
+                <div class="mb-3">
+                    <div class="alert alert-warning alert-permalink-rst" role="alert">This link target has no permanent anchor assigned.The link below can be used, but is prone to change if the page gets moved.
+                    </div>
+                    <label for="permalink-rst" class="col-form-label">Link in reStructuredText (reST)</label>
+                    <div class="input-group">
+                        <textarea class="form-control code" id="permalink-rst" readonly></textarea>
+                        <button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-rst"><i class="far fa-clone"></i></button>
+                    </div>
+                    <p><em>Copy this link into your TYPO3 manual.</em></p>
+                </div>
+                <div class="mb-3">
+                    <label for="permalink-md" class="col-form-label">Link in Markdown</label>
+                    <div class="input-group">
+                        <textarea class="form-control code" id="permalink-md" readonly></textarea>
+                        <button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-md"><i class="far fa-clone"></i></button>
+                    </div>
+                </div>
+                <div class="mb-3">
+                    <label for="permalink-html" class="col-form-label">Link in HTML</label>
+                                        <div class="input-group">
+                        <textarea class="form-control code" id="permalink-html" readonly></textarea>
+                        <button type="button" class="btn btn-outline-secondary copy-button" data-target="permalink-html"><i class="far fa-clone"></i></button>
+                    </div>
+                </div>
+            </div>
+            <div class="modal-footer">
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal">Close</button>
+            </div>
+        </div>
+    </div>
+</div>    <div class="modal fade" id="generalModal" tabindex="-1" aria-labelledby="linkReferenceModalLabel"
+    aria-hidden="true" data-current-filename="index"
+>
+    <div class="modal-dialog">
+        <div class="modal-content">
+            <div class="modal-header">
+                <h5 class="modal-title" id="generalModalLabel"></h5>
+                <button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
+            </div>
+            <div class="modal-body">
+                <div class="alert alert-success d-none" id="general-alert-success" role="alert"></div>
+                <div id="generalModalContent">
+                </div>
+            </div>
+            <div class="modal-footer justify-content-between">
+                <div id="generalModalCustomButtons"></div>
+                <button type="button" class="btn btn-secondary" data-bs-dismiss="modal"><i class="fa-regular fa-circle-xmark"></i>&nbsp;Close</button>
+            </div>
+        </div>
+    </div>
+</div></div>
+
+
+<footer class="page-footer">
+    <div class="frame frame-ruler-before frame-background-dark">
+        <div class="frame-container">
+            <div class="frame-inner">
+                                <div class="footer-additional">
+                    <p class="text-center">Last rendered: Jan 01, 2023 12:00</p>
+                </div>
+                <div class="footer-meta">
+                    <ul class="footer-meta-navigation">
+                        <li><a href="https://typo3.org/legal-notice" rel="nofollow" target="_blank" title="Legal Notice">Legal Notice</a></li>
+                        <li><a href="https://typo3.org/privacy-policy" rel="nofollow" target="_blank" title="Privacy Policy">Privacy Policy</a></li>
+                    </ul>
+                </div>
+            </div>
+        </div>
+    </div>
+</footer>
+<script src="_resources/js/popper.min.js"></script>
+<script src="_resources/js/bootstrap.min.js"></script>
+<script src="_resources/js/theme.min.js"></script>
+
+<!--
+ Locally rendered. No tracking embedded.
+-->
+</body>
+</html>
\ No newline at end of file
diff --git a/tests/Integration/tests/images/Float/expected/logs/warning.log b/tests/Integration/tests/images/Float/expected/logs/warning.log
new file mode 100644
index 000000000..c4f786621
--- /dev/null
+++ b/tests/Integration/tests/images/Float/expected/logs/warning.log
@@ -0,0 +1,7 @@
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead. {"rst-file":"index.rst","currentLineNumber":40} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead. {"rst-file":"index.rst","currentLineNumber":49} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead, or `float-start` / `float-end` for substitution images. {"rst-file":"index.rst","currentLineNumber":55,"currentLine":""} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead, or `float-start` / `float-end` for substitution images. {"rst-file":"index.rst","currentLineNumber":62,"currentLine":""} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead. {"rst-file":"index.rst","currentLineNumber":72} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead. {"rst-file":"index.rst","currentLineNumber":82} []
+app.WARNING: Using `:class: float-left` / `:class: float-right` is deprecated. Use `:align: left` / `:align: right` instead, or `float-start` / `float-end` for substitution images. {"rst-file":"index.rst","currentLineNumber":118,"currentLine":""} []
diff --git a/tests/Integration/tests/images/Float/input/index.rst b/tests/Integration/tests/images/Float/input/index.rst
index 6a8a4d3c6..e13080d46 100644
--- a/tests/Integration/tests/images/Float/input/index.rst
+++ b/tests/Integration/tests/images/Float/input/index.rst
@@ -1,97 +1,120 @@
-==============
-Document Title
-==============
+===========
+Float Tests
+===========
 
-Lorem Ipsum Dolor.
+Align Left
+==========
 
-Figure align left
-=================
+.. figure:: /typo3-logo.png
+   :alt: Left figure
+   :align: left
 
-..  figure:: /typo3-logo.png
-    :alt: Left aligned figure
-    :align: left
+   Left aligned figure
 
-    Caption for left-aligned figure
+Align Right
+===========
 
-Figure align right
-==================
+.. figure:: /typo3-logo.png
+   :alt: Right figure
+   :align: right
+
+   Right aligned figure
 
-..  figure:: /typo3-logo.png
-    :alt: Right aligned figure
-    :align: right
+Align Center
+============
 
-    Caption for right-aligned figure
+.. figure:: /typo3-logo.png
+   :alt: Center figure
+   :align: center
 
-Figure align center
+   Center aligned figure
+
+Legacy Figure Class
 ===================
 
-..  figure:: /typo3-logo.png
-    :alt: Center aligned figure
-    :align: center
+.. figure:: /typo3-logo.png
+   :alt: Legacy float-left figure
+   :class: float-left
 
-    Caption for center-aligned figure
+   Should rewrite to float-start
 
-Image align left
-================
+Legacy Figure Right
+====================
+
+.. figure:: /typo3-logo.png
+   :alt: Legacy float-right figure
+   :class: float-right
 
-..  image:: /typo3-logo.png
-    :alt: Left aligned image
-    :align: left
+   Should rewrite to float-end
 
-Image align right
+Legacy Image Left
 =================
 
-..  image:: /typo3-logo.png
-    :alt: Right aligned image
-    :align: right
+.. image:: /typo3-logo.png
+   :alt: Legacy float-left image
+   :class: float-left
 
-Image align center
+Legacy Image Right
 ==================
 
-..  image:: /typo3-logo.png
-    :alt: Center aligned image
-    :align: center
+.. image:: /typo3-logo.png
+   :alt: Legacy float-right image
+   :class: float-right
 
-Figure with float class
-=======================
+Mixed Legacy With Extra Class
+==============================
 
-..  figure:: /typo3-logo.png
-    :alt: Figure with float-left class
-    :class: float-left
+.. figure:: /typo3-logo.png
+   :alt: Mixed class figure
+   :class: float-left with-shadow
 
-    Float class on figure
+   Should rewrite float-left but keep with-shadow
 
-Figure with float-right class
-=============================
+Align Plus Legacy Class
+========================
 
-..  figure:: /typo3-logo.png
-    :alt: Figure with float-right class
-    :class: float-right
+.. figure:: /typo3-logo.png
+   :alt: Both align and legacy class
+   :align: left
+   :class: float-left
+
+   Should use align, class gets rewritten to float-start
+
+Image Align Left
+================
+
+.. image:: /typo3-logo.png
+   :alt: Image align left
+   :align: left
+
+Image Align Right
+=================
 
-    Float-right class on figure
+.. image:: /typo3-logo.png
+   :alt: Image align right
+   :align: right
 
-Figure with float class and extra classes
-=========================================
+Modern Float Start (No Warning)
+================================
 
-..  figure:: /typo3-logo.png
-    :alt: Figure with float and shadow
-    :class: float-left with-shadow
+.. figure:: /typo3-logo.png
+   :alt: Modern float-start figure
+   :class: float-start
 
-    Float class combined with other classes
+   Already uses modern class, no rewriting needed
 
-Image with float class
-======================
+Modern Float End Image (No Warning)
+=====================================
 
-..  image:: /typo3-logo.png
-    :alt: Image with float-right class
-    :class: float-right
+.. image:: /typo3-logo.png
+   :alt: Modern float-end image
+   :class: float-end
 
-Figure with align and extra class
-=================================
+Substitution Image Left
+========================
 
-..  figure:: /typo3-logo.png
-    :alt: Figure with align and border
-    :align: left
-    :class: with-border
+.. |sub-logo| image:: /typo3-logo.png
+   :alt: Substitution logo
+   :class: float-left
 
-    Align option combined with extra class
+Use the |sub-logo| inline text here.
diff --git a/tests/Integration/tests/site-set-failure/expected/logs/error.log b/tests/Integration/tests/site-set-failure/expected/logs/error.log
index 03f8548ca..2cff43b58 100644
--- a/tests/Integration/tests/site-set-failure/expected/logs/error.log
+++ b/tests/Integration/tests/site-set-failure/expected/logs/error.log
@@ -1 +1 @@
-app.ERROR: Error while processing "typo3:site-set-settings" directive in "index": Path is outside of the defined root, path: [/../../../tests/Integration/tests/site-set/input/_includes/Sets/FluidStyledContent/settings.definitions.yaml] {"rst-file":"index.rst","currentLineNumber":1} []
+app.ERROR: Error while processing "typo3:site-set-settings" directive in "index": Path traversal detected: /../../../tests/Integration/tests/site-set/input/_includes/Sets/FluidStyledContent/settings.definitions.yaml {"rst-file":"index.rst","currentLineNumber":1} []
diff --git a/tests/Integration/tests/site-set-failure/expected/logs/warning.log b/tests/Integration/tests/site-set-failure/expected/logs/warning.log
index 03f8548ca..2cff43b58 100644
--- a/tests/Integration/tests/site-set-failure/expected/logs/warning.log
+++ b/tests/Integration/tests/site-set-failure/expected/logs/warning.log
@@ -1 +1 @@
-app.ERROR: Error while processing "typo3:site-set-settings" directive in "index": Path is outside of the defined root, path: [/../../../tests/Integration/tests/site-set/input/_includes/Sets/FluidStyledContent/settings.definitions.yaml] {"rst-file":"index.rst","currentLineNumber":1} []
+app.ERROR: Error while processing "typo3:site-set-settings" directive in "index": Path traversal detected: /../../../tests/Integration/tests/site-set/input/_includes/Sets/FluidStyledContent/settings.definitions.yaml {"rst-file":"index.rst","currentLineNumber":1} []