Annotation Workflow

This guide covers the complete annotation lifecycle from creation to completion, including iteration with AI.

Overview

The annotation workflow follows this pattern:

Create → AI Implements → Review → Iterate or Complete

Phase 1: Create Annotations

Step 1: Identify What to Change

Review your UI and note what needs to change:

  • Text or copy updates
  • Spacing adjustments
  • Color changes
  • Layout modifications
  • Missing elements

Step 2: Create Annotations

For each change:

  1. Open Pointa sidebar
  2. Click the element
  3. Add clear, specific feedback
  4. Submit

Effective feedback examples:

  • "Change button text from 'Submit' to 'Save Changes'"
  • "Add 24px padding to this container"
  • "Make this heading blue (#3b82f6)"
  • "Center this content horizontally"

Step 3: Review Before Proceeding

Check the sidebar to see all your annotations. Make sure:

  • All intended changes are captured
  • Feedback is clear and specific
  • Nothing is missing

Phase 2: AI Implementation

Ask AI to Implement

Switch to your AI coding tool and request implementation:

Effective prompts:

  • "Implement the Pointa annotations"
  • "Check Pointa and implement all pending feedback"
  • "Work on the Pointa annotations for the dashboard page"

What AI Does

  1. Calls read_annotations to get your feedback
  2. Analyzes the element context
  3. Locates relevant code files
  4. Makes the requested changes
  5. Marks annotations as "in-review"

Monitor Progress

Watch as AI:

  • Reports which annotations it's processing
  • Shows the files it's modifying
  • Explains its implementation approach

Phase 3: Review Changes

Refresh and Check

  1. Refresh your development page
  2. Check each implemented change
  3. Compare against your original intent

In the Sidebar

Annotations move from "Active" to "To Review" tab.

Evaluate Each Change

For each annotation, decide:

  • ✅ Correct - Matches your intent
  • ⚠️ Needs adjustment - Close but needs tweaking
  • ❌ Incorrect - Misunderstood the request

Phase 4: Iterate or Complete

If Changes Are Correct

  1. Click the annotation in the sidebar
  2. Click Mark as Done (checkmark)
  3. Annotation is archived

If Changes Need Adjustment

  1. Click the annotation
  2. Add a follow-up comment:
    • "Make the padding 32px instead of 24px"
    • "Use a darker shade of blue"
    • "Also center it vertically"
  3. Submit
  4. Ask AI to implement again

AI sees the full conversation and understands the iteration.

If Changes Are Wrong

  1. Add a follow-up explaining the issue:
    • "This isn't the right element - I meant the header button"
    • "I wanted the background color, not the text color"
  2. Submit and re-ask AI

Multi-Annotation Workflow

Batch Processing

For efficiency:

  1. Add all annotations first (don't ask AI after each one)
  2. Ask AI to implement all at once
  3. Review all changes together
  4. Mark completed ones as done
  5. Iterate on ones that need adjustment

Prioritizing

You can guide AI:

  • "Start with the header annotations"
  • "Do the color changes first"
  • "Skip the footer for now"

Tips for Success

Write for AI Understanding

Remember AI reads your feedback literally:

  • Be specific about values
  • Use CSS/design terminology
  • Reference elements clearly

One Change Per Annotation

Keep annotations focused:

  • ✅ "Add 16px padding to this button"
  • ❌ "Make this button better with more padding, different color, and rounded corners"

Split complex changes into multiple annotations.

Use Screenshots When Helpful

Attach reference images for:

  • Design references
  • Before/after comparisons
  • External examples

Check Mobile Views

After AI implements, check responsive behavior:

  • Does it work on mobile?
  • Are there unexpected layout issues?
  • Add new annotations if needed

Common Patterns

Quick Text Changes

  1. Click text element
  2. "Change this to 'New Text'"
  3. AI implements
  4. Done

Style Adjustments

  1. Click element
  2. "Add padding: 16px, border-radius: 8px"
  3. AI implements
  4. Review and adjust if needed

Layout Changes

  1. Click container
  2. "Make this a flex container with gap: 16px"
  3. AI implements
  4. May need iteration for complex layouts

Related