Visual Annotations

Annotations are the core feature of Pointa. Click any element on your page, leave feedback, and let your AI coding agent implement the changes.

Overview

Visual annotations let you:

  • Point to exactly what you want changed
  • Describe changes in natural language
  • Have iterative conversations with follow-up messages
  • Track status from pending to complete

Creating Annotations

Step 1: Activate Annotation Mode

Open the Pointa sidebar and click the Annotate button. Alternatively, just click anywhere on the page when the sidebar is open.

Step 2: Select an Element

Hover over elements - you'll see them highlight with a blue outline. Click to select the element you want to annotate.

Step 3: Add Your Feedback

A comment modal appears. Type your feedback or instructions:

Good examples:

  • "Change this button to blue"
  • "Add 16px padding on all sides"
  • "Make the font size 18px and bold"
  • "Center this text"
  • "Add a subtle shadow effect"

Even better examples (more specific):

  • "Change background to #3b82f6 (blue-500)"
  • "Add padding: 16px 24px"
  • "Use font-size: 18px, font-weight: 600"

Step 4: Submit

Click Submit to save the annotation. You'll see:

  • A numbered badge appears on the element
  • The annotation shows in the sidebar

Annotation Features

Multi-Turn Conversations

You can have ongoing conversations about an annotation. After AI implements your first request, you can add follow-up messages:

  1. Click the annotation badge or find it in the sidebar
  2. Add a new message with additional feedback
  3. AI will see the full conversation history

This is useful for:

  • Requesting adjustments to AI's implementation
  • Clarifying your original request
  • Adding new requirements

Image Attachments

You can attach images to annotations to provide visual references:

  1. While creating an annotation, click the image icon
  2. Upload a screenshot or design reference
  3. AI will see the attached image for context

Managing Annotations

View All Annotations

The sidebar shows all annotations for the current page. Use the page dropdown to switch between different routes in your application.

Filter by Status

The sidebar has two tabs:

  • Active: Pending annotations waiting for AI
  • To Review: Completed work ready for your review

Edit Annotations

Click any annotation badge or sidebar entry to:

  • View the full details
  • Add follow-up messages
  • Delete the annotation

Delete Annotations

Click the trash icon on an annotation to remove it. Deleted annotations cannot be recovered.

Annotation Badges

Badges appear on annotated elements to show:

  • A number (annotation index on the page)
  • Status indicator color

Badge Positioning

Badges automatically position themselves to avoid:

  • Overlapping with element content
  • Going off-screen
  • Covering important UI elements

Annotation Status Lifecycle

Status What It Means What You Do
Pending Waiting for AI to implement Ask AI to implement annotations
In Review AI completed the work Review changes, mark as done or add feedback
Done You confirmed it's complete Archived automatically

What AI Receives

When AI reads your annotations, it gets:

Data Description
Your comment The feedback you typed
Element selector CSS selector to find the element
Element classes CSS classes on the element
Element text Text content of the element
Element position Location and dimensions on page
Source file Detected source file path (when possible)
Framework hints React, Next.js, Vue, etc. detection

This context helps AI find the right code and make accurate changes.

Tips for Effective Annotations

Be Specific About Values

Less Effective More Effective
"Make this bigger" "Increase font-size to 24px"
"Add some space" "Add 16px margin-bottom"
"Make it look better" "Add border-radius: 8px and box-shadow"

Use Design Terminology

AI understands CSS and design terms:

  • Spacing: margin, padding, gap
  • Colors: hex codes, rgb, color names
  • Typography: font-size, font-weight, line-height
  • Layout: flex, grid, center, align

Reference Other Elements

You can mention other parts of your UI:

  • "Use the same style as the header button"
  • "Match the color scheme of the sidebar"
  • "Make this consistent with the other cards"

Batch Related Changes

You can add multiple annotations before asking AI to implement. This is efficient for related changes across a page.

Related Features