# Visual Style Guide

> **Intro:** This archive is designed to look clean in GitBook and still read well in plain Markdown. Styling choices are deliberately conservative so that content survives export, import, and offline viewing.
>
> **What this page includes**
>
> * page structure conventions
> * typography choices for SVG assets
> * icon and emoji usage guidance
>
> **Working assumptions**
>
> * readability beats novelty
> * diagrams should help a reader think, not compete with the text

## Page pattern

Most pages should use the following order:

1. title
2. one diagram only when it clarifies the topic
3. an intro block with three parts:
   * **Intro**
   * **What this page includes**
   * **Working assumptions**
4. body sections with concise tables and code
5. section-end footer

## Typography

SVG decorative assets in this archive use the following font stack:

`Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`

Use:

* strong weight for headings
* regular weight for body lines
* enough whitespace inside boxes and banners
* no cramped text blocks inside diagrams

## Emoji and icons

Small icons are welcome in:

* top-level section headings
* summary pages
* a few high-signal subheadings

Avoid using icons on every single heading. Use them where they improve scanning speed.

## Color and diagram rules

* prefer calm neutrals with one accent color per diagram
* do not overuse gradients
* keep labels short enough to avoid line-wrap collisions
* use large hit areas and generous padding for cards and boxes

![Footer](/files/fQNzMAKOWjRP989toSYF)

## Collapsible blocks

Use HTML `<details>` blocks when all of the following are true:

* the content is **useful but secondary on first read**
* the section is **answer-heavy**, such as interview packs, QA walkthroughs, or finding-by-finding commentary
* the hidden block does **not contain essential navigation or the only copy of a critical instruction**

Recommended pattern:

```html
<details>
<summary><strong>Reveal the worked answer</strong></summary>

Hidden explanation, tradeoffs, and implementation notes go here.

</details>
```

Default to **closed** spoilers. Use them to reduce visual noise, not to hide essential context.

## Emphasis and typography in Markdown

* use **bold** for the decision, control, or take-away
* use *italics* for nuance, judgment, or a conditional note
* use `<u>underline</u>` sparingly for a phrase the reader must not miss
* avoid stacking bold + italics + underline on the same sentence unless there is a real need
* prefer short lead-in labels such as **Why it matters**, **Short fix**, **Watch for**, **Operator note**

## Captions and labels

Give diagrams short, functional captions:

* **GitLab runner trust zones**
* **Vault request and lease flow**
* **Mobile release gate**
* **OPA admission decision path**

Keep captions short enough to survive GitBook sidebars and narrow reading widths.

## GitBook presentation refresh notes

* prefer **one strong hero image** per landing/index page instead of many competing graphics;
* keep **muted colors**, strong typography, and clear section dividers;
* use **section maps**, **start-here tables**, and **related-section links** to reduce cognitive load;
* keep long dense technical pages content-first; do not overload them with decorative elements.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.product-security.expert/appendices-assets-and-reusable-artifacts/reading-paths/visual-style-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.