Pixel-perfect UI feedback for AI agents. Inspect your live site, pin notes to any element, and copy feedback your agent can act on.
pixelspec.dev · Install · How to use it · Copy for AI
PixelSpec is a free, open-source design QA tool that runs as an overlay on your website in development. Measure padding, margin, gaps and the distance between elements, check typography and color contrast, and click any element to leave a note. Then copy every note as a compact prompt with the selector, component, size and styles, and paste it into Claude Code, Cursor, Codex, Copilot or any AI coding agent.
- Designers doing design QA on the real build. Check spacing, type and color on the shipped page and leave notes on the exact element instead of sending annotated screenshots.
- Vibe coders building with AI. Stop describing visual bugs in words. Click the element, say what should change, and your agent gets the selector and styles it needs to fix it in one pass.
- Frontend developers who want a fast spacing inspector and pixel-perfect redlines without opening DevTools.
- Exact, not approximate. Real computed values from the browser: padding, margin, gap, redline distances, font, line height, letter spacing, colors and WCAG contrast.
- Made for your agent. Feedback copies as two compact lines per element to save tokens, or as full Markdown.
- Invisible to your app. It lives in its own shadow root, has zero runtime dependencies and is about 28 KB gzipped. Load it in development only.
- Works everywhere. Any site and any framework: React, Next.js, Vite, Vue, Svelte or plain HTML. React, Vue and Svelte component names are detected automatically.
Pick the setup that matches your project. All three take under a minute.
npm install -D pixelspecimport { PixelSpec } from 'pixelspec/react';
export default function App() {
return (
<>
<YourApp />
{process.env.NODE_ENV === 'development' && <PixelSpec />}
</>
);
}In the Next.js App Router, render it from a 'use client' component, for example in your root layout.
npm install -D pixelspec// main.ts
if (import.meta.env.DEV) {
import('pixelspec').then(({ init }) => init());
}Add one line before </body>:
<script src="https://unpkg.com/pixelspec"></script>To work offline, download pixelspec.global.js from the latest release and point the src at it.
Optional attributes: data-active="true" to start open, data-hotkey="alt+shift+i", data-position="bottom-left" and data-ai-detail="full".
Then open your page. Click the PixelSpec button in the bottom-right corner, or press Alt+Shift+I.
- Hover anything to see its name and size.
- Click an element. A popover opens where you clicked, with the key specs: size, padding, margin, gap, layout, font, color, contrast, radius and shadow. Click any value to copy it. The spacing icons use the overlay colors: green is padding, orange is margin, pink is gap.
- Hover another element to see red redline distances. Hold Alt to measure to the parent.
- Type feedback and press Enter. A numbered marker appears on the element. Hover a marker to read the note, click it to edit or delete.
- Select text on the page to leave feedback that quotes it.
- Copy with the toolbar's copy button or C, and paste it into your agent.
In the popover header, click the element name to copy its selector, or the code icon to copy its CSS. "All properties" opens the full list: box model, every flex and grid property, full typography, colors, appearance, accessibility and attributes.
The toolbar stays pinned to its corner (bottom right by default, or position: 'bottom-left').
| Button | Key | What it does |
|---|---|---|
| Spacing overlay | S | Box model and pink gap hatching on the selected element |
| Guides | G | Crosshair with coordinates and edge guides |
| Pause animations | P | Freezes CSS animations, transitions and videos |
| Hide markers | H | Shown once you have feedback |
| Copy feedback | C | Copies all feedback. The badge shows the count |
| Clear all | X | Clears all feedback, with Undo |
| Settings | Copy detail, overlays, clear after copy | |
| Close | Esc | Esc closes the popover first, then the toolbar |
In the popover, ↑ ↓ ← → walk to the parent, child and siblings while the feedback box is empty. Shift+Enter adds a new line.
Your work is protected. A stray click never throws away feedback you are typing; the popover shakes instead. Deleting and clearing can be undone. Feedback survives page reloads and hot reloads.
While the toolbar is open, clicks on the page are blocked so links and buttons don't fire. Text selection still works.
Copied feedback uses a compact format by default to save tokens. It has two lines per element and only non-default values:
UI feedback for /pricing (1440×900):
1. Make this button bigger
body>header>button.cta "Start free trial"
126×34 p:10 18 r:999 | system-ui 14/14 w600 ls:0.01em | c:#FFF bg:#3581F6 contrast:3.7(fails AA)
Key: p padding, m margin, b border, r radius, 14/14 w600 size/line-height and weight, ls letter spacing, c text color, bg background. Contrast only appears when it fails AA. Containers skip text and typography.
For the full Markdown version, switch to Full in settings, hold Shift while copying, or set aiDetail: 'full'. It adds page position, layout details, shadows and the full contrast result, at roughly 2.5 times the length.
init({
hotkey: 'alt+shift+i', // modifiers: alt, shift, ctrl, meta, mod (Ctrl or ⌘)
startActive: false,
showToolbar: true,
position: 'bottom-right', // or 'bottom-left'
aiDetail: 'compact', // starting value; users can change it in settings
persist: true, // remember settings, toolbar position and feedback
onCopy: (text, kind) => {}, // kind: 'value' | 'css' | 'ai' | 'selector' | 'notes'
});The React component takes the same options as props, plus enabled. The instance returned by init() has activate(), deactivate(), toggle(), select(el), getNotes(), notesMarkdown() and destroy().
- Contrast ignores background images and element opacity, and says so in the popover.
- Feedback is matched back to elements by selector after a reload, so it can land on the wrong element if the page structure changed.
- Rendered font detection is a heuristic based on loaded font faces and canvas measurement.
- Component source paths need a dev build. React 19 removed
_debugSource, so React 19 shows names only. - Elements inside closed shadow roots and cross-origin iframes can't be inspected.
- Needs a browser with CSS
color-mix(): Chrome 111, Safari 16.2, Firefox 113 or newer.
Contributions are welcome. See CONTRIBUTING.md for how to run it locally and how the code is laid out.
git clone https://github.com/yesith0106/pixelspec.git
cd pixelspec
npm install
npm run demo # http://localhost:5178/demo/MIT. Free for personal and commercial use.