From 7f47972494d1a9eaa9591d7ff2c588d394019aed Mon Sep 17 00:00:00 2001
From: Lotfi Habbiche <lotfi.habbiche@capgemini.com>
Date: Tue, 25 Aug 2026 16:07:16 +0200
Subject: [PATCH 1/3] feat: add <ContentMedia /> component (img, svg, iframe,
 video, audio)

---
 src/ContentMedia.tsx               | 192 ++++++++++++++++++++++++++++
 stories/ContentMedia.stories.tsx   | 193 +++++++++++++++++++++++++++++
 test/integration/vite/src/Home.tsx |  77 +++++++++++-
 3 files changed, 460 insertions(+), 2 deletions(-)
 create mode 100644 src/ContentMedia.tsx
 create mode 100644 stories/ContentMedia.stories.tsx

diff --git a/src/ContentMedia.tsx b/src/ContentMedia.tsx
new file mode 100644
index 000000000..d4d057299
--- /dev/null
+++ b/src/ContentMedia.tsx
@@ -0,0 +1,192 @@
+"use client";
+
+import React, { memo, forwardRef, type CSSProperties, type ReactNode } from "react";
+import { symToStr } from "tsafe/symToStr";
+import { fr } from "./fr";
+import { cx } from "./tools/cx";
+import { getLink, type RegisteredLinkProps } from "./link";
+import { useAnalyticsId } from "./tools/useAnalyticsId";
+
+export type ContentMediaProps = {
+    id?: string;
+    className?: string;
+    style?: CSSProperties;
+    classes?: Partial<Record<"root" | "img" | "caption", string>>;
+    /**
+     * aria-label for the `<figure>` element.
+     * Defaults to the `caption` prop when it is a plain string.
+     * Required for image and SVG media types when caption is not a string.
+     */
+    label?: string;
+    /** Caption text shown below the media (description / source). */
+    caption?: ReactNode;
+    /** Text of the optional link inside the figcaption. */
+    captionLinkLabel?: ReactNode;
+    /** Props of the optional link inside the figcaption. */
+    captionLinkProps?: RegisteredLinkProps;
+} & ContentMediaProps.Media;
+
+export namespace ContentMediaProps {
+    /** Image (`<img>`) media. */
+    export type ImageMedia = {
+        type: "img";
+        /**
+         * Props forwarded to the `<img>` element.
+         * `src` and `alt` are required — `alt` can be an empty string when
+         * the image is purely decorative.
+         */
+        imgProps: React.ImgHTMLAttributes<HTMLImageElement> & {
+            src: string;
+            /** Empty string is allowed for decorative images. */
+            alt: string;
+        };
+    };
+
+    /** SVG media — pass your `<svg>` element as the `svg` prop. */
+    export type SvgMedia = {
+        type: "svg";
+        /**
+         * The `<svg>` element to render.
+         * • Decorative SVGs should carry `aria-hidden="true"`.
+         * • Meaningful SVGs should carry `role="img"` and an `aria-label`.
+         */
+        svg: ReactNode;
+    };
+
+    /** Embedded video via `<iframe>` (e.g. YouTube). */
+    export type IframeMedia = {
+        type: "iframe";
+        /**
+         * Props forwarded to the `<iframe>` element.
+         * `src` and `title` are required — `title` is the video's text alternative.
+         */
+        iframeProps: React.IframeHTMLAttributes<HTMLIFrameElement> & {
+            src: string;
+            /** Text alternative / accessibility title of the embedded video. */
+            title: string;
+        };
+    };
+
+    /** Native HTML5 `<video>`. */
+    export type VideoMedia = {
+        type: "video";
+        /**
+         * Text alternative for users who cannot view the video.
+         * Displayed inside a `<p>` within the `<video>` element.
+         */
+        alternative?: string;
+        /** Props forwarded to the `<video>` element. `controls` is always set. */
+        videoProps: React.VideoHTMLAttributes<HTMLVideoElement> & { src: string };
+    };
+
+    /** Native HTML5 `<audio>`. */
+    export type AudioMedia = {
+        type: "audio";
+        /**
+         * Text alternative for users who cannot hear the audio.
+         * Displayed inside a `<p>` within the `<audio>` element.
+         */
+        alternative?: string;
+        /** Props forwarded to the `<audio>` element. `controls` is always set. */
+        audioProps: React.AudioHTMLAttributes<HTMLAudioElement> & { src: string };
+    };
+
+    export type Media = ImageMedia | SvgMedia | IframeMedia | VideoMedia | AudioMedia;
+}
+
+/** @see <https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenu-medias> */
+export const ContentMedia = memo(
+    forwardRef<HTMLElement, ContentMediaProps>((props, ref) => {
+        const {
+            id: id_props,
+            className,
+            style,
+            classes = {},
+            label,
+            caption,
+            captionLinkLabel,
+            captionLinkProps
+        } = props;
+
+        const id = useAnalyticsId({
+            "defaultIdPrefix": "fr-content-media",
+            "explicitlyProvidedId": id_props
+        });
+
+        const { Link } = getLink();
+
+        const ariaLabel = label ?? (typeof caption === "string" ? caption : undefined);
+
+        const renderMedia = () => {
+            switch (props.type) {
+                case "img":
+                    return (
+                        <div className={cx(fr.cx("fr-content-media__img"), classes.img)}>
+                            <img
+                                {...props.imgProps}
+                                className={cx(fr.cx("fr-responsive-img"), props.imgProps.className)}
+                            />
+                        </div>
+                    );
+                case "svg":
+                    return <>{props.svg}</>;
+                case "iframe":
+                    return (
+                        <iframe
+                            {...props.iframeProps}
+                            className={cx(fr.cx("fr-responsive-vid"), props.iframeProps.className)}
+                        />
+                    );
+                case "video":
+                    return (
+                        <video
+                            {...props.videoProps}
+                            controls
+                            className={cx(fr.cx("fr-responsive-vid"), props.videoProps.className)}
+                        >
+                            {props.alternative !== undefined && <p>{props.alternative}</p>}
+                        </video>
+                    );
+                case "audio":
+                    return (
+                        <audio
+                            {...props.audioProps}
+                            controls
+                            className={cx(fr.cx("fr-responsive-vid"), props.audioProps.className)}
+                        >
+                            {props.alternative !== undefined && <p>{props.alternative}</p>}
+                        </audio>
+                    );
+            }
+        };
+
+        const hasCaption = caption !== undefined || captionLinkProps !== undefined;
+
+        return (
+            <figure
+                id={id}
+                role="group"
+                className={cx(fr.cx("fr-content-media"), classes.root, className)}
+                style={style}
+                {...(ariaLabel !== undefined ? { "aria-label": ariaLabel } : {})}
+                ref={ref}
+            >
+                {renderMedia()}
+                {hasCaption && (
+                    <figcaption className={cx(fr.cx("fr-content-media__caption"), classes.caption)}>
+                        {caption}
+                        {captionLinkProps !== undefined && (
+                            <Link {...captionLinkProps} className={fr.cx("fr-link")}>
+                                {captionLinkLabel}
+                            </Link>
+                        )}
+                    </figcaption>
+                )}
+            </figure>
+        );
+    })
+);
+
+ContentMedia.displayName = symToStr({ ContentMedia });
+
+export default ContentMedia;
diff --git a/stories/ContentMedia.stories.tsx b/stories/ContentMedia.stories.tsx
new file mode 100644
index 000000000..77221be30
--- /dev/null
+++ b/stories/ContentMedia.stories.tsx
@@ -0,0 +1,193 @@
+import { ContentMedia, type ContentMediaProps } from "../dist/ContentMedia";
+import { sectionName } from "./sectionName";
+import { getStoryFactory } from "./getStory";
+import { assert } from "tsafe/assert";
+import type { Equals } from "tsafe";
+
+const { meta, getStory } = getStoryFactory({
+    sectionName,
+    "wrappedComponent": { ContentMedia },
+    "description": `
+- [See DSFR documentation](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenu-medias)
+- [See source code](https://github.com/codegouvfr/react-dsfr/blob/main/src/ContentMedia.tsx)
+
+Supports **image**, **SVG**, **iframe**, **video** and **audio** media types  
+via the \`type\` discriminator prop.
+
+\`\`\`tsx
+import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
+
+// Image
+<ContentMedia
+    type="img"
+    label="Description / Source"
+    imgProps={{ src: "image.png", alt: "Description de l'image" }}
+    caption="Description / Source"
+    captionLinkLabel="Libellé lien"
+    captionLinkProps={{
+        href: "https://www.systeme-de-design.gouv.fr",
+        target: "_blank",
+        rel: "noopener noreferrer"
+    }}
+/>
+
+// Iframe vidéo (YouTube, etc.)
+<ContentMedia
+    type="iframe"
+    iframeProps={{
+        src: "https://www.youtube.com/embed/HyirpmPL43I",
+        title: "Vidéo de présentation - voir transcription ci-dessous",
+        allow: "accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",
+        allowFullScreen: true
+    }}
+    caption="Description / Source"
+    captionLinkLabel="Libellé lien"
+    captionLinkProps={{
+        href: "https://www.youtube.com/watch?v=HyirpmPL43I",
+        target: "_blank",
+        rel: "noopener noreferrer"
+    }}
+/>
+
+// Vidéo native
+<ContentMedia
+    type="video"
+    alternative="Alternative de la vidéo - voir transcription ci-dessous"
+    videoProps={{ src: "video.mp4" }}
+    caption="Description / Source"
+    captionLinkLabel="Libellé lien"
+    captionLinkProps={{
+        href: "https://www.w3schools.com/html/html5_video.asp",
+        target: "_blank",
+        rel: "noopener noreferrer"
+    }}
+/>
+
+// Audio natif
+<ContentMedia
+    type="audio"
+    alternative="Alternative de l'audio - voir transcription ci-dessous"
+    audioProps={{ src: "audio.mp3" }}
+    caption="Description / Source"
+    captionLinkLabel="Libellé lien"
+    captionLinkProps={{
+        href: "https://www.w3schools.com/html/html5_audio.asp",
+        target: "_blank",
+        rel: "noopener noreferrer"
+    }}
+/>
+\`\`\`
+`,
+    "argTypes": {
+        "type": {
+            "options": (() => {
+                const types = ["img", "svg", "iframe", "video", "audio"] as const;
+                assert<Equals<typeof types[number], ContentMediaProps.Media["type"]>>();
+                return types;
+            })(),
+            "control": { "type": "radio" }
+        },
+        "label": {
+            "description":
+                "`aria-label` of the `<figure>` element. Defaults to `caption` when it is a plain string."
+        },
+        "caption": {
+            "description": "Caption / source text shown in the `<figcaption>`."
+        },
+        "captionLinkLabel": {
+            "description": "Label of the link inside the `<figcaption>`."
+        },
+        "captionLinkProps": {
+            "description": "Props of the link inside the `<figcaption>`.",
+            "control": { "type": null }
+        }
+    },
+    "disabledProps": ["lang"]
+});
+
+export default meta;
+
+export const Image = getStory({
+    "type": "img",
+    "label": "Description / Source",
+    "imgProps": {
+        "src": "https://www.systeme-de-design.gouv.fr/img/placeholder.16x9.png",
+        "alt": "Description de l'image (texte alternatif)"
+    },
+    "caption": "Description / Source",
+    "captionLinkLabel": "Libellé lien",
+    "captionLinkProps": {
+        "href": "https://www.systeme-de-design.gouv.fr",
+        "target": "_blank",
+        "rel": "noopener noreferrer"
+    }
+});
+
+export const IframeVideo = getStory(
+    {
+        "type": "iframe",
+        "iframeProps": {
+            "src": "https://www.youtube.com/embed/HyirpmPL43I",
+            "title":
+                "Vidéo de présentation du Service National Universel - voir transcription ci-dessous",
+            "allow": "accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",
+            "allowFullScreen": true
+        },
+        "caption": "Description / Source",
+        "captionLinkLabel": "Libellé lien",
+        "captionLinkProps": {
+            "href": "https://www.youtube.com/watch?v=HyirpmPL43I",
+            "target": "_blank",
+            "rel": "noopener noreferrer"
+        }
+    },
+    { "description": "Vidéo intégrée via `<iframe>` (ex : YouTube)." }
+);
+
+export const VideoNative = getStory(
+    {
+        "type": "video",
+        "alternative": "Alternative de la vidéo - voir transcription ci-dessous",
+        "videoProps": {
+            "src": "https://www.w3schools.com/html/mov_bbb.mp4"
+        },
+        "caption": "Description / Source",
+        "captionLinkLabel": "Libellé lien",
+        "captionLinkProps": {
+            "href": "https://www.w3schools.com/html/html5_video.asp",
+            "target": "_blank",
+            "rel": "noopener noreferrer"
+        }
+    },
+    { "description": "Vidéo native HTML5 avec `<video>`." }
+);
+
+export const AudioNative = getStory(
+    {
+        "type": "audio",
+        "alternative": "Alternative de l'audio - voir transcription ci-dessous",
+        "audioProps": {
+            "src": "https://www.w3schools.com/html/horse.mp3"
+        },
+        "caption": "Description / Source",
+        "captionLinkLabel": "Libellé lien",
+        "captionLinkProps": {
+            "href": "https://www.w3schools.com/html/html5_audio.asp",
+            "target": "_blank",
+            "rel": "noopener noreferrer"
+        }
+    },
+    { "description": "Fichier audio natif HTML5 avec `<audio>`." }
+);
+
+export const ImageWithoutCaption = getStory(
+    {
+        "type": "img",
+        "label": "Image illustrative",
+        "imgProps": {
+            "src": "https://www.systeme-de-design.gouv.fr/img/placeholder.16x9.png",
+            "alt": ""
+        }
+    },
+    { "description": 'Image décorative (`alt=""`) sans légende.' }
+);
diff --git a/test/integration/vite/src/Home.tsx b/test/integration/vite/src/Home.tsx
index a74746c06..8cafbd5ca 100644
--- a/test/integration/vite/src/Home.tsx
+++ b/test/integration/vite/src/Home.tsx
@@ -13,6 +13,7 @@ import { Table } from "@codegouvfr/react-dsfr/Table";
 import { Tile } from "@codegouvfr/react-dsfr/Tile";
 
 import { Accordion } from "@codegouvfr/react-dsfr/Accordion";
+import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
 import { Book, Money, Police, Sun, LocationFrance } from '@codegouvfr/react-dsfr/picto';
 import CityHall from './assets/city-hall.svg';
 
@@ -84,6 +85,9 @@ export function Home() {
             <div className={fr.cx("fr-my-4w")}>
                 <HighlightExample />
             </div>
+            <div className={fr.cx("fr-my-4w")}>
+                <ContentMediaExamples />
+            </div>
         </>
     );
 }
@@ -260,8 +264,77 @@ function ControlledAccordion() {
 function HighlightExample() {
     return (
         <Highlight
-            children={`Les parents d’enfants de 11 à 14 ans n’ont aucune démarche à accomplir : les CAF versent automatiquement l’ARS aux familles déjà allocataires qui remplissent les conditions.`}
+            children={`Les parents d'enfants de 11 à 14 ans n'ont aucune démarche à accomplir : les CAF versent automatiquement l'ARS aux familles déjà allocataires qui remplissent les conditions.`}
             bodyAs="p"
         />
     )
-}
\ No newline at end of file
+}
+
+function ContentMediaExamples() {
+    return (
+        <>
+            <h2>ContentMedia — Image</h2>
+            <ContentMedia
+                type="img"
+                label="Exemple d'image responsive"
+                imgProps={{
+                    src: "https://www.w3schools.com/css/img_5terre.jpg",
+                    alt: "Paysage de Cinque Terre en Italie"
+                }}
+                caption="© W3Schools – Cinque Terre, Italie"
+                captionLinkLabel="Voir la source"
+                captionLinkProps={{
+                    href: "https://www.w3schools.com",
+                    target: "_blank",
+                    rel: "noopener noreferrer"
+                }}
+            />
+
+            <h2 className={fr.cx("fr-mt-4w")}>ContentMedia — Iframe (YouTube)</h2>
+            <ContentMedia
+                type="iframe"
+                iframeProps={{
+                    src: "https://www.youtube.com/embed/HyirpmPL43I",
+                    title: "Vidéo de présentation du Service National Universel – voir transcription ci-dessous",
+                    allow: "accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture",
+                    allowFullScreen: true
+                }}
+                caption="Service National Universel – présentation officielle"
+                captionLinkLabel="Voir sur YouTube"
+                captionLinkProps={{
+                    href: "https://www.youtube.com/watch?v=HyirpmPL43I",
+                    target: "_blank",
+                    rel: "noopener noreferrer"
+                }}
+            />
+
+            <h2 className={fr.cx("fr-mt-4w")}>ContentMedia — Vidéo native</h2>
+            <ContentMedia
+                type="video"
+                alternative="Vidéo de démonstration Big Buck Bunny – voir transcription ci-dessous"
+                videoProps={{ src: "https://www.w3schools.com/html/mov_bbb.mp4" }}
+                caption="Big Buck Bunny – Blender Foundation"
+                captionLinkLabel="Voir la source"
+                captionLinkProps={{
+                    href: "https://www.w3schools.com/html/html5_video.asp",
+                    target: "_blank",
+                    rel: "noopener noreferrer"
+                }}
+            />
+
+            <h2 className={fr.cx("fr-mt-4w")}>ContentMedia — Audio natif</h2>
+            <ContentMedia
+                type="audio"
+                alternative="Son d'un cheval – voir transcription ci-dessous"
+                audioProps={{ src: "https://www.w3schools.com/html/horse.mp3" }}
+                caption="Illustration sonore – W3Schools"
+                captionLinkLabel="Voir la source"
+                captionLinkProps={{
+                    href: "https://www.w3schools.com/html/html5_audio.asp",
+                    target: "_blank",
+                    rel: "noopener noreferrer"
+                }}
+            />
+        </>
+    );
+}

From d095b52ac0b73011d76cfd64206d19c7d6a6beee Mon Sep 17 00:00:00 2001
From: kevbarns <kevin.barnoin@ext.beta.gouv.fr>
Date: Sat, 29 Aug 2026 14:29:22 +0200
Subject: [PATCH 2/3] feat(content-media): map ContentMedia in
 only-include-used-components

A module absent from REACT_DSFR_MODULE_TO_DSFR_COMPONENTS resolves to
undefined, which trips the include-everything fail-safe: the script warns,
exits 0, and trims no CSS at all for any project importing it.

content for the fr-content-media markup, link for the fr-link the caption
renders.
---
 src/bin/only-include-css-of-used-components.ts | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/bin/only-include-css-of-used-components.ts b/src/bin/only-include-css-of-used-components.ts
index 00773b1a4..3484d103d 100644
--- a/src/bin/only-include-css-of-used-components.ts
+++ b/src/bin/only-include-css-of-used-components.ts
@@ -134,6 +134,8 @@ export const REACT_DSFR_MODULE_TO_DSFR_COMPONENTS: Record<string, DsfrComponentN
     // The Chart components pull their CSS from the @gouvfr/dsfr-chart peer dependency.
     "Chart": [],
     "Checkbox": ["checkbox", "radio", "form"],
+    // The caption renders an fr-link.
+    "ContentMedia": ["content", "link"],
     "Display": ["modal", "radio", "form", "button", "link"],
     "Download": ["download", "link"],
     "Follow": ["follow", "form", "input", "upload", "button", "link", "alert", "checkbox"],

From ccb34426d05ed11c0581b007002406025b8ca0a6 Mon Sep 17 00:00:00 2001
From: Lotfi Habbiche <lotfi.habbiche@capgemini.com>
Date: Mon, 31 Aug 2026 16:05:39 +0200
Subject: [PATCH 3/3] feat(content-media): add size and ratio variants

- Add support for sm and lg media sizes
- Add ratio prop for image and SVG media
- Wrap SVGs in media container to support DSFR ratio utilities
- Simplify caption link API with a single captionLink prop
- Enforce accessible caption links by requiring label and link props together
- Update stories and integration examples
---
 src/ContentMedia.tsx               |  75 ++++++++-----
 stories/ContentMedia.stories.tsx   | 168 ++++++++++++++++-------------
 test/integration/vite/src/Home.tsx |  50 +++++----
 3 files changed, 168 insertions(+), 125 deletions(-)

diff --git a/src/ContentMedia.tsx b/src/ContentMedia.tsx
index d4d057299..1be45dd22 100644
--- a/src/ContentMedia.tsx
+++ b/src/ContentMedia.tsx
@@ -20,12 +20,29 @@ export type ContentMediaProps = {
     label?: string;
     /** Caption text shown below the media (description / source). */
     caption?: ReactNode;
-    /** Text of the optional link inside the figcaption. */
-    captionLinkLabel?: ReactNode;
-    /** Props of the optional link inside the figcaption. */
-    captionLinkProps?: RegisteredLinkProps;
+    /**
+     * Label and props of the optional link inside the figcaption.
+     * Both properties are required together so the link always has an accessible
+     * name (RGAA 6.1 / WCAG 2.4.4 – Link Purpose).
+     */
+    captionLink?: {
+        label: ReactNode;
+        linkProps: RegisteredLinkProps;
+    };
+    /**
+     * Size variant of the media container.
+     * - `"sm"` → `fr-content-media--sm`
+     * - `"lg"` → `fr-content-media--lg`
+     * - `"md"` (default) → no modifier class
+     */
+    size?: "sm" | "md" | "lg";
+    /**
+     * Aspect-ratio utility class applied to the image/SVG wrapper (`fr-ratio-*`).
+     * Only applies to `type="img"` and `type="svg"`.
+     * Example values: `"16x9"`, `"4x3"`, `"1x1"`, `"3x2"`, `"3x4"`, `"2x3"`.
+     */
+    ratio?: "16x9" | "3x2" | "4x3" | "1x1" | "3x4" | "2x3";
 } & ContentMediaProps.Media;
-
 export namespace ContentMediaProps {
     /** Image (`<img>`) media. */
     export type ImageMedia = {
@@ -41,7 +58,6 @@ export namespace ContentMediaProps {
             alt: string;
         };
     };
-
     /** SVG media — pass your `<svg>` element as the `svg` prop. */
     export type SvgMedia = {
         type: "svg";
@@ -52,7 +68,6 @@ export namespace ContentMediaProps {
          */
         svg: ReactNode;
     };
-
     /** Embedded video via `<iframe>` (e.g. YouTube). */
     export type IframeMedia = {
         type: "iframe";
@@ -66,7 +81,6 @@ export namespace ContentMediaProps {
             title: string;
         };
     };
-
     /** Native HTML5 `<video>`. */
     export type VideoMedia = {
         type: "video";
@@ -78,7 +92,6 @@ export namespace ContentMediaProps {
         /** Props forwarded to the `<video>` element. `controls` is always set. */
         videoProps: React.VideoHTMLAttributes<HTMLVideoElement> & { src: string };
     };
-
     /** Native HTML5 `<audio>`. */
     export type AudioMedia = {
         type: "audio";
@@ -90,10 +103,8 @@ export namespace ContentMediaProps {
         /** Props forwarded to the `<audio>` element. `controls` is always set. */
         audioProps: React.AudioHTMLAttributes<HTMLAudioElement> & { src: string };
     };
-
     export type Media = ImageMedia | SvgMedia | IframeMedia | VideoMedia | AudioMedia;
 }
-
 /** @see <https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenu-medias> */
 export const ContentMedia = memo(
     forwardRef<HTMLElement, ContentMediaProps>((props, ref) => {
@@ -104,24 +115,26 @@ export const ContentMedia = memo(
             classes = {},
             label,
             caption,
-            captionLinkLabel,
-            captionLinkProps
+            captionLink,
+            size,
+            ratio
         } = props;
-
         const id = useAnalyticsId({
             "defaultIdPrefix": "fr-content-media",
             "explicitlyProvidedId": id_props
         });
-
         const { Link } = getLink();
-
         const ariaLabel = label ?? (typeof caption === "string" ? caption : undefined);
-
+        const imgWrapperClassName = cx(
+            fr.cx("fr-content-media__img"),
+            ratio !== undefined ? (`fr-ratio-${ratio}` as string) : undefined,
+            classes.img
+        );
         const renderMedia = () => {
             switch (props.type) {
                 case "img":
                     return (
-                        <div className={cx(fr.cx("fr-content-media__img"), classes.img)}>
+                        <div className={imgWrapperClassName}>
                             <img
                                 {...props.imgProps}
                                 className={cx(fr.cx("fr-responsive-img"), props.imgProps.className)}
@@ -129,7 +142,10 @@ export const ContentMedia = memo(
                         </div>
                     );
                 case "svg":
-                    return <>{props.svg}</>;
+                    // The DSFR reference implementation wraps SVGs in fr-content-media__img
+                    // (example/component/content/index.html). The wrapper provides width:100%
+                    // and serves as an anchor for the fr-ratio-* size utilities.
+                    return <div className={imgWrapperClassName}>{props.svg}</div>;
                 case "iframe":
                     return (
                         <iframe
@@ -159,14 +175,19 @@ export const ContentMedia = memo(
                     );
             }
         };
-
-        const hasCaption = caption !== undefined || captionLinkProps !== undefined;
-
+        const hasCaption = caption !== undefined || captionLink !== undefined;
         return (
             <figure
                 id={id}
                 role="group"
-                className={cx(fr.cx("fr-content-media"), classes.root, className)}
+                className={cx(
+                    fr.cx("fr-content-media"),
+                    size !== undefined && size !== "md"
+                        ? (`fr-content-media--${size}` as string)
+                        : undefined,
+                    classes.root,
+                    className
+                )}
                 style={style}
                 {...(ariaLabel !== undefined ? { "aria-label": ariaLabel } : {})}
                 ref={ref}
@@ -175,9 +196,9 @@ export const ContentMedia = memo(
                 {hasCaption && (
                     <figcaption className={cx(fr.cx("fr-content-media__caption"), classes.caption)}>
                         {caption}
-                        {captionLinkProps !== undefined && (
-                            <Link {...captionLinkProps} className={fr.cx("fr-link")}>
-                                {captionLinkLabel}
+                        {captionLink !== undefined && (
+                            <Link {...captionLink.linkProps} className={fr.cx("fr-link")}>
+                                {captionLink.label}
                             </Link>
                         )}
                     </figcaption>
@@ -186,7 +207,5 @@ export const ContentMedia = memo(
         );
     })
 );
-
 ContentMedia.displayName = symToStr({ ContentMedia });
-
 export default ContentMedia;
diff --git a/stories/ContentMedia.stories.tsx b/stories/ContentMedia.stories.tsx
index 77221be30..a8f6890ab 100644
--- a/stories/ContentMedia.stories.tsx
+++ b/stories/ContentMedia.stories.tsx
@@ -3,16 +3,13 @@ import { sectionName } from "./sectionName";
 import { getStoryFactory } from "./getStory";
 import { assert } from "tsafe/assert";
 import type { Equals } from "tsafe";
-
 const { meta, getStory } = getStoryFactory({
     sectionName,
     "wrappedComponent": { ContentMedia },
     "description": `
 - [See DSFR documentation](https://www.systeme-de-design.gouv.fr/elements-d-interface/composants/contenu-medias)
 - [See source code](https://github.com/codegouvfr/react-dsfr/blob/main/src/ContentMedia.tsx)
-
-Supports **image**, **SVG**, **iframe**, **video** and **audio** media types  
-via the \`type\` discriminator prop.
+Supports **image**, **SVG**, **iframe**, **video** and **audio** media types via the \`type\` discriminator prop.
 
 \`\`\`tsx
 import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
@@ -23,14 +20,15 @@ import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
     label="Description / Source"
     imgProps={{ src: "image.png", alt: "Description de l'image" }}
     caption="Description / Source"
-    captionLinkLabel="Libellé lien"
-    captionLinkProps={{
-        href: "https://www.systeme-de-design.gouv.fr",
-        target: "_blank",
-        rel: "noopener noreferrer"
+    captionLink={{
+        label: "Libellé lien",
+        linkProps: {
+            href: "https://www.systeme-de-design.gouv.fr",
+            target: "_blank",
+            rel: "noopener noreferrer"
+        }
     }}
 />
-
 // Iframe vidéo (YouTube, etc.)
 <ContentMedia
     type="iframe"
@@ -41,39 +39,13 @@ import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
         allowFullScreen: true
     }}
     caption="Description / Source"
-    captionLinkLabel="Libellé lien"
-    captionLinkProps={{
-        href: "https://www.youtube.com/watch?v=HyirpmPL43I",
-        target: "_blank",
-        rel: "noopener noreferrer"
-    }}
-/>
-
-// Vidéo native
-<ContentMedia
-    type="video"
-    alternative="Alternative de la vidéo - voir transcription ci-dessous"
-    videoProps={{ src: "video.mp4" }}
-    caption="Description / Source"
-    captionLinkLabel="Libellé lien"
-    captionLinkProps={{
-        href: "https://www.w3schools.com/html/html5_video.asp",
-        target: "_blank",
-        rel: "noopener noreferrer"
-    }}
-/>
-
-// Audio natif
-<ContentMedia
-    type="audio"
-    alternative="Alternative de l'audio - voir transcription ci-dessous"
-    audioProps={{ src: "audio.mp3" }}
-    caption="Description / Source"
-    captionLinkLabel="Libellé lien"
-    captionLinkProps={{
-        href: "https://www.w3schools.com/html/html5_audio.asp",
-        target: "_blank",
-        rel: "noopener noreferrer"
+    captionLink={{
+        label: "Libellé lien",
+        linkProps: {
+            href: "https://www.youtube.com/watch?v=HyirpmPL43I",
+            target: "_blank",
+            rel: "noopener noreferrer"
+        }
     }}
 />
 \`\`\`
@@ -94,35 +66,76 @@ import { ContentMedia } from "@codegouvfr/react-dsfr/ContentMedia";
         "caption": {
             "description": "Caption / source text shown in the `<figcaption>`."
         },
-        "captionLinkLabel": {
-            "description": "Label of the link inside the `<figcaption>`."
-        },
-        "captionLinkProps": {
-            "description": "Props of the link inside the `<figcaption>`.",
+        "captionLink": {
+            "description":
+                "Label and props of the link inside the `<figcaption>`. Both are required together (RGAA 6.1).",
             "control": { "type": null }
+        },
+        "size": {
+            "options": ["sm", "md", "lg"],
+            "control": { "type": "radio" },
+            "description": "Size variant of the media container (`fr-content-media--sm/lg`)."
+        },
+        "ratio": {
+            "options": ["16x9", "3x2", "4x3", "1x1", "3x4", "2x3", undefined],
+            "control": { "type": "select" },
+            "description": "Aspect ratio applied to the image/SVG wrapper (`fr-ratio-*`)."
         }
     },
     "disabledProps": ["lang"]
 });
-
 export default meta;
-
 export const Image = getStory({
     "type": "img",
     "label": "Description / Source",
     "imgProps": {
-        "src": "https://www.systeme-de-design.gouv.fr/img/placeholder.16x9.png",
+        "src": "https://www.systeme-de-design.gouv.fr/v1.15/storybook/img/placeholder.16x9.png",
         "alt": "Description de l'image (texte alternatif)"
     },
     "caption": "Description / Source",
-    "captionLinkLabel": "Libellé lien",
-    "captionLinkProps": {
-        "href": "https://www.systeme-de-design.gouv.fr",
-        "target": "_blank",
-        "rel": "noopener noreferrer"
+    "captionLink": {
+        "label": "Libellé lien",
+        "linkProps": {
+            "href": "https://www.systeme-de-design.gouv.fr",
+            "target": "_blank",
+            "rel": "noopener noreferrer"
+        }
     }
 });
-
+export const ImageSmall = getStory(
+    {
+        "type": "img",
+        "size": "sm",
+        "label": "Image petite taille",
+        "imgProps": {
+            "src": "https://www.systeme-de-design.gouv.fr/v1.15/storybook/img/placeholder.16x9.png",
+            "alt": "Description de l'image"
+        },
+        "caption": "Description / Source — taille sm",
+        "captionLink": {
+            "label": "Libellé lien",
+            "linkProps": {
+                "href": "https://www.systeme-de-design.gouv.fr",
+                "target": "_blank",
+                "rel": "noopener noreferrer"
+            }
+        }
+    },
+    { "description": "Image avec variante de taille `sm` (`fr-content-media--sm`)." }
+);
+export const ImageWithRatio = getStory(
+    {
+        "type": "img",
+        "ratio": "1x1",
+        "label": "Image ratio carré",
+        "imgProps": {
+            "src": "https://www.systeme-de-design.gouv.fr/v1.15/storybook/img/placeholder.16x9.png",
+            "alt": "Description de l'image en ratio carré"
+        },
+        "caption": "Description / Source — ratio 1x1"
+    },
+    { "description": "Image avec ratio carré (`fr-ratio-1x1`) via la prop `ratio`." }
+);
 export const IframeVideo = getStory(
     {
         "type": "iframe",
@@ -134,16 +147,17 @@ export const IframeVideo = getStory(
             "allowFullScreen": true
         },
         "caption": "Description / Source",
-        "captionLinkLabel": "Libellé lien",
-        "captionLinkProps": {
-            "href": "https://www.youtube.com/watch?v=HyirpmPL43I",
-            "target": "_blank",
-            "rel": "noopener noreferrer"
+        "captionLink": {
+            "label": "Libellé lien",
+            "linkProps": {
+                "href": "https://www.youtube.com/watch?v=HyirpmPL43I",
+                "target": "_blank",
+                "rel": "noopener noreferrer"
+            }
         }
     },
     { "description": "Vidéo intégrée via `<iframe>` (ex : YouTube)." }
 );
-
 export const VideoNative = getStory(
     {
         "type": "video",
@@ -152,16 +166,17 @@ export const VideoNative = getStory(
             "src": "https://www.w3schools.com/html/mov_bbb.mp4"
         },
         "caption": "Description / Source",
-        "captionLinkLabel": "Libellé lien",
-        "captionLinkProps": {
-            "href": "https://www.w3schools.com/html/html5_video.asp",
-            "target": "_blank",
-            "rel": "noopener noreferrer"
+        "captionLink": {
+            "label": "Libellé lien",
+            "linkProps": {
+                "href": "https://www.w3schools.com/html/html5_video.asp",
+                "target": "_blank",
+                "rel": "noopener noreferrer"
+            }
         }
     },
     { "description": "Vidéo native HTML5 avec `<video>`." }
 );
-
 export const AudioNative = getStory(
     {
         "type": "audio",
@@ -170,22 +185,23 @@ export const AudioNative = getStory(
             "src": "https://www.w3schools.com/html/horse.mp3"
         },
         "caption": "Description / Source",
-        "captionLinkLabel": "Libellé lien",
-        "captionLinkProps": {
-            "href": "https://www.w3schools.com/html/html5_audio.asp",
-            "target": "_blank",
-            "rel": "noopener noreferrer"
+        "captionLink": {
+            "label": "Libellé lien",
+            "linkProps": {
+                "href": "https://www.w3schools.com/html/html5_audio.asp",
+                "target": "_blank",
+                "rel": "noopener noreferrer"
+            }
         }
     },
     { "description": "Fichier audio natif HTML5 avec `<audio>`." }
 );
-
 export const ImageWithoutCaption = getStory(
     {
         "type": "img",
         "label": "Image illustrative",
         "imgProps": {
-            "src": "https://www.systeme-de-design.gouv.fr/img/placeholder.16x9.png",
+            "src": "https://www.systeme-de-design.gouv.fr/v1.15/storybook/img/placeholder.16x9.png",
             "alt": ""
         }
     },
diff --git a/test/integration/vite/src/Home.tsx b/test/integration/vite/src/Home.tsx
index 8cafbd5ca..1fcf376cc 100644
--- a/test/integration/vite/src/Home.tsx
+++ b/test/integration/vite/src/Home.tsx
@@ -264,7 +264,7 @@ function ControlledAccordion() {
 function HighlightExample() {
     return (
         <Highlight
-            children={`Les parents d'enfants de 11 à 14 ans n'ont aucune démarche à accomplir : les CAF versent automatiquement l'ARS aux familles déjà allocataires qui remplissent les conditions.`}
+            children={`Les parents d’enfants de 11 à 14 ans n’ont aucune démarche à accomplir : les CAF versent automatiquement l’ARS aux familles déjà allocataires qui remplissent les conditions.`}
             bodyAs="p"
         />
     )
@@ -282,11 +282,13 @@ function ContentMediaExamples() {
                     alt: "Paysage de Cinque Terre en Italie"
                 }}
                 caption="© W3Schools – Cinque Terre, Italie"
-                captionLinkLabel="Voir la source"
-                captionLinkProps={{
-                    href: "https://www.w3schools.com",
-                    target: "_blank",
-                    rel: "noopener noreferrer"
+                captionLink={{
+                    label: "Voir la source",
+                    linkProps: {
+                        href: "https://www.w3schools.com",
+                        target: "_blank",
+                        rel: "noopener noreferrer"
+                    }
                 }}
             />
 
@@ -300,11 +302,13 @@ function ContentMediaExamples() {
                     allowFullScreen: true
                 }}
                 caption="Service National Universel – présentation officielle"
-                captionLinkLabel="Voir sur YouTube"
-                captionLinkProps={{
-                    href: "https://www.youtube.com/watch?v=HyirpmPL43I",
-                    target: "_blank",
-                    rel: "noopener noreferrer"
+                captionLink={{
+                    label: "Voir sur YouTube",
+                    linkProps: {
+                        href: "https://www.youtube.com/watch?v=HyirpmPL43I",
+                        target: "_blank",
+                        rel: "noopener noreferrer"
+                    }
                 }}
             />
 
@@ -314,11 +318,13 @@ function ContentMediaExamples() {
                 alternative="Vidéo de démonstration Big Buck Bunny – voir transcription ci-dessous"
                 videoProps={{ src: "https://www.w3schools.com/html/mov_bbb.mp4" }}
                 caption="Big Buck Bunny – Blender Foundation"
-                captionLinkLabel="Voir la source"
-                captionLinkProps={{
-                    href: "https://www.w3schools.com/html/html5_video.asp",
-                    target: "_blank",
-                    rel: "noopener noreferrer"
+                captionLink={{
+                    label: "Voir la source",
+                    linkProps: {
+                        href: "https://www.w3schools.com/html/html5_video.asp",
+                        target: "_blank",
+                        rel: "noopener noreferrer"
+                    }
                 }}
             />
 
@@ -328,11 +334,13 @@ function ContentMediaExamples() {
                 alternative="Son d'un cheval – voir transcription ci-dessous"
                 audioProps={{ src: "https://www.w3schools.com/html/horse.mp3" }}
                 caption="Illustration sonore – W3Schools"
-                captionLinkLabel="Voir la source"
-                captionLinkProps={{
-                    href: "https://www.w3schools.com/html/html5_audio.asp",
-                    target: "_blank",
-                    rel: "noopener noreferrer"
+                captionLink={{
+                    label: "Voir la source",
+                    linkProps: {
+                        href: "https://www.w3schools.com/html/html5_audio.asp",
+                        target: "_blank",
+                        rel: "noopener noreferrer"
+                    }
                 }}
             />
         </>