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. For example, in Grafana blog posts, pictures or diagrams can add visual interest and capture the reader’s attention. 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. Do not include distracting or unnecessary content and whitespace.
Format: PNG and SVG are the preferred image formats. Use JPG only for photos.
Copyright: 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.
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.
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. Please 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 cannot 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 new 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 is 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, do not 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. Do not 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.
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 will cause issues with localization.
- For example, spell out
database
instead of usingdb
, but using an acronym, such as RBAC, is ok. - When in doubt, don’t use an abbreviation.
Asset type Naming convention Screenshot Naming 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
Icon Be 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
Logo When 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
Photo Naming 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
Recording Naming convention: [asset type]-[visual description].[file type]
Example:- gif-grafana-share-playlist.mp4
- For example, spell out
Recommended image editors
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: Do not 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 |
|
Grafana Labs community contributor |
|
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:

For example:
In the Visualization list, select a visualization type.

Test images in a local build
Note: This section is relevant to internal Grafana Labs contributors.
It is 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.
Follow the steps in Where to store media assets.
Run
make docs
on your branch and verify that the image appears.(Optional) Upload a new version and test again.
Screen recordings
The recommended format for screen recordings is .mp4. Do not use .gif or .mov formats. 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.
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
. The video id is located at the end of the URL.
{{< vimeo 773194063 >}}