Skip to main content

Demonstrative images

A demonstrative image is a visual representation of an object, scene, person, or concept. Use images to demonstrate a concept that is difficult to understand or showcase a complex effect.

When you use images correctly, they can do the following:

  • Supplement textual descriptions for different types of learners.
  • Break down language barriers by conveying information visually.
  • Reduce cognitive load and accelerate learning.
  • Engage users by making the content visually appealing.

Despite these benefits, images can impact overall file size and page loading times. Use them only when necessary.

note

For guidelines around setting up and taking screenshots, refer to Screenshots.

Guidelines and best practices​

Use images in the following situations only:

  • To enhance the understanding of the material being presented.
  • To provide useful visual explanations of a concept, feature, or effect that is otherwise difficult to express with words.

When you create images, keep the following guidelines and best practices in mind.

Image conception​

Keep your images simple. Don’t try to illustrate multiple thoughts, concepts, or effects in the same image. Don’t complicate images with detailed backgrounds, lighting, or unnecessary effects. Instead, focus on the specific feature or effect that you want to demonstrate.

Third-party assets​

Whenever possible, avoid using third-party assets. If you decide to use a third-party asset or image to showcase a specific feature, check with legal to make sure you have the rights to use the asset or image. After you get legal approval, make sure to provide adequate attribution. For more information, refer to Image attribution.

Image format, size, and resolution​

  • Depending on the type of image, use one of the following image formats:
    • PNG: For images with defined lines and large areas of monotone colors.
    • JPG: For photorealistic images with many colors and gradients.
  • Image size depends on the target platform or site:
    • Core platform: Maximum image size is 849 x 900 pixels in landscape orientation. Images larger than the maximum are automatically resized during the build process.
    • Packages: No restriction on pixel width or height, but larger images are downscaled to fit within the content area of the package docs site. For more information about image size restrictions, refer to Screenshot size and resolution.
  • Keep the file size as small as possible. For packages, the file size must be below 1MB.

Accessibility​

  • Include a text alternative to the image for people who use screen readers or text-only browsers, or who have a low-bandwidth internet connection. For more information, refer to Alt text.
  • Don’t use image maps to create multiple clickable areas or "hotspots" within a single image.
  • Don't use images of text, code samples, or terminal output. Use actual text.

File naming​

Use meaningful, unique names and format them in kebab-case, as follows:
Feature-name-specific-thing-name.png.

Example: animation-select-imported-clip.png
Example: scene-room-avatars.png

Testing​

Verify the size of all images that you add to the documentation by building a local or staged version of the documentation. To build a local or staged version of the documentation, refer to the following resources: