Skip to content

Clarify screenshot image guidance in Style Guide #5424

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jun 2, 2025
Merged

Clarify screenshot image guidance in Style Guide #5424

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
92d8ea4
Clarify screenshot image guidance in Style Guide
kimsauce May 31, 2025
16b38f3
Update docs/contributing/style-guide.md
kimsauce Jun 2, 2025
6bdab58
Merge branch 'main' into DOCS-717
kimsauce Jun 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 22 additions & 17 deletions docs/contributing/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -735,30 +735,42 @@ You can use a link to a file embedding the entire file, or embed a range of code
</TabItem>
</Tabs>

### Image sizes
### Logos

When sizing images, use your discretion.

#### Logos

For square logos, set the width to about 45-55px.
When sizing images, use your discretion. For square logos, set the width to about 45-55px.

| &#9989; **Do** | &#10060; **Don't** |
|:---------------|:-------------------|
| <img src={useBaseUrl('img/contributing/logo-yes.png')} alt="Screenshot showing correctly sized logo" width="400"/> | <img src={useBaseUrl('img/contributing/logo-no.png')} alt="Screenshot showing oversized logo" width="440"/> |

For wide logos (like [in this doc](/docs/integrations/microsoft-azure/iis-7/)), set the width to about 90-120px.

#### Screenshots
### Screenshots

Use screenshots only when they clarify complex instructions. Our UI changes often, so minimizing screenshots reduces maintenance overhead.

* Prefer clear, concise text instructions over images when possible.
* Only include screenshots if they significantly aid user understanding.
* Avoid screenshots for simple UI interactions.
* When updating docs, evaluate whether screenshots are outdated or redundant.
* If you come across unnecessary screenshots, use your judgment to delete or replace them.

Ensure that screenshots are large enough so that the content is legible, but not comically oversized. Use your discretion.
Make sure screenshots are large enough to be legible, but never wider than 800px. Avoid oversized images.

By default, images that you insert into a page are set to be responsive-resized for the type of device the reader is using.

Use the following syntax to add screenshots:

```md
<img src={useBaseUrl('img/<your-image-file>.png')} alt="Descriptive alt text" style={{border: '1px solid gray'}} width="500" />
```

Add appropriate `alt` text for accessibility. See [Add an image](#add-an-image) for more.

| &#9989; **Do** | &#10060; **Don't** |
|:---------------|:-------------------|
| <img src={useBaseUrl('img/contributing/screenshot-yes.png')} alt="alt-text" width="400"/> | <img src={useBaseUrl('img/contributing/screenshot-no.png')} alt="alt-text" width="400"/> |

Screenshots should never be wider than 600px.

### Images in lists

When adding an image to a bulleted or sequential list, include the image snippet in-line with the list item, with a `<br/>` element in between, like this:
Expand All @@ -785,13 +797,6 @@ When adding an image to a bulleted or sequential list, include the image snippet
</TabItem>
</Tabs>

### Screenshots

Capture screenshots using SnagIt in .png format. Use SnagIt's border effect to apply a gray (RGB 212, 212, 212) four-point border.

By default, images that you insert into a page are set to be responsive - resized for the type of device the reader is using.


### Masking sensitive information

We mask sensitive information like usernames, email addresses, and IP addresses. In Snagit or a similar program, use the shape tool to mask the text using solid gray, (RGB 212, 212, 212).
Expand Down