Menu
Writers' Toolkit Write Image and media guidelines
Open source

Image, diagram, and screenshot guidelines

At Grafana Labs, images are an essential part of helpful, clear, and concise content. Follow the standards in this section when creating images for your documents.

Image and diagram guidelines

Images and diagrams can complement text, enabling readers to quickly grasp a concept and visualize complex processes in a simplified way. However, because translation services and tools for the visually impaired don’t interpret or translate images well, avoid using images to replace text.

When to use images and diagrams

Consider using images or diagrams when you need to:

  • Clarify configurations and settings, such as the architecture for virtual servers
  • Define a complex workflow within a Grafana product

Do not include images or diagrams when:

  • A workflow is simplistic
  • There is no interaction with a Grafana product

Image and diagram standards

Use the following standards for images and diagrams:

  • Size: To reduce page-load time, make images and diagrams as small as you can without compromising their usefulness.

    Unless image clarity is critical to understanding, use 65-75 percent quality when saving your image. Use the following recommendations when you size images:

    • Horizontal: maximum width 1200px
    • Vertical: maximum height 900px
  • Scope: Limit the contents of an image to the relevant portion.

    Don’t include distracting or unnecessary content and whitespace.

  • Format: PNG and SVG are the preferred image formats.

    Use JPG only for photos.

  • Copyright: You must determine if an image or diagram is protected by copyright.

    If it is, you must obtain permission and acknowledge credit.

  • File name: Use the naming convention documented in Media asset file naming conventions.

Personally Identifiable Information (PII)

Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security.

Alt text and figure captions

Make sure to include alt text for every image. Figure captions are optional.

Diagram assets

To create diagrams, you need to access the recommended software and download the required icons and stencils.

Request a diagram from Creative Services

The Design team at Grafana Labs can provide support for diagrams developed by internal Grafana Labs contributors. Contact them directly using their design request form.

Screenshot guidelines

When you document a user interface, consider whether you need to include screenshots. Screenshots can be helpful when text alone can’t adequately convey instructions.

Users also like screenshots and find them useful. However, screenshots are difficult and time-consuming to maintain, and can present problems with translation.

As a result, you should minimize the use of screenshots within your content.

When to use screenshots

Consider using screenshots when you want to:

  • Provide an example of a visualization
  • Show panels populated with a query and settings
  • Orient users in a complicated or long procedure
  • Show complex relationships among drop-down menus, such as those that contain multiple subsets of information and many options available for selection
  • Emphasize a feature or a change in the UI

When not to use screenshots

Do not use screenshots for the following items:

  • Simple create operations, such as create a user, a team, an organization, and so on
  • Primary or secondary navigation items
  • Code samples (show code samples in code blocks)
  • Dialog boxes that are easy to understand
  • Message text (instead show message text within the Markdown)
  • Progress bars
  • Simple pages, such as Wizard pages and Welcome pages
  • Tables created in another authoring tool
  • A page that’s likely to change frequently

Screenshot alternatives

Only add screenshots to your documentation when necessary. Instead of providing screenshots, you can consider being explicit about the user interface elements with which the user interacts. Add the names of buttons, navigation items, toggles, menus, and so on as they appear on the user interface.

For example, don’t include a screenshot to illustrate simple instructions like, “To add a dashboard, click Dashboard > New Dashboard”.

Screenshots in tasks

Place a screenshot below the step that it illustrates. Don’t rely on the screenshot to convey the information or values that the user must enter. If the user must enter specific information, provide that information in the text of the steps. However, ensure that the screenshot accurately reflects the directions and values in the step text.

Screenshot guidelines

Consult the following guidelines when you create screenshots:

  • Size: The maximum width of a screenshot is 600 pixels.
  • Scope: Limit the screenshot to just the portion of the user interface that shows the action, and enough surrounding detail to help the user locate the item.
  • Annotations: To annotate a screenshot, use red, hexadecimal color FF0000, arrows and boxes.
  • File name: Use the naming convention documented in Media asset file naming conventions.
  • Personal identifiable information (PII): Make sure to mask, modify, or remove any PII such as passwords, logins, account details, or other information that could compromise security.
  • Alt text: Make sure to include alt text for every image.

Media asset file naming conventions

The table in this section includes file naming conventions for you to follow when you create image assets.

General rules:

  • Use lowercase letters in filenames, always.
  • Use dashes between words; don’t use spaces or underscores.
  • Don’t type special characters or punctuation marks in a filename except for periods in product version numbers. For example: grafana-9.2.release.png.
  • Don’t use abbreviations that may cause issues with localization.
    • For example, spell out database instead of using db.
    • When in doubt, don’t use an abbreviation.
    Asset typeNaming convention
    ScreenshotNaming convention: [asset type]-[visual description]-[version, if applicable].png

    Examples:
    • screenshot-grafana-loki-uptime-dashboard.png
    • screenshot-grafana-mimir-data-flow-diagram.png
    • screenshot-grafana-9-kubernetes-dashboard.png (or)
    • screenshot-grafana-9.0-kubernetes-dashboard.png
    • screenshot-simple-scalable-test-environment-grafana-loki.png
    IconBe as descriptive as possible.

    For example, use `icon-bar-graph.svg` or `icon-graph-bar.svg` instead of `icon-graph.svg`.
    Naming convention: [asset type]-[visual description].svg

    Examples:
    • icon-bar-graph.svg
    • icon-prometheus.svg
    LogoWhen you name Grafana logo files, be sure to include the word “Grafana”.

    Naming convention: [asset type]-[visual description]-[color + orientation].[file type]

    Examples:
    • logo-prometheus-full-horizontal.svg
    • logo-grafana-loki-full-horizontal.svg
    PhotoNaming convention: [asset type]-[visual description].jpg

    Examples:
    • photo-raji-on-stage-grafanacon-keynote-2022.jpg
    • photo-grafanacon-team-marketing.jpg
    • photo-headshot-mike-szczys.jpg
    RecordingNaming convention: [asset type]-[visual description].[file type]

    Example:
    • gif-grafana-share-playlist.mp4

Where to store media assets

All visual assets are stored in Google Cloud Storage, only accessible to Grafana Labs employees. You use the asset upload application to upload assets. The following table lists the steps you take to provide the Grafana Labs technical documentation team with the image.

Note

Don’t store images in the local repository, as it prohibits re-use of the asset in other content.
If you are a...Complete these steps
Grafana Labs employee
  1. Create a PR against the local repository that includes the Markdown file.
  2. Navigate to https://admin.grafana.com/upload/.
  3. Find or create a directory under the media directory. To create a directory, type the directory name in the upload input field.
  4. Use a free image optimizer like TinyPNG to decrease the image file size.
  5. Browse and select assets to upload.
  6. Click Upload.
  7. The asset is available under https://grafana.com/media/ in the directory where you uploaded it.
  8. Click Copy to copy the path (reference) of the file to your clipboard.
  9. Add the reference to the Markdown file.

    The reference that you add to the Markdown renders the image when you build the Grafana website or a local docs preview.
Grafana Labs community contributor
  1. Create a PR against the local repository that includes the Markdown file.
  2. Add the image reference to the Markdown file.

    You don't need to test that the image renders in a local build of the documentation. The Grafana technical documentation team reviewing the PR ensures that the image reference works correctly.

  3. Attach the image to the GitHub PR description.

Add an image to a Markdown file

To add an image to a Markdown file, insert a reference to the image below the associated step and indent it so that the reference aligns with the step text.

The image reference path conforms to the following convention: ![<Short description of image>](/media/<path-to-image/image-file.png>)

For example:

  1. In the Visualization list, select a visualization type.

    ![Visualization types](/media/docs/panel-editor/select-visualization.png)

Test images in a local build

Note

This section is relevant to internal Grafana Labs contributors.

It’s important that you generate a local build of your docs so that you can verify that the path to the image, the image size, and the image placement are correct.

  1. Follow the steps in Where to store media assets.

  2. Run make docs on your branch and verify that the image appears.

  3. If it doesn’t render as you desire, upload another version and test again.

Alt text

Alt text is an HTML attribute that you can use to provide a concise description of an image. The text is used in situations where the image isn’t visible, such as when people use screen readers or have a low-bandwidth internet connection.

In Markdown, the alt text is the text in square brackets when declaring an image:

markdown
![Alt text](/media/<path-to-image/image-file.png>)

Or, if you’re using the figure shortcode, you can use the alt parameter:

markdown
{{< figure alt="Alt text"  src="/media/<path-to-image/image-file.png>" >}}

Every image that you add to the Grafana documentation should have an alt text.

A good piece of guidance for writing good alt text from HTML: The Living Standard is:

One way to think of alternative text is to think about how you would read the page containing the image to someone over the phone, without mentioning that there is an image present. Whatever you say instead of the image is typically a good start for writing the alternative text.

For more information about how to write good alt text, refer to:

Screen recordings

The recommended format for screen recordings is .mp4. Don’t use .gif or .mov formats. In particular, avoid animated GIFs because they distract users. For more information about distracting content, refer to Understanding Success Criterion 2.2.2: Pause, Stop, Hide | WAI | W3C.

Screen recordings follow the same upload procedure and file naming convention as other media assets. Use the video-embed shortcode to embed the video on the page:

{{< video-embed src="/media/<path-to-recording/recording.mp4>" >}}

Videos

The Creative Services team periodically creates videos for blog posts and other collateral. Most of these videos are hosted on Vimeo or YouTube.

Note

Embed videos only from official Grafana sources.

Embed Vimeo videos

You can embed a Vimeo-hosted video by using the vimeo shortcode and the video ID: {{< vimeo 1111111>}}.

In this example, the video is a Preview of Tempo 2.0 and TraceQL: https://vimeo.com/773194063. You can find the video ID at the end of the URL.

{{< vimeo 773194063 >}}

Embed YouTube videos

You can also embed videos hosted on YouTube. The Grafana YouTube channel has good, short content that highlights features and specific topics.

Use the youtube shortcode to embed the video. The id is the v URL parameter in the YouTube URL.

For example, for the YouTube URL https://www.youtube.com/watch?v=g97CjKOZqT4, the shortcode is the following:

markdown
{{< youtube id="g97CjKOZqT4" >}}

You can configure start and end, in seconds, with:

markdown
{{< youtube id="g97CjKOZqT4" start="100" end="200" >}}

You can configure automatic playback with:

markdown
{{< youtube id="g97CjKOZqT4" autoplay="true" >}}