Annotations Guide

Add professional visual annotations to your documentation screenshots to highlight important UI elements and guide users through your interface.

Overview

Poliage supports several annotation types:

Highlights

Draw attention to specific areas with colored overlays

Arrows

Point to elements with customizable arrows

Callouts

Add numbered or lettered callout markers

Text Labels

Overlay explanatory text on screenshots

Configuration

Add annotations to any capture in your config:

{
  "name": "dashboard-annotated",
  "url": "https://app.example.com/dashboard",
  "annotations": [
    {
      "type": "highlight",
      "selector": ".sidebar-nav",
      "color": "blue",
      "opacity": 0.2
    },
    {
      "type": "callout",
      "selector": ".user-menu",
      "label": "1",
      "position": "top-right"
    }
  ]
}

Annotation Types

Highlight

Draws a colored overlay on an element.

{
  "type": "highlight",
  "selector": ".target-element",
  "color": "blue",
  "opacity": 0.3,
  "padding": 4
}

Options:

Property	Type	Default	Description
`selector`	string	—	CSS selector for target element
`color`	string	`"blue"`	Highlight color
`opacity`	number	`0.2`	Opacity (0-1)
`padding`	number	`0`	Padding around element
`borderRadius`	number	`4`	Corner radius

Available colors: blue, green, red, yellow, purple, orange, or any hex code.

Arrow

Draws an arrow pointing to an element.

{
  "type": "arrow",
  "selector": ".target-element",
  "from": { "x": -50, "y": -50 },
  "color": "red",
  "strokeWidth": 2
}

Options:

Property	Type	Default	Description
`selector`	string	—	CSS selector for target
`from`	`{x, y}`	auto	Arrow start position (relative to target)
`to`	`{x, y}`	auto	Arrow end position
`color`	string	`"red"`	Arrow color
`strokeWidth`	number	`2`	Line thickness
`headSize`	number	`8`	Arrowhead size

Callout

Adds a numbered or lettered marker.

{
  "type": "callout",
  "selector": ".target-element",
  "label": "1",
  "position": "top-right",
  "color": "blue"
}

Options:

Property	Type	Default	Description
`selector`	string	—	CSS selector for target
`label`	string	`"1"`	Callout text (number or letter)
`position`	string	`"top-right"`	Position relative to element
`color`	string	`"blue"`	Background color
`size`	number	`24`	Marker size in pixels

Positions: top-left, top-right, bottom-left, bottom-right, top-center, bottom-center

Text Label

Adds text overlay to the screenshot.

{
  "type": "text",
  "content": "Click here to start",
  "position": { "x": 100, "y": 50 },
  "style": {
    "fontSize": 14,
    "color": "#333",
    "backgroundColor": "#fff"
  }
}

Box

Draws a box outline around an element.

{
  "type": "box",
  "selector": ".important-section",
  "color": "green",
  "strokeWidth": 2,
  "style": "dashed"
}

Interactive Annotations

For complex annotations, use interactive mode:

poliage capture interactive

In the web interface:

Capture Your Screenshot

Navigate to the page and capture the base screenshot.

Add Annotations

Use the toolbar to add highlights, arrows, callouts, and text.

Adjust Styling

Customize colors, sizes, and positions visually.

Export Configuration

Save the annotation configuration for reproducible captures.

Best Practices

Keep it simple. Too many annotations make screenshots harder to understand, not easier. Focus on 1-3 key elements per screenshot.

Do's

✅ Use consistent colors throughout your documentation
✅ Number callouts in reading order (left-to-right, top-to-bottom)
✅ Add padding around highlights to avoid clipping text
✅ Use arrows sparingly for emphasis

Don'ts

❌ Overload screenshots with too many annotations
❌ Use clashing or low-contrast colors
❌ Place callouts that obscure important UI elements
❌ Mix different annotation styles inconsistently

Full Example

{
  "name": "onboarding-walkthrough",
  "url": "https://app.example.com/onboarding",
  "annotations": [
    {
      "type": "callout",
      "selector": ".step-1-input",
      "label": "1",
      "position": "top-left",
      "color": "blue"
    },
    {
      "type": "callout",
      "selector": ".step-2-button",
      "label": "2",
      "position": "top-left",
      "color": "blue"
    },
    {
      "type": "highlight",
      "selector": ".helper-text",
      "color": "yellow",
      "opacity": 0.3
    },
    {
      "type": "arrow",
      "selector": ".submit-button",
      "from": { "x": 100, "y": -30 },
      "color": "green"
    }
  ]
}