PS Product SecurityKnowledge Base

🎨 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

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:

<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.