graphql-engine/docs/wiki/style/images.mdx

---
title: Images
description: Style for images and screenshots in documentation
keywords:
  - hasura
  - style
  - images
slug: images
---

# Images

A picture says a thousand words. Try to use images and diagrams wherever you can if it will provide more clarity to the
user.

## Screenshots

### Scale

- Screenshots should be captured at a browser viewport width of `1200px`. This helps keep scaling consistent.
- You can use this
  [Chrome extension](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh?hl=en) to
  quickly set your browser viewport to `1200px`
- Don't zoom in or out.
- When placed in situ in the documentation, the text in the image of a screenshot should closely match the text size of
  the page itself.

### Cropping

- Leave `20px` blank margins in-image around all four sides for breathability of the image.
- Crop only the logical contextual area for the feature that you are referencing. For example:
  - **don't** crop the whole screen UI if you are calling attention to only one small component on the page.
  - **do** crop the whole screen UI if it is contextual to what you are referencing.
- Make sure if you are cropping a smaller area or component that the user understands where to find it and its place in
  context within their workflow.

### File type

- Use PNGs.
- PNGs will automatically be optimized when added to the pull request

### File name

- Include the Hasura feature and version number in the screenshot name to make it easier to check when screenshots are
  outdated.
- Name the file with this structure:
  `{{action-depicted}}_{{image-step-or-variation-number-if-needed}}_{{hasura-feature-depicted}}_{{hasura-feature-version}}.png`
- eg: `connect-database-google-cloud_step-2_console_2-7-1.png`

### Callouts, arrows and other screenshot markup

- Use hex color <pre style={{ background: `#FC336D` }}>#FC336D</pre> for all image markup.
- Use rounded corners on callout blocks.
- Generally, if you want to show selecting something, use borders. If you want to show clicking on a button, use arrows.
- Don't make arrows unnecessarily long or short.
- Use step numbering of a number in a circle. Start count from 1, not array 0 notation.
- Use the [Skitch markup app](https://evernote.com/products/skitch) if possible.

### Versioning

- Always add an `:::info Note` admonitions for new features detailing the version at which the feature is supported
  from.
- Make sure prior versions of documentation are properly kept.

## Animated images

Animated images should be used sparingly and should be used to show a user how to perform a task.

### Creating animated images

- We use a tool called [ScreenStudio](https://www.screen.studio/) to create animated images.
- This is a paid tool; if you don't have access to it, please ask someone on the docs team to create the animated image
  for you.
  - If you ask for an animated image, please provide a detailed description of what you want to show in the animated
    image along with the steps you want to highlight.
- If you are creating an animated image, please follow the guidelines below.

### Guidelines

- Use Google Chrome with the default dark theme.
- Your browser window should be set to `1200px x 900px`.
- Ensure your bookmark bar is hidden.
- It also helps to
  [disable autocomplete](https://support.iclasspro.com/hc/en-us/articles/218569268-How-Do-I-Disable-or-Clear-AutoFill-AutoComplete-Information-)
  in the URL and search bars.
- Carefully and deliberately perform the steps you want to show in the animated image.
  - If needed, you can speed up the playback of your actions during editing.

### Workflow

#### Recording and editing

- Create a new project in ScreenStudio.
- Utilize this background image for a consistent look:
  ![Background Image](https://user-images.githubusercontent.com/94021366/226903753-3958eb19-bd3f-4890-9743-5a4a3f03502d.jpg)
- As you edit, ensure the camera doesn't zoom in and out constantly; deliberately select when you want to emphasize a
  particular area of the screen using the zoom tool.
- We speak from experience: ☝️ it helps to practice this a few times first!
- When you are done, export the video as an mp4.

#### Converting and compressing

All videos should be converted and compressed to the webm format before being added to the docs. This can be done using
[`ffmpeg`](https://ffmpeg.org/):

```bash
 ffmpeg -i <ORIGINAL>.mp4 -c vp9 -b:v 0 -crf 55 <DESIRED_FINAL_FILENAME>.webm
```

The `-crf` flag controls the quality of the video. The lower the value, the higher the quality. The default value is
`23`. The range is `0-63`, with `0` being lossless and `63` being the worst possible quality. A value of `55` is
generally considered to be a good balance between quality and file size.

#### Adding to the docs

Use the `<Player />` component to add the video to the docs. The component takes the following props:

| Prop           | Type    | Description                                            | Required | Default |
| -------------- | ------- | ------------------------------------------------------ | -------- | ------- |
| `src`          | string  | The path to the video file.                            | Yes      |         |
| `autoPlay`     | boolean | Whether the video should autoplay when the page loads. |          | `true`  |
| `loop`         | boolean | Whether the video should loop when it reaches the end. |          | `true`  |
| `muted`        | boolean | Whether the video should be muted.                     |          | `true`  |
| `playsInline`  | boolean | Whether the video should play inline.                  |          | `true`  |
| `showControls` | boolean | Whether the video should show controls.                |          | `false` |

You can import the component inside any `.mdx` file like this:

```jsx
import Player from '@site/src/components/Player';
```

And then use it like this:

```jsx
<Player src="/img/<SUBDIRECTORY>/<FILENAME>.webm" />
```