Diagrams are useful in documentation to help illustrate engineering concepts and
guides. However, it's important to ensure diagrams on fuchsia.dev are accessible
and updatable. This guide shows you how to add maintainable diagrams to Fuchsia
documentation.

## Types of diagrams

- Generate a simple flow diagram from text in the source code. Options:

  - [Mermaid](https://mermaid.live/): This is a simple way to maintain diagrams that are generated from text in the source code
  - [Sequence Diagram](https://bramp.github.io/js-sequence-diagrams/): Create basic flow diagrams using text in the source code
  - (Googlers only) [go/sequencediagram](http://goto.google.com/sequencediagram): Internal version of the Sequence Diagram tool
- Create a visual diagram in Google Drawings, Slides, or other tools

## How to add visual diagrams

If you are creating a visual diagram for documentation on fuchsia.dev, follow
these steps:

1. Create a visual diagram in your tool of choice and either use a code block
   for tools like Mermaid or export the image as a `.svg` (suggested) or `.png`
   file.

   For images, ensure to do the following:
   - Optimize your image to ensure it loads quickly. Large images can increase page load times.
   - Use SVG (Scalable Vector Graphics) format whenever possible. SVGs are scalable, accessible, and have a smaller file size compared to other image formats.
2. Embed the image on fuchsia.dev using Markdown. For example:
   [see instructions](https://fuchsia.dev/docs/contribute/docs/markdown#images).

   ### mermaid

   > [!NOTE]
   > **Note:** Use the [Mermaid live editor](https://mermaid.live/) to create your diagram. For more information about Mermaid syntax, see the [Mermaid documentation](https://mermaid.js.org/intro/syntax-reference.html).

   ### markdown

   ````
   ```mermaid
   graph LR
   A[Square Rect] -- Link text --> B((Circle))
   A --> C(Round Rect)
   B --> D{Rhombus}
   C --> D
   ```

   ````

   ### html


       <pre class="mermaid">
         graph LR
         A[Square Rect] -- Link text --> B((Circle))
         A --> C(Round Rect)
         B --> D{Rhombus}
         C --> D
       </pre>

   Rendered:

   <br />

   <iframe src="https:///frame/fuchsia-src/contribute/docs/adding-diagrams_d34decc8d3f1c5000078aa2fa2dcae53d3f5e36f9b99fe1dce802ab71b619f34.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

   <br />

   ### .svg/.png

   > [!NOTE]
   > **Note:** If applicable, store your image in a `image/` directory near your Markdown file.

   Make sure to add alt text to the image. Alt text helps screen reader users
   understand the content of your image. For example:

       ![Alt text](image_filename.svg)

   - Replace `Alt text` with a concise description of the image.
   - Replace `image_filename.svg` with the actual filename of your image.

   For example:

       ![A flowchart showing the boot process of a Fuchsia device. The process starts
       with the bootloader, then moves to Zircon kernel, and finally to the user
       space.](component_framework.svg)

## UX guidelines for diagrams

Diagrams are a useful tool for providing additional clarity or context that is
not easily conveyed through words alone. Effective diagrams should directly
support and enhance the accompanying text in documentation.

- **Focus:** Each diagram should have a clear focus and convey a specific
  concept or idea. Label all elements clearly and concisely.

- **Simplicity:** Strive for visual clarity. Avoid excessive complexity or
  visual clutter that might confuse the reader.

- **Consistency:** Maintain a consistent style and visual language across all
  diagrams within Fuchsia documentation.

- **Internationalization:** Keep text within diagrams to a minimum. If text is
  necessary, ensure it is translatable and localized. Use universally recognized
  symbols and icons whenever possible.

### Design considerations

- **Visual hierarchy:** Use clear and consistent visual hierarchy to guide the
  reader's eye through the diagram. Use whitespace to create visual separation
  and improve readability.

- **Color:** Use sufficient color contrast to ensure readability for users with
  visual impairments. Avoid using color as the sole means of conveying
  information.

- **Scalability:** Ensure diagrams are scalable and can be zoomed in without
  losing clarity.

### Alt text

Provide concise and informative alternative text descriptions for all diagrams. Alt text should:

- Accurately describe the content and purpose of the diagram
- Use plain language that is easy for everyone to understand
- Be concise and to the point, avoiding unnecessary detail
- If a diagram contains text, include that text in the alt text

> [!NOTE]
> **Note:** Avoid using phrases like "image of" or "diagram of" as screen readers already identify them as images.

**Alt text examples**:

|---|---|
| A flowchart showing the boot process of a Fuchsia device. The process starts with the bootloader, then moves to Zircon kernel, and finally to the user space. | Image of a flowchart. (Too generic and not informative) |
| Do | Don't |

|---|---|
| A diagram illustrating the relationship between components in a Fuchsia component framework. The components are arranged hierarchically, with parent components at the top and child components at the bottom. | Diagram with boxes and arrows. (Not descriptive enough) |
| Do | Don't |

[](https://issues.fuchsia.dev/issues/new?component=1439230&template=1881640&description=Issue+on:+https://fuchsia.dev/docs/contribute/docs/adding-diagrams.md "Report a bug or suggest improvements on this page") [](https://cs.opensource.google/fuchsia/fuchsia/+/main:docs/contribute/docs/adding-diagrams.md "View the source code of this page") [](https://ci.android.com/edit?repo=fuchsia/fuchsia/main&file=docs/contribute/docs/adding-diagrams.md&cloneRepo=fuchsia/fuchsia:refs/heads/main&fullPath=fuchsia/docs/contribute/docs/adding-diagrams.md "Edit the source code of this page")