---
title: "Guidelines for creating images"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:guidelines-for-images"
source: "Advanced/GuidelinesForImages.rst"
modified: "2026-09-14T09:38:54+00:00"
---

# Guidelines for creating images

For accessibility reasons **always** provide an alt text:

**Documentation/MyDocs.rst**

```plaintext
..  figure:: /_Images/a4.jpg
    :alt: some image

    This is the image caption

```

More optional parameters for embedding images into ReST: [Images](https://docs.typo3.org/permalink/h2document:images).

## Image formats

-   It is recommended to use PNG for bitmaps (for example screenshots, photographs)
    and SVG for vector graphics images. In any case, you can use `.png`.

## Guidelines for screenshots

> [!NOTE]
> You can use the [The example screenshot project](https://docs.typo3.org/permalink/h2document:screenshot-project).
> It already follows most of the rules stated below. There has been no automatic
> screenshot tool since TYPO3 v11 as it proved to be too complicated to maintain.

-   Before adding a screenshot consider if one is necessary. Each new screenshot
    requires maintenance.
-   Use a Composer-based installation of the latest LTS release, or dev-main.
-   Turn the backend into light mode and modern look.
-   Unless you want to demonstrate features of certain system extensions use
    a default installation as described in Getting Started:
    [Installing TYPO3 with DDEV](https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/Installation/Install.html#installation-ddev-tutorial).
-   If you need an example site package use `t3docs/site-package`.
-   If you need example data use [`t3docs/site-package-data`](https://packagist.org/packages/t3docs/site-package-data).
-   As personalized usernames are considered best practice always use username
    "j.doe".
-   Do not install third party extensions unless what you want to demonstrate
    requires one. If possible use one of the extensions from vendor `typo3` or
    `t3docs`.
-   Use PNG or AVIF format (`.png` or `.avif` file ending).
-   If you take a screenshot of a full page it should have 1400 x 1050 px.
-   Size the browser window to at least 1440 x 1050 px before taking backend
    screenshots — narrow viewports collapse the module menu and truncate
    table columns. Capture slightly wider than the 1400 px target, then crop.
-   The content of a backend module is rendered inside an iframe that scrolls
    internally. A "full page" screenshot (for example Playwright's
    `fullPage: true`) captures only the outer frame and cuts off the lower
    part of the module — to capture a tall module view, increase the height
    of the viewport itself and take a normal screenshot.
-   Use only parts of a full page when possible, the flatter the screenshot the
    less room it takes.
-   When reviewing screenshots take into consideration that taking screenshots
    is a lot of effort.

## The example screenshot project

We have a ready to use TYPO3 project that you can run in GitHub Codespaces
or locally on DDEV to make screenshots:

[Ready to use Project for screenshots](https://github.com/TYPO3-Documentation/site-introduction/blob/main/README.md)

## Guidelines for screenshots with graphics elements

You will often see a screenshot where additional graphic elements have been added in the
documentation. These additional graphic elements may be boxes, numbers or arrows.

-   Use sufficient contrast to ensure additional graphic elements are visible
    across devices and for as many readers as possible, even if they have
    color vision differences.