aradotso Agentation Visual Feedback
Skill by ara.so — AI Agent Skills collection.
Agentation is an agent-agnostic visual feedback tool that helps developers capture precise UI element references for AI coding agents. It provides click-to-annotate functionality with automatic selector identification, text selection, multi-select, and structured markdown output that includes selectors, positions, and context.
Installation
npm install agentation -D
For other package managers:
yarn add agentation -D
# or
pnpm add agentation -D
Basic Usage
React Integration
Add the Agentation component to your app:
import { Agentation } from 'agentation';
function App() {
return (
<>
<YourApp />
<Agentation />
</>
);
}
Next.js Integration
For Next.js apps, wrap in a client component:
// components/AgentationWrapper.tsx
'use client';
import { Agentation } from 'agentation';
export function AgentationWrapper() {
return <Agentation />;
}
Then add to your layout or page:
// app/layout.tsx
import { AgentationWrapper } from '@/components/AgentationWrapper';
export default function RootLayout({ children }) {
return (
<html>
<body>
{children}
<AgentationWrapper />
</body>
</html>
);
}
Conditional Loading (Development Only)
Only load Agentation in development:
import { Agentation } from 'agentation';
function App() {
return (
<>
<YourApp />
{process.env.NODE_ENV === 'development' && <Agentation />}
</>
);
}
Configuration
Basic Props
<Agentation
position="bottom-right" // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
theme="auto" // 'auto' | 'light' | 'dark'
defaultOpen={false} // Start with toolbar expanded
/>
Custom Styling
<Agentation
style={{
zIndex: 10000,
bottom: '20px',
right: '20px'
}}
/>
Features & Usage Patterns
Click to Annotate
- Click the Agentation toolbar button (bottom-right by default)
- Click any element on the page
- Add your feedback/note in the modal
- Copy the structured output with selectors
Example output format:
## Element: .sidebar > button.primary
**Selector:** `.sidebar > button.primary`
**Position:** x: 120, y: 340
**Note:** This button should be blue (#0066FF) instead of green
Text Selection Mode
Select specific text content for annotation:
- Activate Agentation
- Click and drag to select text
- Add annotation
- Get selector + text content in output
Multi-Select Mode
Select multiple related elements at once:
- Activate Agentation
- Hold Shift (or use multi-select button)
- Drag across multiple elements
- Annotate all selected elements together
Area Selection
Annotate regions or empty space:
- Activate Agentation
- Enable area mode
- Drag to create a selection box
- Annotate the entire region
Animation Pause
Freeze animations to capture specific states:
- Click the pause button in the toolbar
- All CSS animations, transitions, JS animations, and videos freeze
- Click elements in their paused state
- Resume animations when done
// Agentation automatically pauses:
// - CSS animations and transitions
// - requestAnimationFrame loops
// - Video playback
// - GIF animations
Working with AI Agents
Using Structured Output
When you copy annotations, Agentation provides:
## Feedback Report
### Element 1: Navigation Button
**Selector:** `nav.header > button[aria-label="Menu"]`
**Position:** x: 24, y: 16
**Classes:** `.btn-menu`, `.mobile-only`
**Note:** Button should have hover state with 0.2s transition
### Element 2: Card Title
**Selector:** `.card-container > .card-header > h3`
**Position:** x: 340, y: 280
**Text Content:** "Featured Product"
**Note:** Font size should be 24px, currently 18px
Providing Feedback to AI Agents
Best practices when using Agentation output with AI agents:
- Copy the full structured output - includes selectors agents can grep for
- Add specific requirements - color values, spacing, behavior
- Reference multiple elements - select related components together
- Capture animation states - pause animations at the exact frame you want
Example prompt to AI agent:
Here's feedback from Agentation:
[paste structured output]
Please update these components according to the notes. The selectors provided
should help you locate the exact code to modify.
TypeScript Support
Agentation is written in TypeScript and includes full type definitions:
import { Agentation } from 'agentation';
import type { AgentationProps } from 'agentation';
const config: AgentationProps = {
position: 'bottom-right',
theme: 'dark',
defaultOpen: false
};
function App() {
return <Agentation {...config} />;
}
Troubleshooting
Toolbar Not Visible
Issue: Agentation toolbar doesn't appear
Solutions:
- Check z-index conflicts - default is 999999
- Verify the component is rendered in the DOM
- Check for CSS that might hide fixed position elements
// Increase z-index if needed
<Agentation style={{ zIndex: 10000000 }} />
Elements Not Selectable
Issue: Can't click or select certain elements
Solutions:
- Check for overlays or modals with higher z-index
- Verify elements aren't hidden by pointer-events: none
- Try area selection mode for hard-to-click elements
Selectors Too Generic
Issue: Generated selectors like div > div > span aren't useful
Solutions:
- Add meaningful class names to your components
- Use semantic HTML elements
- Add data attributes for better selector generation
// Better markup for Agentation
<div className="product-card" data-testid="product-card">
<h3 className="product-title">Title</h3>
<button className="add-to-cart-btn">Add to Cart</button>
</div>
Performance Issues
Issue: App slows down when Agentation is active
Solutions:
- Only load in development environments
- Disable animation pause if not needed
- Check for extremely deep DOM trees
// Load only in development
{process.env.NODE_ENV === 'development' && <Agentation />}
Dark Mode Not Matching
Issue: Agentation theme doesn't match app theme
Solutions:
- Manually set theme prop
- Ensure prefers-color-scheme is set correctly
- Check for theme overrides in CSS
// Force specific theme
<Agentation theme="dark" />
Browser Support
Agentation requires:
- Modern desktop browser (Chrome, Firefox, Safari, Edge)
- JavaScript enabled
- No mobile support (desktop only)
Common Integration Patterns
With Vite
// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { Agentation } from 'agentation';
import App from './App';
createRoot(document.getElementById('root')!).render(
<StrictMode>
<App />
{import.meta.env.DEV && <Agentation />}
</StrictMode>
);
With Create React App
// index.tsx
import { Agentation } from 'agentation';
import App from './App';
root.render(
<React.StrictMode>
<App />
{process.env.NODE_ENV === 'development' && <Agentation />}
</React.StrictMode>
);
With Remix
// app/root.tsx
import { Agentation } from 'agentation';
export default function App() {
return (
<html>
<head>
<Meta />
<Links />
</head>
<body>
<Outlet />
<ScrollRestoration />
<Scripts />
<LiveReload />
{process.env.NODE_ENV === 'development' && <Agentation />}
</body>
</html>
);
}
License
PolyForm Shield 1.0.0 - Free for non-commercial use. Check the license for commercial usage terms.