Neo Dev Annotations

Neo Dev Annotations#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

Neo Dev Annotations is a development tool built into the host application. It lets you click any element in the running application, attach a note to it, and copy the collected notes as structured Markdown, with the component name, source file, line number, translation key, and design token of each annotated element.

The result is a set of precise references rather than a description such as “fix the blue button in the search header”, which is useful when handing work to an AI coding assistant such as Claude Code.

When It Is Available#

The toolbar is active in development only. It is never part of a production build.

Context	Activates when
Bundle development	You run `neo-ui dev` in your bundle.
Host development	You run the host application in development mode from the `web-client` repository.

In bundle development mode, the tool also reports the source file and line number of your own bundle components, not only of host components, because the development build adds the necessary metadata.

Two cases suppress the toolbar deliberately:

Browser automation. The toolbar does not mount when the browser reports itself as automated, so it never interferes with Playwright or similar end-to-end runs.
Per-developer opt-out. Set VITE_DISABLE_DEV_ANNOTATIONS in your local .env to hide the toolbar without changing anything for your colleagues.

Annotating an Element#

Open the toolbar by clicking the pencil button in the corner of the page, or by pressing Alt+A. The toolbar opens with inspect mode already active.
Move the pointer over the page. A highlight and a chip showing the component name follow the cursor.
Click any element. A note field opens, anchored to that element.
Type what you want changed.
Press Enter, or click Save. A numbered pin appears on the element.
Repeat for as many elements as you need.

Inspect mode stays active after each save, so you can annotate several elements in one pass. Close the toolbar when you are done.

Copying Annotations for Claude#

Click the copy button, or the annotation count, to copy every annotation as structured Markdown. Each entry looks like this:

## 1. "Make this title wrap instead of truncating"
- Element: `[data-testid="dashboard-title"]` — "Risk Monitor Overview"
- Component: `DashboardHeader` — `src/dashboards/header.tsx:23` (exact)
- Bundle: `acme-dashboards` / dashboard `risk-monitor`
- i18n: `ext-acme-dashboards:riskMonitor.title`
- Token: `text-foreground`

Paste that into your coding assistant. The file, line, and translation key let it open the right place directly.

Settings#

Open the settings button on the toolbar to change the following:

Setting	Default	Description
Clear annotations after copy	On	Removes the annotations once you copy them, treating the copy as a handoff.
Open Claude after copy	On	Opens Claude once the annotations are copied.
Include app state	On	Adds the current route, project ID, language, and color mode to the copied output.
Include computed styles	Off	Adds the computed CSS properties of each annotated element.
Show note text on pins	Off	Expands the numbered pins into labelled chips, so you can read each note without opening it.
Shortcut	`Alt+A`	The keyboard shortcut that toggles inspect mode.
Position	Bottom right	Moves the toolbar to the bottom left when it covers your content.

Keyboard Shortcuts#

Key	Action
`Alt+A`	Toggles inspect mode, including when the toolbar is closed.
`Escape`	Closes inspect mode, or dismisses the open note.
`Enter`	Saves the annotation you are typing.

Annotations after a Page Reload#

Annotations survive a page reload. The pins re-anchor to their elements once the page has rendered, which takes a moment. When an element can no longer be matched, because the component was renamed or the structure of the page changed, the annotation is reported as unanchored in the toolbar rather than being lost.

Troubleshooting#

Pins Do Not Appear After a Reload#

The components of the page have to render before the pins can re-anchor. Wait a moment after the application finishes loading. If the pins still do not appear, open the toolbar: the count shows how many annotations are stored.

A Component Name Appears but No File or Line#

File and line information is added by the development build only. A host component that comes from a production build shows the component name alone. That is expected.