🟥 UI-Referee

Visual UI Annotation SDK for AI Coding Agents

Click any element on any webpage. Leave a note. Export structured, AI-ready context in one click.

Works with →

What is UI-Referee?

UI-Referee is a single JavaScript file you drop into any webpage.
It injects a floating toolbar that lets you:

Flag any element on the page with a click
Describe the change you want in plain English
Export a structured JSON payload or a ready-to-paste AI prompt

No build tools. No npm. No React. No backend. No accounts.
It just works — on any site, any stack, any browser.

Quick Start

CDN (recommended — no install)

<script src="https://idiotinnovators.com/ui-referee.js"></script>

Drop this tag anywhere in your HTML — <head> or before </body>.
UI-Referee auto-initialises. The toolbar appears in the bottom-right corner.

Self-hosted

# Download the single file
curl -o ui-referee.js https://idiotinnovators.com/ui-referee.js

<script src="/path/to/ui-referee.js"></script>

Bookmarklet (annotate any site)

Create a browser bookmark and set the URL to:

javascript:(function(){var s=document.createElement('script');s.src='https://idiotinnovators.com/ui-referee.js';document.head.appendChild(s);})();

Click the bookmark on any webpage to inject UI-Referee on the fly.

How It Works

┌─────────────────────────────────────────────────────────────┐
│  1. Open any webpage                                        │
│  2. Click  🚩 Flag Element  in the toolbar                  │
│  3. Hover over elements  →  red dashed highlight appears    │
│  4. Click the element you want to annotate                  │
│  5. Type your instruction in the modal  →  Save Flag        │
│  6. Repeat for all elements that need changes               │
│  7. Click  ↗ Export  →  copy JSON or AI Prompt             │
│  8. Paste the prompt into Claude Code, Cursor, Cline, etc.  │
└─────────────────────────────────────────────────────────────┘

Features

🚩 Floating Toolbar

Injected into any page at z-index: 2,147,483,000 — always on top, never breaks layout.

Button	Action
🚩 Flag Element	Toggle annotation mode
↗ Export `n`	Open export modal (JSON + AI Prompt)
✕	Clear all flags

Keyboard shortcut: Alt + A — toggle annotation mode from anywhere.

🎯 Smart Element Selection

When annotation mode is active, hover any element to see a red dashed outline and a tag label showing <tag>#id.class.

Clicking opens the annotation modal, which shows:

Tag name
ID attribute
Class list
Auto-generated CSS selector
Visible text content

🔍 Smart Selector Generator

UI-Referee builds the shortest, most reliable CSS selector for each element:

Priority	Example
Unique `id`	`#submit-btn`
`data-testid`	`[data-testid="checkout-btn"]`
`data-cy`	`[data-cy="nav-link"]`
`data-test`	`[data-test="hero-cta"]`
Parent + class chain	`.hero .btn-primary`
`nth-of-type` fallback	`body > div:nth-of-type(2) > button`

📄 Export: JSON

{
  "meta": {
    "tool": "UI-Referee",
    "version": "1.0.0",
    "cdn": "https://idiotinnovators.com/ui-referee.js"
  },
  "page": {
    "url": "https://example.com/pricing",
    "title": "Pricing — Example"
  },
  "annotations": [
    {
      "id": "ref_abc123",
      "timestamp": 1719000000000,
      "selector": "#pricing-cta",
      "tag": "button",
      "idAttribute": "pricing-cta",
      "classes": ["btn", "btn-primary", "btn-lg"],
      "text": "Start Free Trial",
      "note": "Change text to 'Get Started Free' and make the background #00c853",
      "pageUrl": "https://example.com/pricing",
      "pageTitle": "Pricing — Example",
      "context": {
        "outerHTML": "<button id=\"pricing-cta\" class=\"btn btn-primary btn-lg\">Start Free Trial</button>",
        "innerText": "Start Free Trial",
        "parentHTML": "...",
        "boundingRect": { "top": 480, "left": 640, "width": 200, "height": 48 },
        "computedStyles": {
          "display": "inline-flex",
          "position": "static",
          "width": "200px",
          "height": "48px",
          "color": "rgb(255,255,255)",
          "backgroundColor": "rgb(232,0,28)",
          "fontSize": "16px"
        }
      }
    }
  ]
}

🤖 Export: AI Prompt

Produces a structured, agent-ready prompt:

# UI-Referee — AI Agent Change Request

You are an expert frontend developer modifying a live webpage.
Below are flagged UI elements with specific change instructions.
Implement all changes, producing production-ready code.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
PAGE CONTEXT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title : Pricing — Example
URL   : https://example.com/pricing
Flags : 2

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FLAG 1 of 2
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Selector : #pricing-cta
Tag      : <button>
...

── Requested Change ──
Change text to 'Get Started Free' and make the background #00c853

🔢 Numbered Badges

After saving a flag, a small red numbered badge appears on the annotated element.
Badges reposition automatically on scroll and window resize.
Click a badge to see a toast with its note.

💾 Persistence

Annotations are saved to localStorage under the key uireferee_annotations.
Reload the page — your flags are still there.

JavaScript API

UI-Referee exposes a global UIReferee object:

// Auto-initialised on load — call manually only if needed
UIReferee.init()

// Annotation mode
UIReferee.enable()        // enter annotation mode
UIReferee.disable()       // exit annotation mode

// Export
UIReferee.exportJSON()    // download ui-referee-annotations.json
UIReferee.exportPrompt()  // copy AI prompt to clipboard

// Data
UIReferee.getAnnotations() // returns array of annotation objects
UIReferee.clear()          // clears all annotations + localStorage

// Meta
UIReferee.version          // "1.0.0"

Example: Programmatic annotation on a specific element

// You can trigger annotation on any element via the internal SDK:
const el = document.querySelector('#my-button');
UIReferee._sdk.addAnnotation(el, 'Change this button color to green');

Example: Export and send to your own backend

const json = JSON.parse(UIReferee._sdk.exportJSON(false));

fetch('/api/annotations', {
  method : 'POST',
  headers: { 'Content-Type': 'application/json' },
  body   : JSON.stringify(json),
});

Using the Exported Prompt with AI Agents

Claude Code (CLI)

# Paste the exported prompt directly into Claude Code
claude "$(pbpaste)"     # macOS — pbpaste reads clipboard
claude "$(xclip -o)"   # Linux

Cursor / Windsurf / Cline / Roo Code

Click ↗ Export → AI Prompt → ⎘ Copy Prompt
Open your AI agent's chat panel
Paste — the agent will implement all flagged changes

Gemini CLI

gemini -p "$(pbpaste)"

OpenAI Codex / API

const prompt = UIReferee._sdk.exportPrompt(false);

const response = await openai.chat.completions.create({
  model   : 'gpt-4o',
  messages: [{ role: 'user', content: prompt }],
});

Data Model Reference

Each annotation object has this shape:

interface Annotation {
  id          : string;       // "ref_abc123def"
  timestamp   : number;       // Unix ms
  selector    : string;       // "#submit-btn"
  tag         : string;       // "button"
  idAttribute : string;       // "submit-btn"
  classes     : string[];     // ["btn", "btn-primary"]
  text        : string;       // Visible text (max 300 chars)
  note        : string;       // Your instruction
  pageUrl     : string;       // Current page URL
  pageTitle   : string;       // document.title

  context: {
    outerHTML   : string;     // Element's HTML (max 2000 chars)
    innerText   : string;     // Visible text (max 500 chars)
    parentHTML  : string;     // Parent element HTML
    boundingRect: {
      top: number; left: number;
      width: number; height: number;
    };
    computedStyles: {
      display: string; position: string;
      width: string;   height: string;
      color: string;   backgroundColor: string;
      margin: string;  padding: string;
      fontSize: string;
    };
  };
}

Browser Support

Browser	Support
Chrome 90+	✅ Full
Firefox 88+	✅ Full
Safari 14+	✅ Full
Edge 90+	✅ Full
Opera 76+	✅ Full

Requires: CSS.escape, getBoundingClientRect, localStorage, Blob / URL.createObjectURL.

Contributing

Contributions are welcome!

git clone https://github.com/idiotinnovators/ui-referee.git
cd ui-referee

# Edit the single source file
code ui-referee.js

# Test by opening the example page
open examples/basic.html

Please read CONTRIBUTING.md before opening a pull request.

Changelog

v1.0.0 — Initial Release

Floating toolbar with flag / export / clear
Hover highlight with element tag label
Annotation modal with smart selector generation
JSON export with full DOM context
AI-prompt export (Claude Code, Cursor, Windsurf, Cline, Gemini CLI, Codex)
Numbered badges with scroll repositioning
localStorage persistence across page reloads
Alt+A keyboard shortcut
Bookmarklet support
Zero dependencies · single file · ~18kb

License

⬆ Back to top

Made with love by Idiot Innovators Research And Development · CDN: https://idiotinnovators.com/ui-referee.js

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
basic.html		basic.html
demo.gif		demo.gif
ui-referee.js		ui-referee.js

Folders and files

Latest commit

History

Repository files navigation

🟥 UI-Referee

What is UI-Referee?

Quick Start

CDN (recommended — no install)

Self-hosted

Bookmarklet (annotate any site)

How It Works

Features

🚩 Floating Toolbar

🎯 Smart Element Selection

🔍 Smart Selector Generator

📄 Export: JSON

🤖 Export: AI Prompt

🔢 Numbered Badges

💾 Persistence

JavaScript API

Example: Programmatic annotation on a specific element

Example: Export and send to your own backend

Using the Exported Prompt with AI Agents

Claude Code (CLI)

Cursor / Windsurf / Cline / Roo Code

Gemini CLI

OpenAI Codex / API

Data Model Reference

Browser Support

Contributing

Changelog

v1.0.0 — Initial Release

License

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages