> ## Documentation Index
> Fetch the complete documentation index at: https://learn.mintlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Images, frames, and diagrams

> Choose visuals that clarify a task, then make them accessible and easy to maintain.

export const Quiz = ({question, answers, correctFeedback, incorrectFeedback}) => {
  const [selected, setSelected] = React.useState(null);
  const [checked, setChecked] = React.useState(false);
  const quizId = React.useId();
  const isCorrect = checked && answers[selected]?.correct;
  const reset = () => {
    setSelected(null);
    setChecked(false);
  };
  return <div className={"quiz-container" + (checked ? " quiz-checked" : "")}>
      <Badge color="green">Quiz</Badge>
      <p className="quiz-question" id={quizId + "-question"}>{question}</p>
      <div className="quiz-options" role="radiogroup" aria-labelledby={quizId + "-question"} aria-disabled={checked}>
        {answers.map((answer, i) => <label key={i} className={["quiz-option", !checked && selected === i ? "quiz-option-selected" : "", checked && answer.correct ? "quiz-option-correct" : "", checked && selected === i && !answer.correct ? "quiz-option-incorrect" : ""].filter(Boolean).join(" ")}>
            <input type="radio" name={"quiz-" + quizId} checked={selected === i} onChange={() => !checked && setSelected(i)} disabled={checked} />
            <span className="quiz-radio" />
            <span className="quiz-option-label">{answer.text}</span>
          </label>)}
      </div>
      {checked && <div className={"quiz-feedback " + (isCorrect ? "quiz-feedback-correct" : "quiz-feedback-incorrect")} role="status" aria-live="polite" aria-atomic="true">
          <span className="quiz-feedback-icon">{isCorrect ? "✓" : "✗"}</span>
          {isCorrect ? correctFeedback : incorrectFeedback}
        </div>}
      <div className="quiz-actions">
        {!checked ? <button className="quiz-btn quiz-btn-check" type="button" onClick={() => selected !== null && setChecked(true)} disabled={selected === null}>
            Check answer
          </button> : <button className="quiz-btn quiz-btn-reset" type="button" onClick={reset}>
            Try again
          </button>}
      </div>
    </div>;
};

Adding a screenshot can feel like the quickest way to make a page more helpful. Sometimes it is. Other times, the screenshot repeats the instructions, goes stale after the next product update, and makes the important part harder to find.

Start with the question the visual needs to answer. If there isn't one, you probably don't need the visual.

## Use screenshots to show location or state

A screenshot is useful when readers need to recognize something they can see:

* Where a setting lives in a crowded interface
* Which status confirms that a deployment worked
* What a correctly configured screen looks like

Crop to the part that matters. A full-screen capture with one tiny button circled in red makes readers search the image before they can continue.

Skip the screenshot when the interface is simple enough to describe in a sentence, such as “Select **Settings**, then **API keys**.” Text is faster to scan, easier to update, and searchable.

## Use frames to give visuals context

`<Frame>` separates an image or video from the surrounding page and can add a caption:

```mdx theme={null}
<Frame caption="The repository appears as connected after installation">
  <img
    src="/images/github-app-settings.png"
    alt="GitHub App settings showing the documentation repository as connected"
  />
</Frame>
```

The alt text and caption have different jobs. Alt text conveys what a reader needs from the image. The caption explains why the image is here or points out something worth noticing. Repeating the same sentence in both doesn't help.

“Screenshot of dashboard” is weak alt text because it leaves out the useful part. “Deployment dashboard showing a successful production build” tells the reader which state the image demonstrates.

Use `alt=""` for a purely decorative image. For an instructional image, describe the information—not every color, border, and menu visible on the screen.

## Use diagrams to explain relationships

When the hard part is understanding how several things connect, a diagram is usually more helpful than a screenshot. Request flows, system boundaries, state changes, and branching processes are good candidates.

Mintlify renders Mermaid diagrams from a text definition, so you can review changes to the diagram alongside the rest of your content:

````mdx theme={null}
```mermaid
flowchart LR
  Edit[Edit a page] --> PR[Open a pull request]
  PR --> Preview[Review the preview]
  Preview --> Merge[Merge to main]
  Merge --> Live[Publish the live site]
```
````

This diagram is useful because the order and relationship between stages are the point. A screenshot of GitHub would show the interface, but not the workflow as clearly.

Introduce a diagram in the text and summarize its takeaway. That context helps everyone, including readers who use a screen reader or can't comfortably inspect a large diagram.

## Plan for the next product update

Before publishing a visual, ask what will make it stale. Screenshots often contain button labels, navigation, account data, dates, and feature states that change independently of the instructions.

Remove personal or internal information, and keep the source file for diagrams your team may need to update. During product reviews, check the visuals on every affected page—not only the prose around them.

<Quiz
  question="You need to explain how a request passes through an API gateway, an authentication service, and your application. Readers also need to understand what happens when authentication fails. What should you use?"
  answers={[
{ text: "A Mermaid flow or sequence diagram, introduced and summarized in the prose", correct: true },
{ text: "A screenshot of the API gateway dashboard with each service highlighted", correct: false },
{ text: "A table with one row per service and no representation of request order", correct: false },
{ text: "Three framed screenshots, because each service has a different interface", correct: false },
]}
  correctFeedback="Right. The reader needs to see order, relationships, and a failure path. A flow or sequence diagram communicates those directly, while the prose supplies the context and takeaway."
  incorrectFeedback="The interfaces aren't the important part here. Readers need to follow the request and see where it branches on failure, which is what a flow or sequence diagram is designed to show."
/>

Next up: [Cards as navigation](/courses/components/cards-navigation) — use visual weight to guide readers to another page.